From 0f122af2aab5b6922b08cbd062cd75203b884039 Mon Sep 17 00:00:00 2001 From: David Gageot Date: Wed, 13 May 2026 18:06:31 +0200 Subject: [PATCH 1/2] ci: drop the dead Docs Preview workflow The \`Docs Preview\` workflow can't actually deploy a preview today: \u2022 The \`build-and-deploy\` job is gated on \`head.repo.full_name == github.repository\`, so it skips on every PR opened from a fork. \u2022 Even on internal-branch PRs, the deploy step is rejected by the \`github-pages\` environment, whose custom branch policy only allows deployments from \`main\`: Branch refs/pull//merge is not allowed to deploy to github-pages due to environment protection rules. So the workflow burns CI time, posts no preview comment, and leaves a red FAILURE check on every PR that touches \`docs/**\`. Remove the workflow file rather than leave a permanently broken check in place. If a maintainer wants real PR previews back, the right fix is a follow-up that either widens the \`github-pages\` environment branch policy or moves the docs-preview deploy to a separate destination (e.g. Cloudflare Pages, Netlify, or a non-protected \`gh-pages\` push). --- .github/workflows/docs-preview.yml | 89 ------------------------------ 1 file changed, 89 deletions(-) delete mode 100644 .github/workflows/docs-preview.yml diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml deleted file mode 100644 index 5f90f0a34..000000000 --- a/.github/workflows/docs-preview.yml +++ /dev/null @@ -1,89 +0,0 @@ -name: Docs Preview - -on: - pull_request: - paths: - - "docs/**" - types: [opened, synchronize, reopened, closed] - -concurrency: - group: docs-preview-${{ github.event.pull_request.number }} - cancel-in-progress: true - -jobs: - build-and-deploy: - if: >- - github.event.pull_request.head.repo.full_name == github.repository - && github.event.action != 'closed' - runs-on: ubuntu-latest - permissions: - contents: write - environment: - name: github-pages - url: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-${{ github.event.pull_request.number }}/ - steps: - - name: Checkout - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - - name: Set up Ruby - uses: ruby/setup-ruby@e5517072e87f198d9533967ae13d97c11b604005 # v1.99.0 - with: - ruby-version: "3.3" - working-directory: docs - - - name: Install dependencies - run: bundle install - working-directory: docs - - - name: Build Jekyll site - run: bundle exec jekyll build --baseurl "/${{ github.event.repository.name }}/pr-${{ github.event.pull_request.number }}" - working-directory: docs - env: - JEKYLL_ENV: production - - - name: Deploy to GitHub Pages - uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: docs/_site - destination_dir: pr-${{ github.event.pull_request.number }} - - comment: - needs: build-and-deploy - if: >- - github.event.pull_request.head.repo.full_name == github.repository - && github.event.action != 'closed' - runs-on: ubuntu-latest - permissions: - pull-requests: write - steps: - - name: Comment preview URL - uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4 - with: - header: docs-preview - message: | - πŸ“– **Docs preview**: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-${{ github.event.pull_request.number }}/ - - cleanup: - if: >- - github.event.pull_request.head.repo.full_name == github.repository - && github.event.action == 'closed' - runs-on: ubuntu-latest - permissions: - contents: write - steps: - - name: Checkout gh-pages branch - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - ref: gh-pages - - - name: Remove preview directory - run: | - PR_DIR="pr-${{ github.event.pull_request.number }}" - if [ -d "$PR_DIR" ]; then - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - git rm -rf "$PR_DIR" - git commit -m "chore: remove docs preview for PR #${{ github.event.pull_request.number }}" - git push - fi From 7aae80c1ed5307a6cf725e7a41bc88ff739a7fde Mon Sep 17 00:00:00 2001 From: David Gageot Date: Wed, 13 May 2026 18:07:18 +0200 Subject: [PATCH 2/2] docs(site): rebrand to docker.com / docs.docker.com style MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 `` 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 `
` 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 `
` across 56 content pages had its leading `ℹ️ / πŸ’‘ / ⚠️` emoji stripped, because the new icon-badge callout already provides one. ## Meta * `` 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. --- docs/.gitignore | 1 + docs/STYLE.md | 72 ++ docs/_config.yml | 4 +- docs/_includes/footer.html | 45 + docs/_includes/header.html | 9 +- docs/_layouts/default.html | 24 +- docs/assets/docker-mark-white.svg | 25 + docs/assets/docker-mark.svg | 25 + docs/assets/how-it-works.svg | 79 ++ docs/community/contributing/index.md | 6 +- docs/community/telemetry/index.md | 4 +- docs/community/troubleshooting/index.md | 6 +- docs/concepts/agents/index.md | 4 +- docs/concepts/distribution/index.md | 4 +- docs/concepts/models/index.md | 2 +- docs/concepts/multi-agent/index.md | 12 +- docs/concepts/tools/index.md | 4 +- docs/configuration/agents/index.md | 8 +- docs/configuration/hcl/index.md | 4 +- docs/configuration/hooks/index.md | 16 +- docs/configuration/overview/index.md | 4 +- docs/configuration/permissions/index.md | 6 +- docs/configuration/routing/index.md | 6 +- docs/configuration/sandbox/index.md | 4 +- docs/configuration/structured-output/index.md | 4 +- docs/configuration/tools/index.md | 12 +- docs/css/style.css | 846 +++++++++++++++--- docs/features/a2a/index.md | 4 +- docs/features/acp/index.md | 6 +- docs/features/api-server/index.md | 4 +- docs/features/chat-server/index.md | 6 +- docs/features/cli/index.md | 8 +- docs/features/evaluation/index.md | 8 +- docs/features/mcp-mode/index.md | 2 +- docs/features/rag/index.md | 6 +- docs/features/remote-mcp/index.md | 4 +- docs/features/skills/index.md | 6 +- docs/features/tui/index.md | 10 +- docs/getting-started/installation/index.md | 6 +- docs/getting-started/introduction/index.md | 46 +- docs/getting-started/quickstart/index.md | 12 +- docs/guides/go-sdk/index.md | 2 +- docs/guides/secrets/index.md | 2 +- docs/index.md | 253 +++++- docs/js/app.js | 102 ++- docs/providers/anthropic/index.md | 2 +- docs/providers/bedrock/index.md | 2 +- docs/providers/custom/index.md | 2 +- docs/providers/dmr/index.md | 4 +- docs/providers/google/index.md | 4 +- docs/providers/local/index.md | 4 +- docs/providers/openai/index.md | 2 +- docs/providers/overview/index.md | 2 +- docs/tools/a2a/index.md | 2 +- docs/tools/api/index.md | 6 +- docs/tools/background-agents/index.md | 2 +- docs/tools/fetch/index.md | 6 +- docs/tools/filesystem/index.md | 2 +- docs/tools/handoff/index.md | 4 +- docs/tools/lsp/index.md | 6 +- docs/tools/memory/index.md | 2 +- docs/tools/model-picker/index.md | 2 +- docs/tools/script/index.md | 2 +- docs/tools/shell/index.md | 4 +- docs/tools/tasks/index.md | 2 +- docs/tools/think/index.md | 2 +- docs/tools/transfer-task/index.md | 2 +- docs/tools/user-prompt/index.md | 6 +- 68 files changed, 1468 insertions(+), 327 deletions(-) create mode 100644 docs/STYLE.md create mode 100644 docs/_includes/footer.html create mode 100644 docs/assets/docker-mark-white.svg create mode 100644 docs/assets/docker-mark.svg create mode 100644 docs/assets/how-it-works.svg diff --git a/docs/.gitignore b/docs/.gitignore index ee58fa2ca..a17c0ea9c 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -3,6 +3,7 @@ _site/ .jekyll-cache/ .jekyll-metadata vendor/ +.bundle/ Gemfile.lock node_modules/ pages/ diff --git a/docs/STYLE.md b/docs/STYLE.md new file mode 100644 index 000000000..a378e8aae --- /dev/null +++ b/docs/STYLE.md @@ -0,0 +1,72 @@ +# Documentation style guide + +A short reference for writers and reviewers. Goal: keep voice, naming +and examples consistent across every page on this site. + +## Product naming + +| Context | Use | Don't use | +|---|---|---| +| Prose, headings, marketing | **Docker Agent** (two words, both capitalised β€” the proper name of the product) | docker-agent, Docker-Agent, docker agent (in prose) | +| The CLI command | `docker agent` (lower-case, two words, in monospace) | `docker-agent`, `Docker Agent run` | +| The repository / module path | `docker/docker-agent` | docker/Docker-Agent | +| Internal identifiers / package names | as defined in code (e.g. `cagent`) β€” never invent new spellings in prose | mixing internal identifiers into user-facing copy | + +A simple rule of thumb: +- **Talking about the product?** β†’ "Docker Agent" +- **Showing a command the user types?** β†’ `docker agent run agent.yaml` + +## Voice + +- Address the reader as **you**, not "we" or "the user". +- Prefer present tense and active voice ("the agent reads files", + not "files will be read by the agent"). +- Keep sentences short. Two short sentences usually beat one compound + one. +- Avoid "simply", "just", "easily" β€” they're rarely accurate and + often condescending. + +## Code samples + +- All shell prompts use `$ ` (dollar + space) and the command on the + same line. Output, when shown, has no prompt. +- YAML/HCL examples should be runnable as-is when reasonable, or end + in `# ...` to make truncation explicit. +- The canonical example agent uses `model: anthropic/claude-sonnet-4-5`. + Use a different model only when the example is *about* that model. +- File names in prose are in `monospace` (`agent.yaml`, not "agent.yaml"). + +## Callouts + +Use the existing pattern; the new visual style does the rest: + +```markdown +<div class="callout callout-tip" markdown="1"> +<div class="callout-title">When to use it</div> + <p>Body text.</p> +</div> +``` + +- `callout-info` β€” neutral context +- `callout-tip` β€” positive, "consider this" +- `callout-warning` β€” caution, breaking, security + +Don't prefix the title with an emoji β€” the icon badge already provides +one. + +## Glossary one-liners + +When a page first introduces a term, link to its concept page or use +one of these standard one-liners: + +- **Agent** β€” an LLM with instructions, tools, and (optionally) + sub-agents, defined in YAML or HCL. +- **Toolset** β€” a group of related tools the agent can call (e.g. + `filesystem`, `shell`, `mcp`). +- **MCP** β€” Model Context Protocol, an open standard for tool servers. +- **A2A** β€” Agent-to-Agent protocol, used to talk to other agents + over HTTP. +- **TUI** β€” Terminal User Interface, the default interactive front end + Docker Agent ships with. +- **OCI** β€” Open Container Initiative; the same registry format used + for Docker images. Docker Agent reuses it for sharing agents. diff --git a/docs/_config.yml b/docs/_config.yml index 469a46fe5..06fb36172 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,5 +1,6 @@ title: Docker Agent -description: Build, run, and share powerful AI agents with a declarative YAML config, rich tool ecosystem, and multi-agent orchestration β€” by Docker. +tagline: Run AI agents like containers. +description: Run AI agents from a YAML file. Define them once, share them through any OCI registry, and run them anywhere β€” by Docker. url: "https://docker.github.io" baseurl: "/docker-agent" @@ -25,6 +26,7 @@ relative_links: exclude: - DEVELOPMENT.md - TODO.md + - STYLE.md - recordings/ - Gemfile - Gemfile.lock diff --git a/docs/_includes/footer.html b/docs/_includes/footer.html new file mode 100644 index 000000000..5f1c89704 --- /dev/null +++ b/docs/_includes/footer.html @@ -0,0 +1,45 @@ +<footer class="site-footer" role="contentinfo"> + <div class="site-footer-inner"> + <div class="site-footer-brand"> + <img src="{{ '/assets/docker-mark.svg' | relative_url }}" alt="" width="28" height="22"> + <div> + <div class="site-footer-product">Docker Agent</div> + <div class="site-footer-tagline">Run AI agents like containers.</div> + </div> + </div> + + <div class="site-footer-cols"> + <div class="site-footer-col"> + <h4>Product</h4> + <ul> + <li><a href="https://www.docker.com/products/docker-desktop/" target="_blank" rel="noopener">Docker Desktop</a></li> + <li><a href="https://hub.docker.com" target="_blank" rel="noopener">Docker Hub</a></li> + <li><a href="https://www.docker.com/products/docker-scout/" target="_blank" rel="noopener">Docker Scout</a></li> + <li><a href="https://www.docker.com/products/build-cloud/" target="_blank" rel="noopener">Build Cloud</a></li> + </ul> + </div> + <div class="site-footer-col"> + <h4>Resources</h4> + <ul> + <li><a href="https://docs.docker.com" target="_blank" rel="noopener">Docker Docs</a></li> + <li><a href="https://github.com/docker/docker-agent" target="_blank" rel="noopener">GitHub</a></li> + <li><a href="https://hub.docker.com/u/agentcatalog" target="_blank" rel="noopener">Agent Catalog</a></li> + <li><a href="https://www.docker.com/blog/" target="_blank" rel="noopener">Blog</a></li> + </ul> + </div> + <div class="site-footer-col"> + <h4>Company</h4> + <ul> + <li><a href="https://www.docker.com/company/" target="_blank" rel="noopener">About</a></li> + <li><a href="https://status.docker.com" target="_blank" rel="noopener">Status</a></li> + <li><a href="https://www.docker.com/legal/docker-terms-service/" target="_blank" rel="noopener">Terms</a></li> + <li><a href="https://www.docker.com/legal/docker-privacy-policy/" target="_blank" rel="noopener">Privacy</a></li> + </ul> + </div> + </div> + </div> + <div class="site-footer-bottom"> + <span>© {{ site.time | date: '%Y' }} Docker Inc. All rights reserved.</span> + <span>Docker Agent is open source under the <a href="https://github.com/docker/docker-agent/blob/main/LICENSE" target="_blank" rel="noopener">Apache 2.0 license</a>.</span> + </div> +</footer> diff --git a/docs/_includes/header.html b/docs/_includes/header.html index 210417cc5..3d39e14ae 100644 --- a/docs/_includes/header.html +++ b/docs/_includes/header.html @@ -2,13 +2,8 @@ <header class="header" role="banner"> <div class="header-inner"> <a href="{{ '/' | relative_url }}" class="header-logo" aria-label="Docker Agent docs home"> - <!-- Docker whale logo --> - <svg viewBox="0 0 50 36" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"> - <path d="M48.3 16.5c-.3-.2-2.6-1.3-5.1-1.3-.5 0-1 0-1.5.1-.6-2.2-2.6-3.2-2.7-3.3l-.5-.3-.3.5c-.4.8-.7 1.7-.8 2.6-.3 1.8.1 3.5 1.2 4.9-1.8 1-4.7 1.3-5.3 1.3H1.2c-.7 0-1.2.5-1.2 1.2 0 4.4 1.8 8.8 5.2 12C8.5 37.2 13.2 39 19 39c12.5 0 21.7-7.3 26-20.4 1.7 0 3.3-.5 4.1-2.1l.2-.4-.3-.2zM5.3 19.8H9c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3H5.3c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm5 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm-10.2-5h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm0-5h3.8c.2 0 .3-.1.3-.3V5.7c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm5.1 5h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3z" fill="#1D63ED"/> - </svg> - <span>Docker Agent</span> - <span class="logo-divider"></span> - <span class="logo-label">Docs</span> + <img class="docker-mark" src="{{ '/assets/docker-mark.svg' | relative_url }}" alt="" width="32" height="25"> + <span class="product-name">Docker Agent</span> </a> <div class="header-actions"> diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 01b0387f4..9dc4538dd 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -3,20 +3,29 @@ <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> - <title>{% if page.title %}{{ page.title }} – Docker Agent Docs{% else %}Docker Agent – Documentation{% endif %} + {% if page.title and page.url != '/' %}{{ page.title }} – Docker Agent Docs{% else %}Docker Agent β€” Run AI agents from YAML, like containers{% endif %} - + {% comment %} + Source path of the current page on disk, used by the right-column + \"Edit this page\" link in js/app.js. We point at GitHub's web editor + on the configured repo + branch. + {% endcomment %} + + + + + + - + - - + @@ -24,6 +33,7 @@ {% include header.html %}