docs(site): make the docs site feel like part of Docker, and explain what Docker Agent is by dgageot · Pull Request #2792 · docker/docker-agent

dgageot · 2026-05-13T14:03:59Z

Make the docs site feel like part of Docker — same chrome, same fonts,
same vocabulary — and rewrite the homepage so a first-time visitor can
answer "what is this and why should I care?" in under 30 seconds.

This is one commit per recommendation so reviewers can land them
piecemeal, push back on individual ones, or revert one without losing
the others. No code/runtime changes — only files under docs/.

Branding (1–11)

#	Commit	Change
1	`4d8d318da`	Switch fonts to Roboto / Roboto Mono (Docker design system)
2	`11b72ba56`	Introduce structured brand color tokens (`--blue-`, `--navy-`, `--moby-cyan`)
3	`606ea37fa`	Honor light theme on code blocks (warm `#F6F8FA` + matching syntax palette)
4	`c5902c024`	Redesign callouts in docs.docker.com style (filled circular icon badge)
5	`be5cbf997`	Tighter `<title>` and meta description for SEO
6	`7e3b96f49`	Ship Moby mark + wordmark as real assets, fix the clipped `viewBox`
7	`1f98e2a38`	Add Docker corporate top bar (Hub · Desktop · Docs · Scout · Blog)
8	`9d842ca74`	Show "Docs" as a Docker-Blue product pill
9	`be43e2892`	Tagline ("Run AI agents like containers.") at the top of the sidebar
10	`1988b0eaf`	Add Docker ecosystem footer
11	`a1c2d4a47`	Add `docs/STYLE.md` and reconcile Docker Agent (prose) vs `docker agent` (CLI)

Messaging (12–21)

#	Commit	Change
12	`c4204c615`	Move the demo GIF above the fold
13	`bce901222`	Hero leads with the `docker run` analogy
14	`7295990a7`	30-second elevator panel (what / what isn't / who for / what you get)
15	`476e999ac`	Glossary box (Agent · Tool · MCP · A2A · TUI · OCI)
16	`2bac64289`	"How it works" SVG flow diagram
17	`d2cb0bb90`	Replace abstract "Why" copy with pain → fix rows
18	`ee1deacbf`	Add a Use Cases row (coding · ops · data · custom)
19	`b54af673a`	Side-by-side Without / With Docker Agent code comparison
20	`95253a425`	Cross-link the wider Docker ecosystem on the home page
21	`fb259975c`	Replace emoji icons with Lucide-style line icons in Docker Blue

Try it locally

cd docs
bundle install        # needs Ruby ≥ 3.0
bundle exec jekyll serve

Validation

I couldn't run a full Jekyll build locally (host Ruby is 2.6, Bundler
needs ≥ 3.0), but everything passes structural validation:

✅ _config.yml and _data/nav.yml parse as YAML
✅ All three new SVGs (docker-mark, docker-wordmark, how-it-works) parse as XML
✅ Liquid {% %} and {{ }} are balanced across every layout/include
✅ style.css braces are balanced (311 / 311)
✅ No Markdown content was deleted — pages were edited in place

A reviewer running bundle exec jekyll serve should see the site
build clean. Visual review on the deployed site is the main thing left.

Out of scope (not done in this PR)

A few items I considered but deferred — happy to do them in follow-ups
if reviewers want:

An asciinema recording to complement the demo GIF (item B12 from the
original list).
A site-wide pass to apply the new naming convention beyond the home
page, introduction and quickstart (the rest of the docs still uses
"docker-agent" in places — STYLE.md documents the convention, but
changing every page would balloon this PR).
Pulling fonts and SVG icons into docs/assets/ so the site has zero
third-party requests at runtime.

Review feedback addressed

Three medium-severity issues raised by the PR Review bot are fixed in
dedicated follow-up commits:

#	Commit	Fix
22	`f10643db0`	Move footer out of `<main>` ARIA landmark
23	`aa27973ab`	`scroll-margin-top` on skip-link target
24	`499204f94`	`markdown="1"` on `.compare` so fenced code renders

Replace Inter and JetBrains Mono with Roboto and Roboto Mono to align with Docker's design system used across docker.com and docs.docker.com.

Replace ad-hoc hex values with a structured palette of named tokens (--blue-100..700, --navy-600..900, --moby-cyan) that mirrors Docker's design system. Existing --docker-* and --accent-* names are kept as aliases so nothing breaks; new code should prefer the scaled tokens.

Previously code blocks stayed dark navy even when the rest of the page switched to the light theme, which clashed with docs.docker.com styling. Switch the light theme to a soft \"#F6F8FA\" code background and add a matching warm Rouge token palette so code reads naturally in both modes.

Switch admonitions to a Docker-style panel: rounded card, filled circular icon badge in the top-left, and a strong title row. Authors keep the same Markdown structure, so existing pages just look better. Also strip the redundant emoji prefixes (\"\u2139\ufe0f\", \"\ud83d\udca1\", \"\u26a0\ufe0f\") from callout titles \u2014 the icon badge now carries that role.

The homepage now reads \"Docker Agent \u2014 Run AI agents from YAML, like containers\" instead of the generic \"Docker Agent \u2013 Documentation\", and the site description is shortened to fit Google's ~155-char snippet budget. Also surface a sharper tagline (\"Run AI agents like containers.\") in _config.yml and add og:site_name plus Twitter card metadata for nicer link previews.

The previous header SVG and favicon used a viewBox of 0 0 50 36 even though the path extended down to y=39, clipping part of the whale's body. Move the mark into /assets/docker-mark.svg with a corrected 0 0 50 40 viewBox, reference it from both <link rel=\"icon\"> and the header logo, and add an /assets/docker-wordmark.svg variant for the upcoming Docker top bar.

A thin (32px) black bar now sits above the product header with the Docker wordmark and quick links to Desktop, Hub, Docs, Scout, and Blog \u2014 mirroring the docs.docker.com / docker.com layout. This immediately signals that Docker Agent is part of the Docker ecosystem. Sidebar, main content, TOC and heading scroll-margins are shifted by the new bar height so nothing gets clipped under the fixed chrome.

Replace the muted divider + grey \"Docs\" label with a small rounded pill in Docker Blue, matching the badge convention used on Docker Hub, Docker Desktop and Docker Scout product headers.

Surface \"Run AI agents like containers.\" at the top of the sidebar on every page so the value proposition is reinforced no matter where the reader lands. The text is sourced from site.tagline so it can be edited centrally in _config.yml.

Add a three-column site footer with links to Docker Desktop, Hub, Scout, Build Cloud, docs.docker.com, the agent catalog on Hub, the Docker blog, status page, terms and privacy. Anchors the docs site in the broader Docker ecosystem instead of feeling like an orphan project.

Codify a single naming convention (\"Docker Agent\" in prose, \`docker agent\` for the CLI) in docs/STYLE.md and apply it to the two most visible pages \u2014 the introduction and the quickstart \u2014 which were mixing \"docker-agent\" and \"Docker Agent\" almost line by line. The new STYLE.md also documents voice, code samples and a small glossary of terms (Agent, Toolset, MCP, A2A, TUI, OCI) so subsequent contributors don't have to guess.

Seeing the TUI in action is the single most effective way to explain what Docker Agent does. Pull the demo GIF up directly under the hero so first-time visitors don't have to scroll past three sections of prose to find it.

Replace the abstract \"open-source runtime for AI agents\" hero copy with a sentence that lands instantly for anyone who has used Docker: Docker Agent is to AI agents what \`docker run\` is to containers. Define an agent in a YAML file, run it with one command, share it through any OCI registry \u2014 the same workflow you already use for images. Also style inline \`code\` inside the hero so the analogy reads cleanly on the gradient background.

Right under the demo GIF, surface a four-card panel that answers \"what is this?\" without requiring the reader to parse paragraphs of prose: \u2022 What it is \u2022 What it isn't \u2022 Who it's for \u2022 What you get Bullet-style framing tends to convert curious visitors faster than narrative copy.

First-time visitors don't know what \"MCP\", \"A2A\", \"TUI\" or \"OCI\" mean, and forcing them to click into the Concepts pages just to read the homepage costs us readers. Drop a compact <dl> on the home page that defines the six terms most likely to trip people up: Agent, Tool, MCP, A2A, TUI and OCI.

Add an inline SVG that shows the runtime in a single picture: agent.yaml \u2192 docker agent run \u2192 [Model \u2194 Tools \u2194 Sub-agents] \u2192 stream The diagram complements (rather than replaces) the four-step list \u2014 some readers grok pictures faster, others prefer the list \u2014 and uses currentColor so it stays readable in both light and dark themes.

Above the existing feature grid, add four side-by-side rows that pair a concrete developer complaint with the matching Docker Agent solution \u2014 e.g. \"I rebuilt the same agent loop in three projects\" \u2192 \"Reusable YAML, declare once, run everywhere\". Concrete problem/solution framing tends to convert better than abstract \"declarative configuration\" arguments.

The previous home page never told the visitor what people actually *build* with Docker Agent. Add a four-card row above \"How it works\" showing the four common shapes \u2014 coding agents, ops/SRE, data & research, custom workflows \u2014 each linking to the most relevant follow-up page (catalog, CLI, RAG, multi-agent).

Two-column block on the home page showing the *exact* same coding assistant written: \u2022 left \u2014 ~30 lines of Python glue (anthropic SDK + tool dispatch loop), the kind of code teams keep rewriting per project. \u2022 right \u2014 8 lines of YAML + a single \`docker agent run\` invocation. Visceral side-by-side framing communicates the value proposition faster than any prose section.

Two changes that anchor Docker Agent in the rest of Docker's product line: \u2022 In \"What Is Docker Agent?\" call out that it comes from Docker, makers of Engine, Desktop, Hub and Scout, with inline links. \u2022 Add a new \"Part of the Docker ecosystem\" tile row right above the \"Explore the Docs\" cards, with one-line pitches for Docker Hub (agent catalog), Docker Desktop (MCP-in-containers), Docker Model Runner (local models) and Docker Scout (supply chain).\n\nThe quickstart link to the catalog is also rewritten to mention\nDocker Hub by name, so the reader connects \"agentcatalog/\u2026\" to a\nfamiliar registry instead of an opaque slash-separated string.

The home page mixed feature emojis (\ud83d\udcdd \ud83d\udd27 \ud83d\udc65 \ud83e\udde0 \ud83d\udce6 \ud83d\udda5\ufe0f) with the rest of the chrome and looked more like a blog post than a Docker product page. Swap every emoji in the feature, use-case and \"Explore the Docs\" grids for a Lucide-style line icon rendered in Docker Blue inside a tinted square \u2014 the same shape the Docker design system uses on docker.com.

docker-agent

Assessment: 🟡 NEEDS ATTENTION

3 medium-severity issues found in the docs branding update. No high-severity or security issues. The changes are otherwise well-structured.

Severity	File	Issue
🟡 MEDIUM	`docs/_layouts/default.html`	Footer nested inside `<main>` — incorrect ARIA landmark
🟡 MEDIUM	`docs/css/style.css`	Skip-link target `#page-content` lacks `scroll-margin-top`
🟡 MEDIUM	`docs/index.md`	Code blocks in `<div class="compare">` won't render (missing `markdown="1"`)

docker-agent · 2026-05-13T14:09:25Z

      {{ content }}
      {% unless page.url == '/' %}{% include page-nav.html %}{% endunless %}
    </div>
+    {% include footer.html %}


[MEDIUM] Footer included inside <main> — incorrect ARIA landmark nesting

{% include footer.html %} is placed as the last child of <main class="main" role="main"> rather than as a sibling after </main>.

A site-level <footer> maps to the contentinfo landmark. Nesting contentinfo inside the main landmark is non-conforming: screen readers and accessibility audit tools will report the landmark hierarchy as incorrect, and users navigating by landmark (e.g. VoiceOver "Rotor") will find the footer inside the main content region rather than as a top-level landmark.

Fix: Move the {% include footer.html %} line to after </main>:

</main> {% include footer.html %}

docker-agent · 2026-05-13T14:09:25Z

  border-bottom: 1px solid var(--border);
  letter-spacing: -0.02em;
-  scroll-margin-top: calc(var(--header-height) + 16px);
+  scroll-margin-top: calc(var(--header-height) + var(--docker-bar-height) + 16px);


[MEDIUM] Skip-link target #page-content missing scroll-margin-top — content hidden behind fixed chrome

The layout adds two fixed bars: .docker-bar (32 px) and .header (56 px) = 88 px of fixed chrome at the top of the viewport. The CSS correctly sets scroll-margin-top on .content h2 and .content h3 to account for this, but the skip-link target #page-content (the .content div itself) has no scroll-margin-top.

When a keyboard or screen-reader user activates the Skip to content link, the browser scrolls #page-content flush to the top of the viewport — placing the first ~88 px of content behind the fixed bars and making it invisible.

Fix: Add scroll-margin-top to .content (or #page-content):

.content { scroll-margin-top: calc(var(--header-height) + var(--docker-bar-height) + 16px); }

docker-agent · 2026-05-13T14:09:25Z

+
+The same coding assistant, written two different ways:
+
+<div class="compare">


[MEDIUM] Fenced code blocks inside <div class="compare"> will not render — missing markdown="1"

Kramdown (Jekyll's default Markdown processor) does not process Markdown inside raw HTML blocks unless the element carries the markdown="1" attribute. The fenced Python, YAML, and Bash code blocks inside <div class="compare"> will be emitted as literal backtick-fenced text in the final HTML — no syntax highlighting, no <code> tags.

The author already applied markdown="1" to callout divs (e.g. line 336: <div class="callout callout-tip" markdown="1">), so the fix is the same pattern:

<div class="compare" markdown="1"> <div class="compare-side compare-without" markdown="1"> ... </div> <div class="compare-side compare-with" markdown="1"> ... </div> </div>

Note: Each nested div that contains Markdown also needs markdown="1".

The site-wide footer was nested inside \`<main role=\"main\">\`, which is a screen-reader anti-pattern: \`<footer>\` is a top-level landmark and putting it inside \`main\` makes assistive tech announce it as part of the page's main content rather than as the site's contentinfo landmark. Move it out as a sibling of \`<main>\` and shift it right with the same \`margin-left: var(--sidebar-width)\` so the column alignment is unchanged. While at it, give \`<main>\` an \`id=\"main-content\"\` for future skip-link targeting. Reported by the PR Review bot on docker#2792.

The \"Skip to content\" link jumps to \`#page-content\`, but with the fixed Docker top bar + product header taking up ~88px the top of the content was being scrolled *under* that fixed chrome \u2014 keyboard users landed on whitespace instead of the page heading. Add the same \`scroll-margin-top\` formula already used on \`h2\` / \`h3\` (\`var(--header-height) + var(--docker-bar-height) + 16px\`) to \`.content\` so the page heading lines up just below the top bars when the skip link is activated. Reported by the PR Review bot on docker#2792.

kramdown only re-parses Markdown inside an HTML block when the block carries the explicit \`markdown=\"1\"\` attribute. Without it, the \`\`\`python and \`\`\`yaml fences inside \`<div class=\"compare\">\` were emitted as raw text, which is exactly the opposite of what the \"Without Docker Agent\" \u2194 \"With Docker Agent\" panel is meant to demonstrate. Add \`markdown=\"1\"\` to the outer \`.compare\` wrapper and to both \`.compare-side\` children so kramdown highlights the code as expected. Reported by the PR Review bot on docker#2792.

dgageot · 2026-05-13T14:13:22Z

All three review findings are addressed in dedicated follow-up commits on top of the existing 21:

Severity	Issue	Fix
🟡 MEDIUM	Footer nested inside `<main>` — incorrect ARIA landmark	`f10643db0` — moved `{% include footer.html %}` out of `<main>` and shifted `.site-footer` right with `margin-left: var(--sidebar-width)` so the column stays aligned. Also gave `<main>` an `id="main-content"` for future skip-link targeting.
🟡 MEDIUM	Skip-link target `#page-content` lacks `scroll-margin-top`	`aa27973ab` — added the same `scroll-margin-top: calc(var(--header-height) + var(--docker-bar-height) + 16px)` formula already used on `h2`/`h3`, so keyboard users land at the heading instead of under the fixed top bars.
🟡 MEDIUM	Code blocks in `<div class="compare">` won't render (missing `markdown="1"`)	`499204f94` — added `markdown="1"` to the outer `.compare` and to both `.compare-side` children so kramdown re-parses the fenced `python /` yaml blocks.

Local sanity checks still pass (CSS braces 312/312, Liquid {% %} 21/21, {{ }} 13/13). Couldn't run bundle exec jekyll serve because host Ruby is 2.6, but the Docs Preview workflow on this PR will exercise the kramdown fix end to end.

dgageot · 2026-05-13T14:29:34Z

Superseded by #2793, which is opened from an internal branch (docs/docker-branding on docker/docker-agent) so the Docs Preview workflow can run.

All commits including the three review-feedback fixes are identical \u2014 only the head ref changes.

dgageot added 21 commits May 13, 2026 15:49

docs(site): use Docker brand fonts (Roboto / Roboto Mono)

4d8d318

Replace Inter and JetBrains Mono with Roboto and Roboto Mono to align with Docker's design system used across docker.com and docs.docker.com.

docs(site): show "Docs" as a Docker Blue product badge

9d842ca

Replace the muted divider + grey \"Docs\" label with a small rounded pill in Docker Blue, matching the badge convention used on Docker Hub, Docker Desktop and Docker Scout product headers.

docs(home): move demo GIF above the fold

c4204c6

Seeing the TUI in action is the single most effective way to explain what Docker Agent does. Pull the demo GIF up directly under the hero so first-time visitors don't have to scroll past three sections of prose to find it.

dgageot requested a review from a team as a code owner May 13, 2026 14:04

docker-agent reviewed May 13, 2026

View reviewed changes

dgageot added 3 commits May 13, 2026 16:12

dgageot mentioned this pull request May 13, 2026

docs(site): make the docs site feel like part of Docker, and explain what Docker Agent is #2793

Merged

dgageot had a problem deploying to github-pages May 13, 2026 14:29 — with GitHub Actions Failure

dgageot closed this May 13, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(site): make the docs site feel like part of Docker, and explain what Docker Agent is#2792

docs(site): make the docs site feel like part of Docker, and explain what Docker Agent is#2792
dgageot wants to merge 24 commits into
docker:mainfrom
dgageot:docs/docker-branding

dgageot commented May 13, 2026 •

edited

Loading

Uh oh!

docker-agent left a comment

Uh oh!

docker-agent May 13, 2026

Uh oh!

docker-agent May 13, 2026

Uh oh!

docker-agent May 13, 2026

Uh oh!

dgageot commented May 13, 2026

Uh oh!

dgageot commented May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		The same coding assistant, written two different ways:

		<div class="compare">

Conversation

dgageot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Branding (1–11)

Messaging (12–21)

Try it locally

Validation

Out of scope (not done in this PR)

Review feedback addressed

Uh oh!

docker-agent left a comment

Choose a reason for hiding this comment

Assessment: 🟡 NEEDS ATTENTION

Uh oh!

docker-agent May 13, 2026

Choose a reason for hiding this comment

Uh oh!

docker-agent May 13, 2026

Choose a reason for hiding this comment

Uh oh!

docker-agent May 13, 2026

Choose a reason for hiding this comment

Uh oh!

dgageot commented May 13, 2026

Uh oh!

dgageot commented May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dgageot commented May 13, 2026 •

edited

Loading