## Description
Gordon answers everything in plain markdown, even when the answer is a
procedure or a comparison. Those answers are harder to scan than they
need to be. This PR lets Gordon put a small card inside its answer when
that helps:
- **Steps** for procedures, with commands in code boxes
- **Tables** for comparisons (limits, plans, options)
- **Notes** for warnings, active incidents or tips
- **Code snippets** for config files
- **Follow-up questions** as chips. Selecting one asks it as your next
question.
```
You can containerize it with docker init, then run it with Compose.
┌───────────────────────────────────────────────┐
│ Containerize a Node.js app │
│ ① Generate the Docker assets │
│ [ docker init ] │
│ ② Build and run the app │
│ [ docker compose up --build ] │
│ ▌ Use Docker Hardened Images for security │
│ ( How do I add a database service? ) │
└───────────────────────────────────────────────┘
Sources:
- https://docs.docker.com/guides/nodejs/
```
Short answers, explanations and greetings stay plain markdown.
### How it works
```
chat ── "I can draw cards" (ui: "openui-v1") ──▶ Gordon
chat ◀── markdown answer, with at most one ```openui-lang block ── Gordon
chat: draws the block as a card, everything else as markdown
```
- The chat sends one extra field with each question. Only then does
Gordon's backend tell the model it may add a card. Without the field,
answers are the same as today.
- A card is a fenced block of [OpenUI
Lang](https://www.openui.com/docs/openui-lang) inside the normal answer
text, so the conversation history and stored messages stay plain text.
- The chat draws the block with its own styles. Anything it doesn't
recognize is left out, and if the card code can't load, the block shows
as a plain code block.
### Visual change to all answers
Gordon's answers are no longer inside a grey bubble. A framed card
inside the grey bubble looked like a box in a box. Answers now sit on
the panel background at full width, and the card stands out as its own
block. Your own messages keep the blue bubble.
<!-- screenshots: before / after, light and dark -->
### Rollout
- Cards are **on in local builds and deploy previews**, and **off in
production**.
- To turn them on in production, set `params.gordon.cards: true` in
`hugo.yaml`.
- Gordon's backend already supports this, so no other change is needed.
### Other notes
- **Safety:** card text from the model is only ever inserted as text,
never as HTML.
- **Page weight:** the card code (about 120 KB gzipped) is a separate
bundle. It's only downloaded when an answer first contains a card, never
on page load.
- **Copy button:** copies the answer with cards written out as markdown
(numbered steps, a table, `> [!NOTE]`), not the raw card code. Follow-up
chips are left out.
- **Instructions Gordon gets:** the prompt lives entirely in Gordon's
backend, which injects it when the chat sends `ui: "openui-v1"`. This
repo only has the component list the chat draws
(`assets/js/gordon-cards/components.mjs`). The backend's card prompt
describes the same components, so when adding or changing one, the
backend's prompt changes with it.
- **New dependencies:** `@openuidev/lang-core` (the OpenUI Lang parser)
and `zod`, pinned. Its usage telemetry never runs in a browser, and
`.npmrc` already blocks install scripts.
### How to test
1. Run `docker compose watch` and open http://localhost:1313. Local
builds use Gordon's staging backend.
2. Open Gordon from the header and ask:
- **Should show a card:** "How do I containerize my Node.js app?", "What
are the Docker Hub pull limits?", "How do I set up a registry mirror?"
- **Should stay plain text:** "What is Docker Scout?", "hi"
3. Select a follow-up chip. It should ask that question.
4. Select **Copy** on an answer with a card. The pasted text should be
markdown.
5. Reload the page. Cards should come back from the conversation
history.
6. Check dark mode.
7. In the browser's Network tab, check:
- each question to `/public/ask` includes `"ui": "openui-v1"`;
- `gordon-cards.js` only loads after the first answer with a card.
## Related issues or tickets
<!-- none public -->
## Reviews
- [x] Technical review
- [ ] Editorial review
- [ ] Product review
## Summary
**Problem:** Mermaid diagrams briefly showed their raw source before the
SVG appeared, stayed on the wrong palette after a light/dark theme
toggle, and could leave Mermaid's error graphic in the page when a
diagram failed to parse.
**Why this change:** Diagrams are used more often in the docs, so the
renderer needs to match the site theme and avoid flashing source text
while SVGs load.
**Solution:** Replace `mermaid.run()` with a controlled
`mermaid.render()` loop that caches each block's source, skips stale
async results, re-renders when the `<html>` dark class changes,
suppresses Mermaid's default error SVG, and hides `pre.mermaid` until an
SVG is present (or a render error sets `data-error` so the source can
still be inspected).
@netlify /get-started/docker-concepts/the-basics/what-is-a-registry/
Preview:
https://deploy-preview-26304--docsdocker.netlify.app/get-started/docker-concepts/the-basics/what-is-a-registry/
Example of pre-fix behavior:
https://deploy-preview-26283--docsdocker.netlify.app/accounts/organization/
Generated by Cursor
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
The Build Cloud, Compose, Scout, Testcontainers Cloud, and
container-supported development guides mostly repeat product benefits
and introduce videos instead of teaching distinct tasks.
Remove these five guides and their unused images, update incoming links,
and redirect all former page and chapter URLs to the relevant product
docs or hands-on lab. Keep both administration guides.
@netlify /reference/api/
[Preview the API
reference](https://deploy-preview-26048--docsdocker.netlify.app/reference/api/)
Adds a shared API reference experience for Hub, DVP, and Registry: a
catalog, operation navigation, linked schemas, request and response
examples, and matching HTML and Markdown output. A validation and
generation pipeline prepares the reference data for Hugo and runs as
part of Docker and Netlify builds.
Migrates the three specifications to OpenAPI 3.2, correcting response
shapes, nullable fields, and authentication and token examples. The Hub
migration also corrects SCIM contracts and CSV exports; DVP gains
complete report response schemas and examples. Registry keeps its
documented Hub-specific subset, with authentication and media
negotiation expressed through OpenAPI security and content fields.
Validation is strict for both checks and generation, with no exception
baseline or bypass flag. The build uses the migrated sources directly,
without migration scripts or records.
Page and specification URLs remain stable, including the DVP alias.
Operation and schema anchors change. Engine and Governance retain their
existing references.
Validated locally with Go tests, strict validation of all three
specifications (zero diagnostics), scoped formatting and lint, and a
full Hugo build checking all 176 HTML/Markdown page pairs, example
parity, reference links, and byte-identical published specifications. A
browser check confirmed raw CSV rendering and the generated request
header. No live API requests were made.
## What
A full revamp of the `/guides` section — taxonomy, structure, and UX.
Preview: https://deploy-preview-25338--docsdocker.netlify.app/guides/
### Taxonomy & structure
- Replaces the sprawling 24-tag set with a focused 9-tag taxonomy
aligned to use case / SDLC: **Languages & frameworks, AI, Testing,
CI/CD, Security, Databases, Deployment, Admin, Hands-on labs**.
- Removes the languages taxonomy entirely (`data/languages.yaml` and all
`languages:` front matter).
- Collapses all multi-page guide series into single pages, with aliases
so old sub-page URLs continue to resolve.
- Deletes redirect-only shim pages and flattens directory-wrapped single
pages.
### Landing page (`/guides/`)
- A clean index: hero, then category sections listing each guide as a
plain **title / summary** row.
- **Browse rail** (sticky, left): click a topic to filter the page to
just that topic's guides; "All guides" resets. A count + Clear bar
appears while filtering.
- **Text filter**: instant client-side search over title, summary, and
tags. Topic filter and text search are mutually exclusive and share the
same flat-list view.
- No more "Featured guides" section.
### Guide content pages
- Removes the left sidebar for the guides section (mobile drawer kept).
- Centered reading column (`92ch`) with the TOC taking the remaining
width.
- Summary rendered as a lead paragraph under the h1.
- TOC scrollbar auto-hides until hover; breadcrumbs render at a
consistent size inside and outside `prose`.
## Notes
- Deep full-text search across guide bodies is still handled by the
existing site-wide Pagefind (⌘K); the landing filter is the fast
metadata-narrowing surface.
- `series.html` is retained — it's still used by `get-started` pages.
## Validation
- Site builds clean locally (Hugo dev server, no errors / broken refs).
- All collapsed sub-page URLs redirect via aliases.
## Follow-ups
- Prune guides that we no longer need/want
- Tighten the guides that span too many concepts (e.g. language guides;
remove cicd/deploy/sscs)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds a Hugo codeblock render hook that turns ```mermaid fences into
<pre class="mermaid"> containers, plus a lazily-loaded mermaid bundle
that only ships on pages that actually contain a diagram. Mirrors the
existing YouTube embed pattern (Store flag + conditional script tag in
baseof) so the main scripts.js bundle stays unchanged.
Hugo's html/template JS-escapes string values inside <script> blocks.
Calling jsonify per-field produced quoted strings like "https://..."
which were then re-escaped, embedding literal quote characters in the
endpoint value passed to the SDK.
Fix by jsonifying the whole config dict at once and marking it safeJS
so html/template does not apply a second round of escaping.
Also extract the environment ternary out of the Marlin constructor call
for readability.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Introduces @docker/marlin-sdk-web-public for first-party pageview and
click analytics, bundled into scripts.js via Hugo's existing js.Build
pipeline. Config is emitted to window.__marlinConfig from head.html and
gated to prod/staging only.
Renames data-heap-id attributes on the markdown-dropdown buttons to
marlin-action so they are picked up by the SDK's auto-click tracking.
TODO: replace the REPLACE-ME endpoint placeholders in hugo.yaml with
the canonical Marlin ingestion URLs from the data-platform team.
TODO: heap.track() calls in youtube-script.html are left in place —
the public SDK exposes no equivalent track() method, so video
play/pause events cannot be migrated yet.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Replaces @material-symbols/svg-400 (5.5 MB) with heroicons (488 KB) — an
11x reduction in icon asset size. Heroicons uses a single consistent
distribution format (24px solid SVGs, fill="currentColor") eliminating
the need for the separate utils/svg.html partial, the icon-svg-stroke CSS
utility, and the dual-path resolution logic in icon.html.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
> 🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
`theme.js` unconditionally wrote the resolved preference to
`localStorage` on every page load, permanently locking in a concrete
`"light"` or `"dark"` value even for first-time visitors — making it
impossible to track OS preference changes after any site visit. Removed
the unconditional `localStorage.setItem` from `theme.js` so the early
script only reads (never writes); the Alpine.js toggle in `header.html`
now cycles through three states (light → dark → auto), with "auto"
removing the `theme-preference` key and resolving from
`prefers-color-scheme` with a live `matchMedia` change listener so the
theme updates immediately when the OS preference changes. A contrast
icon indicates auto mode; all three icon spans are driven by Alpine
`x-show` directives rather than pure CSS dark-mode classes.
**Verified:** logic matches the standard three-state pattern;
`prefers-color-scheme` media query and `matchMedia` change listener are
the canonical browser APIs for system-preference tracking.
**Checked:** no other files reference `theme-preference` or the theme
toggle; no CSS changes required.
Closes#23177
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add pagefind-component-ui.css and .js assets
- Replace search bar with custom button that opens modal
- Add custom result template with Tailwind classes
- Add dark mode styling for modal and result highlights
- Support Cmd/Ctrl+K keyboard shortcut
Assisted-By: cagent
Configure marked.js to escape HTML entities in text tokens while
preserving code blocks. This allows angle brackets like <target-name>
to display correctly in regular text without being interpreted as HTML
tags, while keeping code examples intact.
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Harmonize buttons in the nav and automatically copy the search term to
the AI widget.
Uses "cmd k" to open the AI widget instead of search.
Touch up search results.
<!--Delete sections as needed -->
## Description
<!-- Tell us what you did and why -->
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
- Extract classes to utilities and components.
- Reduce number of colors used.
- Harmonize button colors.
- Restyle admonitions.
- Move **Page options** button to main article.
- Various color tweaks.
Trung Nguyen
David Karlsson
Alexa KristensenandCursor
Derek Misler
Shakirth Anisha
ArthurandUsha Mandya
Craig Osterhout
Sarah Sanders
Allie Sadler