The Jekyll layout renders a canonical link when a page sets
canonical: front matter (added with the preview banner in #3413), but
no page carried a value yet. Set it on all 90 content pages mounted
on docs.docker.com so search engines treat the stable docs as
authoritative, completing phase 3.2 of #3371.
Every generated URL was verified to return 200 on docs.docker.com,
and the rendered site carries the tag on exactly those 90 pages
(homepage and 404 excluded). docs.docker.com itself ignores the
param: its head template always canonicalizes to the page permalink.
Companion change for the Hugo module mount in docker/docs (#3371,
phase 2.1). Mounted pages must match docs.docker.com conventions:
- drop the body H1: both layouts now render the front matter title
(the Jekyll layout prints it like docs.docker.com does; the homepage
keeps its hero)
- add weight front matter derived from the _data/nav.yml order so the
docs.docker.com sidebar matches the github.io navigation
- add linkTitle where the nav label differs from the page title
- add section _index.md files with title, description, and weight;
Jekyll ignores underscore-prefixed files so github.io is unaffected
- add aliases mapping the docs.docker.com URLs of the hand-authored
pages being replaced (tutorial, best-practices, evals, local-models,
model-providers, rag, sharing-agents, integrations/*, reference/*)
onto their mounted equivalents so no URL breaks
Implements the source-side cleanup for the docs.docker.com Hugo module
mount (#3371, phase 1.1):
- replace Liquid relative_url links with plain relative Markdown links
- drop permalink front matter (paths already match the URLs)
- convert HTML callouts to GitHub-style alerts (NOTE, TIP, IMPORTANT,
WARNING), keeping custom titles as a bold lead line
- replace theme HTML card and feature grids with Markdown lists
- add keywords front matter to every content page
- document the new callout, link, and availability badge conventions
in STYLE.md
- tune the markdownlint config to the house style; docs lints clean
Also fixes pre-existing issues surfaced by the conversion: an undefined
site.examples_url variable, a malformed Liquid URL, two absolute links
that bypassed the baseurl, two broken heading anchors, HTML entities
rendering literally inside code spans, and a dead Docker Sandboxes URL.
The github.io homepage (index.md) and 404.md intentionally keep Jekyll
Liquid and theme HTML: they are never mounted on docs.docker.com.
Bring the docs site in line with Docker's official design system and
rewrite the homepage so first-time visitors can answer "what is this
and why should I care?" in under 30 seconds.
No application/runtime code is touched — every change is in `docs/`.
## Branding
* **Fonts** — switch from Inter / JetBrains Mono to **Roboto Flex**
(the variable-axis sans docs.docker.com self-hosts) and **Roboto
Mono**. Both pulled from Google Fonts.
* **Color tokens** — introduce a structured palette of named tokens
derived from the official brand kit (Docker-Logos-1.zip):
--blue-100..700 anchored on Ocean Blue `#2560FF`
--navy-900..600 anchored on Deep Blue `#00153C`
--gray-100..900 lifted verbatim from docs.docker.com (#E7EAEF,
#C8CFDA, …, #1E2129) so chrome feels like the same family.
* **Dark theme** matches docs.docker.com: neutral charcoal page bg
`#10151B`, sidebar/cards `#1E2129`, body text `#C8CFDA`, headings
white, links `#4B83F1`. Brand navy is reserved for the hero, the
primary button and the info-callout dark backgrounds.
* **Light theme** also calibrated to docs.docker.com: page+sidebar+
main on the same `#E7EAEF` (gray-100) surface (matches their
footer / navbar-active), cards on white, headings `#1F242D`,
body copy `#3F4750` (their `oklch(37.3% .034 259.733)`).
* **Moby mark** — the hand-authored whale SVG didn't match Docker's
official asset (it was missing the eight containers stacked on the
whale's back). Ship the actual `docker-mark-ocean-blue.svg` from
the brand kit instead, plus a white variant for dark backgrounds.
* **Callouts** — redesigned in docs.docker.com style: rounded panel
with a filled circular icon badge in the top-left and a strong
title row. `info`, `tip` and `warning` now match the same exact
background colors docs.docker.com uses in dark mode (`#00153C`,
`#11371A`, `#643700`).
* **Header** — Docker Agent wordmark + Moby mark, left-aligned at the
page padding edge so it doesn't drift on wide monitors.
* **Sidebar** — value tagline at the top ("Run AI agents like
containers."), nav links at 16px / weight 400 (was 13.2px), pure
white sidebar text on dark mode for higher contrast.
* **Right-column TOC** — restyled like docs.docker.com:
"Edit this page" link with pencil icon at the top, pointing at
GitHub's web editor (resolved at build time via `<meta
name="docs-edit-url">` and `{{ page.path }}`).
"Table of contents" heading at `1.05rem` weight 500 (was a tiny
uppercase eyebrow).
Links at `.875rem`, gray-600 / gray-100, with a 2px gray-300
left-border + weight 500 on the active entry.
* **Ecosystem footer** — three-column footer with links to Docker
Desktop, Hub, Scout, Build Cloud, docs.docker.com, the agent
catalog on Hub, the Docker blog, status, terms and privacy.
* **Page chrome** — light-theme code blocks honor the theme (warm
`#F6F8FA` + matching syntax palette); footer is moved out of
`<main>` so it isn't part of the ARIA `main` landmark; skip-link
target gets `scroll-margin-top` so keyboard users land below the
header.
## Messaging
* **Hero** leads with the docker-run analogy:
> **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 — the same workflow you already use for
> images.
* **Demo GIF** moved above the fold so the TUI is visible without
scrolling.
* **30-second elevator panel** — four cards under the hero:
what it is / what it isn't / who it's for / what you get.
* **Without / With Docker Agent** code comparison: ~30 lines of
Python+Anthropic glue versus 8 lines of YAML + `docker agent run`.
* **"Why" rows** — abstract copy replaced with concrete pain → fix
pairs ("I rebuilt the same agent loop in three projects" →
"Reusable YAML, declare once, run everywhere").
* **Use cases** — a 4-card row showing the typical shapes (coding /
ops / data / custom workflows), each linking to the most relevant
follow-up page.
* **How it works** — adds an SVG flow diagram
(`agent.yaml → docker agent run → [Model ↔ Tools ↔ Sub-agents] →
stream`) using `currentColor` so it reads in both themes.
* **Glossary box** explaining Agent / Tool / MCP / A2A / TUI / OCI
inline so first-time readers don't bounce on the jargon.
* **Ecosystem tiles** — cross-links to Docker Hub (agent catalog),
Docker Desktop, Docker Model Runner and Docker Scout, anchoring
Docker Agent in the broader product family.
* **Icon set** — emoji feature/usecase/card icons replaced with
Lucide-style line icons in tinted Docker-Blue squares.
* **STYLE.md** — added to codify "Docker Agent" (prose) vs
`docker agent` (CLI) naming, voice, code samples and a small
glossary so subsequent contributors don't have to guess. The
introduction and quickstart pages are reconciled to the new
convention.
* **Bulk callout edit** — every `<div class="callout-title">` across
56 content pages had its leading `ℹ️ / 💡 / ⚠️` emoji stripped,
because the new icon-badge callout already provides one.
## Meta
* `<title>` and meta description tightened for SEO: home page now
reads "Docker Agent — Run AI agents from YAML, like containers"
and the description fits Google's ~155-char snippet budget.
`og:site_name` and Twitter card metadata added for nicer link
previews.
Add markdown="1" attribute to all callout div elements so that
kramdown processes markdown syntax (bold, italic, links) inside
HTML blocks. Without this attribute, content like **bold** and
*italic* was rendered as plain text on the documentation website.
Fixes#2282
Assisted-By: docker-agent
Move built-in tool documentation from being duplicated across
concepts/tools and configuration/tools into dedicated pages under
docs/tools/ (one page per toolset).
- Create individual pages for: filesystem, shell, think, todo, memory,
fetch, script, transfer-task, background-agents, handoff, a2a
- Slim down concepts/tools to a summary table linking to each tool page
- Slim down configuration/tools to a summary table plus cross-cutting
concerns (MCP, auto-install, filtering, deferred loading)
- Update nav.yml to list all 14 built-in tools (was 3)
Assisted-By: docker-agent
Sayt-0
David Gageot