feat: GitHub-style alert admonitions + contributor guide#44
Merged
Conversation
Render `> [!NOTE]` / `[!TIP]` / `[!IMPORTANT]` / `[!WARNING]` / `[!CAUTION]` blockquotes as styled callouts via a Goldmark blockquote render hook, with a plain-blockquote fallback for ordinary quotes. Limited to GitHub's five canonical alert types so the same Markdown renders identically in a GitHub issue/PR and on the site, matching the article submission flow. Styling ships in a theme-owned stylesheet. Also adds the how-to-write contributor guide, which dogfoods [!IMPORTANT] and [!TIP]. See docs/adr/0004-github-alert-admonitions.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
✅ Deploy Preview for powershellorg ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
- Alert title: tighter spacing, uppercase label, filled circular icon badge as a stronger per-type visual indicator. - Highlighted (.highlight) code blocks: trim the inherited .prose pre padding/margins so server-side Chroma blocks no longer read as a wall of whitespace; line numbers retained. - Update contributor guide article and Front Matter CMS config. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds GitHub-style alert admonitions to the site and the "How to Write for PowerShell.org" contributor guide that uses them.
Authors write the standard GitHub alert syntax:
…and a Goldmark blockquote render hook turns it into a styled callout. Ordinary blockquotes are untouched.
Why limited to GitHub's 5 types
Articles are submitted as plain Markdown — pasted into a GitHub issue (no-Git path) or as a Markdown file in a PR — so the Markdown is read on GitHub before it is ever read on the site. GitHub natively renders exactly five alert types (
NOTE,TIP,IMPORTANT,WARNING,CAUTION); anything beyond that degrades to a literal[!SUCCESS]blockquote there. Supporting only the five keeps the rendering identical in the issue form, the PR diff, and the published page. Full rationale indocs/adr/0004-github-alert-admonitions.md.Changes
layouts/_markup/render-blockquote.html— render hook: 5 alert types → Font Awesome icon + label (honors an optional custom title); plain-blockquote fallback.static/css/alerts.css—.ps-alertbase + 5 variants (GitHub light-mode palette). Title uses a tight, uppercase label with a filled circular icon badge as the per-type visual indicator. Theme-owned, linked frombaseof.html.docs/adr/0004-github-alert-admonitions.md— records the syntax/type-cap decision and why the existingterminalshortcode convention was deliberately not extended.content/articles/2026-06-23-how-to-write-for-powershell-org.md— new contributor guide; dogfoods[!IMPORTANT]and[!TIP].Drive-by polish (same article)
baseof.html— trimmed the inherited.prose prepadding/margins on Hugo/Chroma.highlightcode blocks, which had been rendering as a wall of whitespace. Line numbers are retained.frontmatter.json— Front Matter CMS config touch-ups.Verification
hugo --gc --minifybuilds clean (pre-existinglanguageCodedeprecation only).hugo server: both alerts render as.ps-alert-*, the stylesheet ships and is linked, the article's category-list blockquote stays a plain<blockquote>(fallback intact), and code blocks render tighter.🤖 Generated with Claude Code