## 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.
