docs: render Hyak shared-resource callout as an admonition - #2485
Merged
Conversation
The `> [!IMPORTANT]` block in Computing-Hardware.md used GitHub-flavored alert syntax, which mkdocs.yml has no extension to render. On the published site it showed up as a blockquote containing the literal text "[!IMPORTANT]". Converted it to the `!!! important` admonition syntax, which the already- enabled `admonition` extension renders natively. This was the only GFM alert in docs/, so converting it avoids adding a new build dependency (github-callouts) to both mkdocs.yml and the deploy workflow. Co-Authored-By: Claude Opus 5 <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 changed
Converted the
> [!IMPORTANT]block indocs/Computing-Hardware.md(the Hyak/Klonecpu-g2shared-resource note) from GitHub-flavored alert syntax to the!!! importantadmonition syntax.Why
mkdocs.ymldoesn't enable an extension that understands GFM alerts, so the marker was passed through as plain text. On the published site the block rendered as a blockquote whose first line was the literal string[!IMPORTANT]— see Computing-Hardware.The
admonitionextension is already enabled, so!!!blocks render correctly today.Why this approach over adding
github-calloutsA grep of
docs/turned up exactly one GFM alert, this one. The other[!matches (indocs/Lab-Notebooks.md) are false positives — they're[![shields.io badge]](url)image links, not alerts.protocols/andREADME.mdare clean too.With a single occurrence, adding the
github-calloutsextension would have meant a new third-party dependency in bothmkdocs.ymland thepip installline of.github/workflows/mkdocs-material-theme.yml— i.e. on the deploy path — to fix one blockquote. Converting in place uses what's already configured and touches one file.Verification
Built locally with the same stack the workflow installs (
mkdocs-material mkdocs-video mkdocs-git-latest-changes-plugin):bio_Basics.md,klone_Conda.md, andklone_RStudio-Server.md, unrelated to this change and present beforehand.grep -rn '\[!' site/ --include='*.html'returns zero matches.<div class="admonition important">with an "Important" title; the nested####heading and the shared-resource contributions table both render properly inside the admonition rather than as literal text.Note for the reviewer
Material styles
importantas a tip variant (green), not GitHub's purple. Content and structure are correct; only the accent color differs from how this looks on github.com. If an amber caution treatment reads better here,!!! warningis a one-word change.🤖 Generated with Claude Code