docs: convert to portable Markdown and wire docs.docker.com validation#3411
Closed
dgageot wants to merge 3 commits into
Closed
docs: convert to portable Markdown and wire docs.docker.com validation#3411dgageot wants to merge 3 commits into
dgageot wants to merge 3 commits into
Conversation
rumpl
previously approved these changes
Jul 2, 2026
Contributor
|
👋 This PR has merge conflicts with the base branch. Please rebase or merge the latest base branch and resolve them. I've moved it to draft and added |
Prepare docs/ for mounting on docs.docker.com as a Hugo module (docker#3371): - replace Liquid relative_url links with plain relative Markdown links - drop permalink front matter (URLs already match file paths) - convert callout divs to GitHub-style > [!NOTE]/[!TIP]/[!WARNING] alerts - replace card/feature grid HTML with portable Markdown on content pages - add keywords front matter - fix broken anchors and root-absolute links - update markdownlint config and STYLE.md for the new conventions Assisted-By: Claude (Anthropic)
Kramdown renders > [!NOTE] as a plain blockquote; upgrade it client-side to the existing callout panels so github.io keeps the docs.docker.com look. Assisted-By: Claude (Anthropic)
Add markdownlint + offline link check on docs/**, and run docker/docs' reusable validate-upstream workflow (no-op until docker/docs mounts the docker-agent module, phase 2.1 of docker#3371). Assisted-By: Claude (Anthropic)
529a32c to
60f8927
Compare
docker-agent
reviewed
Jul 2, 2026
docker-agent
left a comment
Contributor
There was a problem hiding this comment.
Assessment: 🟢 APPROVE
Reviewed 97 changed files (docs content conversions, CI workflows, JS alert-upgrade function, markdownlint config). No bugs or correctness issues were introduced by this PR.
The Liquid-to-portable-Markdown conversion, > [!NOTE/TIP/WARNING] alert syntax, CI workflow configuration, and the upgradeAlerts() JavaScript function all look correct. The relative-link rewrites, front-matter changes, and lychee/markdownlint CI additions are clean.
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
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.
This implements the docker-agent-side work for Phase 1 and Phase 2.2 of #3371, which enables the docs to be single-sourced across github.io and docs.docker.com via a Hugo module mount. The two sites have different rendering pipelines, and the existing Liquid-template links, callout divs, and permalink declarations are incompatible with Hugo, so they need to be replaced with constructs that both engines understand natively.
The first commit converts 91 content files to portable Markdown. All 292
{{ '…' | relative_url }}links are replaced with plain relative links (resolved by jekyll-relative-links on github.io, natively by Hugo on docs.docker.com). The 186 Liquid callout<div>blocks become GitHub-style> [!NOTE]/> [!TIP]/> [!WARNING]alerts that Hugo understands out of the box. Card and feature-grid HTML on content pages is converted to Markdown lists; the landing page keeps its HTML but is now Liquid-free. Redundantpermalink:front matter is dropped,keywords:entries are added, and a small number of broken anchors and root-absolute links are fixed. STYLE.md and the markdownlint config are updated for the new conventions. Jekyll rendered a byte-identical 92-page URL set before and after this change.The second commit makes the GitHub-style alerts render correctly on the existing Jekyll site. Kramdown emits
> [!NOTE]as a plain blockquote rather than a styled panel, so a smallupgradeAlerts()function inapp.jsupgrades the rendered blockquote to the existing callout panel style client-side, without re-parsing innerHTML and matching only direct-child<p>markers to avoid false positives.The third commit adds CI coverage: a
docs.ymlworkflow runs markdownlint and an offline lychee link check (with fragment validation) on every docs change, and adocs-upstream.ymlworkflow calls docker/docs' reusablevalidate-upstreamworkflow (SHA-pinned) so the mount configuration can be validated automatically once Phase 2.1 lands in docker/docs.Part of #3371.