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 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 +
+
When to use it
+

Body text.

+
+``` + +- `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 @@ + 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 @@