Skip to content

Commit f02e2a5

Browse files
dvdksnclaude
andauthored
Revamp the guides section: taxonomy, single-page structure, and new landing/filter UX (#25338)
## 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>
1 parent ef2165d commit f02e2a5

302 files changed

Lines changed: 22994 additions & 24569 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

assets/css/utilities.css

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,33 @@
208208
}
209209
}
210210
}
211+
@utility scrollbar-hover {
212+
/* Firefox: hide the thumb until hover */
213+
scrollbar-width: thin;
214+
scrollbar-color: transparent transparent;
215+
&:hover {
216+
scrollbar-color: var(--color-gray-400) transparent;
217+
}
218+
.dark &:hover {
219+
scrollbar-color: var(--color-gray-600) transparent;
220+
}
221+
/* WebKit: reserve the track, reveal the thumb only on hover */
222+
&::-webkit-scrollbar {
223+
width: 8px;
224+
height: 8px;
225+
}
226+
&::-webkit-scrollbar-thumb {
227+
border-radius: 9999px;
228+
background-color: transparent;
229+
}
230+
&:hover::-webkit-scrollbar-thumb {
231+
background-color: var(--color-gray-400);
232+
}
233+
.dark &:hover::-webkit-scrollbar-thumb {
234+
background-color: var(--color-gray-600);
235+
}
236+
}
237+
211238
@utility chip {
212239
@apply border-divider-light dark:border-divider-dark inline-flex items-center gap-1 rounded-full border bg-gray-100 px-2 text-sm text-gray-800 select-none dark:bg-gray-700 dark:text-gray-200;
213240
}
@@ -217,7 +244,17 @@
217244
}
218245

219246
@utility breadcrumbs {
220-
font-size: 90%;
247+
/* Absolute size so breadcrumbs render identically inside and outside prose */
248+
font-size: calc(var(--text-base) * 0.9);
249+
}
250+
251+
/* Guides landing: collapse section spacing into a flat list while filtering.
252+
Grouped spacing is the static default; this only applies once the page is
253+
being filtered, so it never affects first paint (no layout jank). */
254+
.guides-flat > section {
255+
border-top-width: 0 !important;
256+
padding-top: 0 !important;
257+
padding-bottom: 0 !important;
221258
}
222259

223260
@utility topbar-button {

content/guides/_index.md

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,25 @@
11
---
22
title: Docker guides
33
linkTitle: Guides
4-
description: Explore the Docker guides
4+
description: Step-by-step tutorials, organized by what you're trying to do.
55
keywords: docker, guides, tutorials, learning paths, getting started
66
params:
77
icon: book-open
88
layout: landing
99
aliases:
1010
- /guides/language/
1111
- /language/
12+
- /guides/dhi-from-doi/
13+
- /guides/dhi-from-wolfi/
14+
- /guides/dhi-go-example/
15+
- /guides/dhi-nodejs-example/
16+
- /guides/dhi-python-example/
17+
- /guides/lab-docker-for-ai-redirect/
1218
- /learning-paths/
1319
---
1420

15-
Explore our collection of guides to learn how Docker can optimize your
16-
development workflows and how to use it with specific languages, frameworks, or
17-
technologies.
21+
Explore guides to learn how Docker can optimize your development workflows and
22+
how to use it with specific languages, frameworks, or technologies.
1823

1924
Can't find the guide you're looking for? Open an issue on the
20-
[docker/docs](https://github.com/docker/docs/issues/new) repository to let us
21-
know.
25+
[docker/docs](https://github.com/docker/docs/issues/new) repository.

content/guides/admin-set-up/_index.md

Lines changed: 0 additions & 108 deletions
This file was deleted.

content/guides/admin-set-up/comms-and-info-gathering.md

Lines changed: 0 additions & 75 deletions
This file was deleted.

content/guides/admin-set-up/deploy.md

Lines changed: 0 additions & 36 deletions
This file was deleted.

content/guides/admin-set-up/finalize-plans-and-setup.md

Lines changed: 0 additions & 77 deletions
This file was deleted.

0 commit comments

Comments
 (0)