docs: convert to portable Markdown and wire docs.docker.com validation

.github/workflows/docs-upstream.yml

@@ -0,0 +1,33 @@
+# Validates that changes under docs/** still build correctly on
+# docs.docker.com, by running docker/docs' reusable validate-upstream
+# workflow against this repo's commit (same pattern as buildx/compose).
+#
+# Until docker/docs mounts the docker-agent Hugo module (phase 2.1 of
+# https://github.com/docker/docker-agent/issues/3371), the validation
+# builds docs.docker.com without mounting these pages and is a no-op.
+name: docs-upstream
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".github/workflows/docs-upstream.yml"
+      - "docs/**"
+  pull_request:
+    paths:
+      - ".github/workflows/docs-upstream.yml"
+      - "docs/**"
+
+jobs:
+  validate:
+    # Tracks docker/docs main; bump the pin when validation needs newer docs changes.
+    uses: docker/docs/.github/workflows/validate-upstream.yml@8255e2bd5f08f1645c0ef677598d2c5f0555e336 # main
+    with:
+      module-name: docker/docker-agent

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: docs
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+
+jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # docs/.markdownlint-cli2.yaml is auto-discovered; passing it via
+      # `config:` would merge its `**/*.md` globs and lint the whole repo.
+      - name: Lint Markdown
+        uses: DavidAnson/markdownlint-cli2-action@992badcdf24e3b8eb7e87ff9287fe931bcb00c6e # v20.0.0
+        with:
+          globs: "docs/**/*.md"
+
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Check internal links
+        uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2.7.0
+        with:
+          # 404.md is Jekyll-only and keeps a Liquid href; skip it.
+          args: --offline --include-fragments --no-progress --root-dir "${{ github.workspace }}/docs" --exclude-path docs/404.md "docs/**/*.md"
+          fail: true

docs/.markdownlint-cli2.yaml

@@ -1,12 +1,13 @@
-# markdownlint configuration for Jekyll docs
+# markdownlint configuration for the docs
 #
-# These docs mix Markdown with HTML blocks (callouts, cards, feature grids).
-# Rules that conflict with this pattern are disabled.
+# The docs are portable Markdown rendered by both Jekyll (github.io) and
+# Hugo (docs.docker.com via module mount). Rules that conflict with the
+# established docs style are disabled.
 
 config:
   default: true
 
-  # Allow inline HTML — callouts, cards, and feature-grids are HTML
+  # Allow inline HTML — the landing page and a few widgets (<kbd>, images) use it
   MD033: false
 
   # Don't enforce line length — HTML blocks and tables often exceed 80 chars
@@ -15,6 +16,15 @@ config:
   # Allow multiple top-level headings — front matter title + # Heading is normal
   MD025: false
 
+  # Shell samples deliberately use "$ " prompts (see STYLE.md § Code samples)
+  MD014: false
+
+  # Adjacent > [!NOTE] alerts are separated by a blank line by design
+  MD028: false
+
+  # Don't enforce table pipe alignment
+  MD060: false
+
   # Allow duplicate headings — different sections may reuse heading text
   MD024:
     siblings_only: true

docs/STYLE.md

@@ -13,6 +13,7 @@ and examples consistent across every page on this site.
 | 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`
 
@@ -28,7 +29,7 @@ A simple rule of thumb:
 
 ## Code samples
 
-- All shell prompts use `$ ` (dollar + space) and the command on the
+- All shell prompts use `$` followed by a space, with 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.
@@ -38,21 +39,34 @@ A simple rule of thumb:
 
 ## Callouts
 
-Use the existing pattern; the new visual style does the rest:
+Use GitHub-style alerts — they render natively on docs.docker.com and
+are upgraded to the styled callout panels on github.io:
 
 ```markdown
-<div class="callout callout-tip" markdown="1">
-<div class="callout-title">When to use it</div>
-  <p>Body text.</p>
-</div>
+> [!TIP]
+> **When to use it**: Body text.
 ```
 
-- `callout-info` — neutral context
-- `callout-tip` — positive, "consider this"
-- `callout-warning` — caution, breaking, security
+- `[!NOTE]` — neutral context
+- `[!TIP]` — positive, "consider this"
+- `[!WARNING]` — caution, breaking, security
+
+An optional bold lead-in (`**Title**:`) names the callout; skip it when
+the kind alone says enough. Don't prefix it with an emoji — the icon
+badge already provides one.
+
+## Links
+
+Use plain relative Markdown links between pages, including the
+`index.md` filename, so both renderers resolve them. From a page two
+levels deep (e.g. `concepts/agents/index.md`):
+
+```markdown
+See [Models](../../concepts/models/index.md) for details.
+```
 
-Don't prefix the title with an emoji — the icon badge already provides
-one.
+Never use Liquid (`relative_url`) or root-absolute paths — they break
+when the docs are mounted on docs.docker.com.
 
 ## Glossary one-liners
 

docs/community/contributing/index.md

@@ -1,7 +1,7 @@
 ---
 title: "Contributing"
 description: "docker-agent is open source. Here's how to set up your development environment and contribute."
-permalink: /community/contributing/
+keywords: docker agent, ai agents, community, contributing
 ---
 
 # Contributing
@@ -17,12 +17,8 @@ _docker-agent is open source. Here's how to set up your development environment
 - [Task](https://taskfile.dev/installation/)
 - [golangci-lint](https://golangci-lint.run/docs/welcome/install/local/)
 
-<div class="callout callout-info" markdown="1">
-<div class="callout-title">Platform Support
-</div>
-  <p>macOS and Linux are fully supported for development. On Windows, use <code>task build-local</code> to build via Docker.</p>
-
-</div>
+> [!NOTE]
+> **Platform Support**: macOS and Linux are fully supported for development. On Windows, use `task build-local` to build via Docker.
 
 ### Build from Source
 
@@ -86,12 +82,8 @@ Key conventions:
 
 File issues on the [GitHub issue tracker](https://github.com/docker/docker-agent/issues). Please:
 
-<div class="callout callout-info" markdown="1">
-<div class="callout-title">See also
-</div>
-  <a href="{{ '/community/troubleshooting/' | relative_url }}">Troubleshooting</a> — Common issues and debug mode. <a href="{{ '/community/telemetry/' | relative_url }}">Telemetry</a> — What data is collected and how to opt out.
-
-</div>
+> [!NOTE]
+> **See also**: [Troubleshooting](../troubleshooting/index.md) — Common issues and debug mode. [Telemetry](../telemetry/index.md) — What data is collected and how to opt out.
 
 - Use the included issue template
 - Search for existing issues before creating new ones
@@ -105,12 +97,8 @@ File issues on the [GitHub issue tracker](https://github.com/docker/docker-agent
 4. **Sign** your commits with `git commit -s` (DCO required)
 5. **Open a pull request** against the `main` branch
 
-<div class="callout callout-tip" markdown="1">
-<div class="callout-title">Tip
-</div>
-  <p>Use the dogfooding agent (<code>docker agent run ./golang_developer.yaml</code>) to help write and review your changes before submitting.</p>
-
-</div>
+> [!TIP]
+> Use the dogfooding agent (`docker agent run ./golang_developer.yaml`) to help write and review your changes before submitting.
 
 ## Sign Your Work
 

docs/community/opentelemetry/index.md

@@ -1,12 +1,12 @@
 ---
 title: "OpenTelemetry Tracing"
 description: "Export docker-agent traces to any OTLP backend, including Langfuse and LangSmith, for debugging agentic workflows."
-permalink: /community/opentelemetry/
+keywords: docker agent, ai agents, community, opentelemetry tracing
 ---
 
 # OpenTelemetry Tracing
 
-_docker-agent can export OpenTelemetry traces of an agent run to any OTLP/HTTP backend. This is separate from [product-analytics telemetry](/community/telemetry/) and is opt-in via the `--otel` flag._
+_docker-agent can export OpenTelemetry traces of an agent run to any OTLP/HTTP backend. This is separate from [product-analytics telemetry](../telemetry/index.md) and is opt-in via the `--otel` flag._
 
 When enabled, docker-agent emits OpenTelemetry GenAI (`gen_ai.*`) and MCP (`mcp.*`) spans following the [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Spans cover the agent turn, model calls (with token usage and cost attributes), tool calls, MCP client/server activity, sub-agent hand-offs, and provider fallbacks. W3C `traceparent` context is propagated so the whole run renders as a single connected trace tree.
 
@@ -29,19 +29,13 @@ docker-agent reads the standard OTLP environment variables:
 | `OTEL_RESOURCE_ATTRIBUTES` | Extra resource attributes merged into every span. |
 | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Set to `true` to capture prompt and response message content as span attributes. Off by default. |
 
-<div class="callout callout-info" markdown="1">
-<div class="callout-title">Base endpoint, not the full signal URL
-</div>
-  <p>Set <code>OTEL_EXPORTER_OTLP_ENDPOINT</code> to the <strong>base</strong> endpoint (for example <code>https://cloud.langfuse.com/api/public/otel</code>). docker-agent appends <code>/v1/traces</code> for you, matching the value documented by Langfuse and LangSmith. A bare <code>host:port</code> is also accepted and gets <code>https://</code> (or <code>http://</code> for localhost).</p>
+> [!NOTE]
+> **Base endpoint, not the full signal URL**: Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the **base** endpoint (for example `https://cloud.langfuse.com/api/public/otel`). docker-agent appends `/v1/traces` for you, matching the value documented by Langfuse and LangSmith. A bare `host:port` is also accepted and gets `https://` (or `http://` for localhost).
 
-</div>
-
-<div class="callout callout-warning" markdown="1">
-<div class="callout-title">Message content can contain sensitive data
-</div>
-  <p><code>OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT</code> is off by default because chat history routinely contains PII, secrets, and internal documents. Enable it only for backends and environments where exporting that content is acceptable.</p>
-
-</div>
+> [!WARNING]
+> **Message content can contain sensitive data**:
+>
+> `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` is off by default because chat history routinely contains PII, secrets, and internal documents. Enable it only for backends and environments where exporting that content is acceptable.
 
 ## Backends
 
@@ -89,12 +83,8 @@ export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
 docker agent run agent.yaml --otel
 ```
 
-<div class="callout callout-info" markdown="1">
-<div class="callout-title">Langfuse and LangSmith ingest traces only
-</div>
-  <p>Both backends accept the traces signal only. docker-agent also wires metric and log exporters at the same endpoint, so their periodic exports return <code>404</code> against trace-only backends. This is harmless to traces but appears in the debug log. Point a full OTLP collector at the endpoint if you also want metrics and logs.</p>
-
-</div>
+> [!NOTE]
+> **Langfuse and LangSmith ingest traces only**: Both backends accept the traces signal only. docker-agent also wires metric and log exporters at the same endpoint, so their periodic exports return `404` against trace-only backends. This is harmless to traces but appears in the debug log. Point a full OTLP collector at the endpoint if you also want metrics and logs.
 
 ## Inspecting traces locally
 

docs/community/telemetry/index.md

@@ -1,7 +1,7 @@
 ---
 title: "Telemetry"
 description: "docker-agent collects anonymous usage data to help improve the tool. Telemetry can be disabled at any time."
-permalink: /community/telemetry/
+keywords: docker agent, ai agents, community, telemetry
 ---
 
 # Telemetry
@@ -20,12 +20,8 @@ $ TELEMETRY_ENABLED=false docker agent run agent.yaml
 $ export TELEMETRY_ENABLED=false
 ```
 
-<div class="callout callout-info" markdown="1">
-<div class="callout-title">Default
-</div>
-  <p>Telemetry is **enabled by default**. Set <code>TELEMETRY_ENABLED=false</code> to opt out.</p>
-
-</div>
+> [!NOTE]
+> **Default**: Telemetry is **enabled by default**. Set `TELEMETRY_ENABLED=false` to opt out.
 
 ## What's Collected ✅
 
@@ -43,12 +39,8 @@ $ export TELEMETRY_ENABLED=false
 - API keys or credentials
 - Personally identifying information (PII)
 
-<div class="callout callout-tip" markdown="1">
-<div class="callout-title">See events locally
-</div>
-  <p>Use <code>--debug</code> to see telemetry events printed to the debug log without sending them anywhere additional.</p>
-
-</div>
+> [!TIP]
+> **See events locally**: Use `--debug` to see telemetry events printed to the debug log without sending them anywhere additional.
 
 ```bash
 docker agent run agent.yaml --debug