## 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>
Two related style-conformance fixes across `content/guides/`, motivated
by a recent audit of guide-page style against STYLE.md, COMPONENTS.md,
and AGENTS.md.
## What changed
### 1. Add missing `keywords:` frontmatter to 104 guide pages
`keywords` is documented as required (AGENTS.md, COMPONENTS.md) but was
missing from 10 single-file guides, 8 `_index.md` landing pages, and 86
chapter pages. Each page now has a meaningful, page-specific
comma-separated keyword list derived from its title, lead content, and
sibling pages where applicable.
Examples of the convention applied:
-
`content/guides/testcontainers-java-spring-boot-kafka/create-project.md`
— `testcontainers, java, spring boot, kafka, mysql, project setup`
- `content/guides/docker-compose/why.md` — `docker compose,
multi-container, yaml, services, orchestration, application`
Post-change verification confirms zero guide pages under
`content/guides/` are missing the field.
### 2. Remove bold-for-emphasis from 14 guide pages
STYLE.md restricts bold to UI elements only — never for emphasis,
product names, command names, or the `**Term**: description`
subsection-label pattern. Cleaned up the top-15 offender files
identified by raw bold-span count (code blocks excluded). One file
(`jupyter.md`, 32 spans) was untouched because all spans were legitimate
UI references.
Shape of the work across 14 files:
- ~60 `**Term**: description` list items de-bolded
- ~10 identifiers/values/commands converted to backticks (e.g.
`**my-mysql**` → `` `my-mysql` ``)
- ~10 product/emphasis bolds removed
- 6 bolded link texts un-bolded
- 3 blockquote-style notes converted to `> [!NOTE]` callouts
Legitimate UI bolds (button names, menu items, field labels, tab names)
were preserved throughout. `databases.md` kept 47 of 49 spans for this
reason — only port-mapping value and container name were converted to
backticks.
## Out of scope
The audit surfaced other items not addressed here:
- Series `params` block missing on all 48 `_index.md` landing pages —
this is a "decide what's authoritative" question that warrants
discussion before code changes.
- Vale prose violations (`just`, `easily`, `we`, etc.) — concentrated in
~5 files; can land separately.
- Heading numbering convention (`## Step N:` vs `## N.` vs plain) —
undocumented; should be pinned down in STYLE.md or COMPONENTS.md before
mechanical sweeps.
## Verification
- `markdownlint` (via `scripts/lint.sh`) clean on all changed files.
- Vale not installed locally; relying on CI to validate prose.
- `git diff --stat` confirms scope: 118 unique files, all under
`content/guides/`. No vendored, layout, or generated-file changes.
## Description
Fixed a minor typo in the documentation/source file. No functional or
behavioral changes; this is purely a text correction to improve clarity.
## Related issues or tickets
N/A. Just fixed a single typo
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
<!--Delete sections as needed -->
## Updated guides/databases.md to consistently use `docker rm --force
my-sql` in the guide instead of sometimes using `docker remove --force
my-mysql`
<!-- Tell us what you did and why -->
## Updated for consistency so all commands use `rm` also I think
`remove` is not a valid docker command?
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
## Description
- Fixed minor typos like `msyql`, `model`, `.json|`.
- Although `docker remove` works due to CLI fallback, it's not an
official command. Replaced with `docker rm` for correctness and clarity.
- Replaced `docker-compose.yml` with `compose.yaml` to align with the
[Compose
specification.](https://github.com/compose-spec/compose-spec/blob/main/03-compose-file.md)
- Rework the filtering system for guides to drop the use of the
"products", "subjects", and "levels" taxonomies in favor of "tags" and
"languages"
- This change means that the existing taxonomy functionality integrates
better with the guides filtering, and there are fewer parameters to
keep in mind when adding metadata to a guide
- Only two taxonomies instead of three
- Only one of those taxonomies are guides-specific (languages)
- The other taxonomy (tags) works for all content
- Updates how tags and tag pages are rendered in general
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
