mirror of
https://github.com/docker/docs.git
synced 2026-06-19 07:35:16 +00:00
Brandon Hunt
a78c3c7e8c
Two related style-conformance fixes across `content/guides/`, motivated by a recent audit of guide-page style against STYLE.md, COMPONENTS.md, and AGENTS.md. ## What changed ### 1. Add missing `keywords:` frontmatter to 104 guide pages `keywords` is documented as required (AGENTS.md, COMPONENTS.md) but was missing from 10 single-file guides, 8 `_index.md` landing pages, and 86 chapter pages. Each page now has a meaningful, page-specific comma-separated keyword list derived from its title, lead content, and sibling pages where applicable. Examples of the convention applied: - `content/guides/testcontainers-java-spring-boot-kafka/create-project.md` — `testcontainers, java, spring boot, kafka, mysql, project setup` - `content/guides/docker-compose/why.md` — `docker compose, multi-container, yaml, services, orchestration, application` Post-change verification confirms zero guide pages under `content/guides/` are missing the field. ### 2. Remove bold-for-emphasis from 14 guide pages STYLE.md restricts bold to UI elements only — never for emphasis, product names, command names, or the `**Term**: description` subsection-label pattern. Cleaned up the top-15 offender files identified by raw bold-span count (code blocks excluded). One file (`jupyter.md`, 32 spans) was untouched because all spans were legitimate UI references. Shape of the work across 14 files: - ~60 `**Term**: description` list items de-bolded - ~10 identifiers/values/commands converted to backticks (e.g. `**my-mysql**` → `` `my-mysql` ``) - ~10 product/emphasis bolds removed - 6 bolded link texts un-bolded - 3 blockquote-style notes converted to `> [!NOTE]` callouts Legitimate UI bolds (button names, menu items, field labels, tab names) were preserved throughout. `databases.md` kept 47 of 49 spans for this reason — only port-mapping value and container name were converted to backticks. ## Out of scope The audit surfaced other items not addressed here: - Series `params` block missing on all 48 `_index.md` landing pages — this is a "decide what's authoritative" question that warrants discussion before code changes. - Vale prose violations (`just`, `easily`, `we`, etc.) — concentrated in ~5 files; can land separately. - Heading numbering convention (`## Step N:` vs `## N.` vs plain) — undocumented; should be pinned down in STYLE.md or COMPONENTS.md before mechanical sweeps. ## Verification - `markdownlint` (via `scripts/lint.sh`) clean on all changed files. - Vale not installed locally; relying on CI to validate prose. - `git diff --stat` confirms scope: 118 unique files, all under `content/guides/`. No vendored, layout, or generated-file changes.