Skip to content

docs: convert to portable Markdown and wire docs.docker.com validation#3411

Closed
dgageot wants to merge 3 commits into
docker:mainfrom
dgageot:docs-portable-markdown
Closed

docs: convert to portable Markdown and wire docs.docker.com validation#3411
dgageot wants to merge 3 commits into
docker:mainfrom
dgageot:docs-portable-markdown

Conversation

@dgageot

@dgageot dgageot commented Jul 2, 2026

Copy link
Copy Markdown
Member

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. Redundant permalink: 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 small upgradeAlerts() function in app.js upgrades 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.yml workflow runs markdownlint and an offline lychee link check (with fragment validation) on every docs change, and a docs-upstream.yml workflow calls docker/docs' reusable validate-upstream workflow (SHA-pinned) so the mount configuration can be validated automatically once Phase 2.1 lands in docker/docs.

Part of #3371.

@dgageot dgageot requested a review from a team as a code owner July 2, 2026 11:14
rumpl
rumpl previously approved these changes Jul 2, 2026
@aheritier aheritier added area/ci CI/CD workflows and pipeline area/docs Documentation changes kind/docs Documentation-only changes status/needs-rebase PR has merge conflicts or is out of date with main labels Jul 2, 2026
@aheritier aheritier marked this pull request as draft July 2, 2026 11:33
@aheritier

Copy link
Copy Markdown
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 status/needs-rebase; it'll be picked back up automatically once the conflicts are cleared.

dgageot added 3 commits July 2, 2026 13:33
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)
@dgageot dgageot force-pushed the docs-portable-markdown branch from 529a32c to 60f8927 Compare July 2, 2026 11:36
@dgageot dgageot marked this pull request as ready for review July 2, 2026 11:37

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@dgageot dgageot closed this Jul 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/ci CI/CD workflows and pipeline area/docs Documentation changes kind/docs Documentation-only changes status/needs-rebase PR has merge conflicts or is out of date with main

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants