Revamp the guides section: taxonomy, single-page structure, and new landing/filter UX#25338
Draft
dvdksn wants to merge 10 commits into
Draft
Revamp the guides section: taxonomy, single-page structure, and new landing/filter UX#25338dvdksn wants to merge 10 commits into
dvdksn wants to merge 10 commits into
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
github-actions
Bot
added
area/build
Phase 1 of the guides section revamp: - Replace 24-tag taxonomy with 7 focused use-case/SDLC tags: ai, testing, cicd, security, admin, databases, deployment - Remove language taxonomy entirely (delete data/languages.yaml, strip languages: front matter from all guides) - Delete 6 redirect shim pages (dhi-from-doi, dhi-from-wolfi, dhi-go-example, dhi-nodejs-example, dhi-python-example, lab-docker-for-ai-redirect) - Flatten 3 directory-wrapped single pages (bake, compose-bake, zscaler) - Retag all ~100 guide pages with new taxonomy - Move all tags: to params.tags for consistent placement - Collapse 47 multi-page guide series into single _index.md files (180 sub-pages merged; headings demoted one level, sub-page titles become H2 sections) - Add URL aliases for all deleted sub-pages so old URLs redirect to the parent guide Phase 2 (template rewrite: tag-pill UX, remove language filter, simplify guide cards) follows in a separate session. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Landing page (layouts/guides/landing.html): - Remove sidebar filter (checkboxes, language buttons) - Hero section: guide count, large "Guides." heading, description - Sticky left "Jump to" nav with numbered categories and counts - Sections per tag with 2-column card grid (title | summary) - Scrollspy via IntersectionObserver highlights active section - No Alpine.js filtering — browse by scrolling/jumping Content pages (layouts/guides/list.html, new): - Clean left sidebar: just mainnav, no guide-specific metadata - Slightly wider article (max-w-5xl) - TOC stays in right column via baseof.html default Other: - data/tags.yaml: add description to each tag (shown under section heading) - layouts/_partials/guide-languages.html: deleted (languages removed in Phase 1) - layouts/_partials/sidebar/guides.html: simplify (remove stepper, resource_links, languages — now just title, summary, tags, time, back link) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Tag taxonomy expanded from 7 to 9 tags: - languages (new): 17 language/framework guides pulled from cicd (angular, bun, cpp, deno, dotnet, golang, java, laravel, nextjs, nodejs, php, python, r, reactjs, ruby, rust, vuejs) - cicd: now pipeline/build tools only (gha, bake, azure-pipelines, docker-build-cloud, docker-compose, opentelemetry, etc.) - labs (new): 12 interactive lab guides previously scattered across ai, security, and cicd; now grouped together at the end Landing page tag order: languages, ai, testing, cicd, security, databases, deployment, admin, labs Also fixes carried over from build testing: - Broken front matter delimiters in container-supported-development.md and dhi-openshift.md (resource_links[]--- → newline before ---) - Orphaned url: lines in 16 guide files (leftover resource_links children) - 96 broken relative links in 18 merged guide _index.md files (containerize.md, configure-github-actions.md etc. → ./ or anchor) - /guides/docker-scout/sbom.md and s3c.md refs in sbom.md → /guides/docker-scout/ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…rome Guide content pages now use a clean, centered reading layout: - Drop the 320px left sidebar for the whole guides section (baseof.html conditions the desktop sidebar on type != guides; mobile drawer kept) - Remove the obsolete /guides/** -> layout: series cascade in hugo.yaml so collapsed guides route to guides/list.html instead of the old series layout - New guides/single.html + updated guides/list.html: centered reading column (max-w-[92ch]) with the TOC taking the remaining width, justify-center so the pair sits balanced rather than left-heavy - Render the guide summary as a lead paragraph under the h1 (content-default) - aside.html: auto-hide the TOC scrollbar until hover (new scrollbar-hover utility) - breadcrumbs: use an absolute font-size so they render identically inside prose (guide pages) and outside it (landing) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Instant client-side filter (Alpine.js) matching title, summary, and tags across the already-rendered guide list; multi-word queries are AND-matched - Refined search input with inline clear button and Esc-to-clear - While filtering: hide the jump-to rail and go single-column full-width, flatten the grouped sections into one list, and show a "N of M guides" meta bar with a Clear action - Container fills the viewport (min-height) so a single result no longer collapses the page - Whole-row link cards with hover affordance (arrow), plus a polished empty-results state Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Convert every directory-based guide from a branch bundle (_index.md = section) to a leaf bundle (index.md = single page). URLs and any co-located images are preserved; the guides are now kind=page, not sections. - Re-collapse the Node.js guide on top of main's refresh (docker#25319): merge the refreshed containerize/develop/run-tests/configure-github-actions/ secure-supply-chain/deploy topics into one page, drop the languages field, move tags under params ([languages]), and add aliases for the old /guides/nodejs/<topic>/ URLs. - Landing: enumerate guides with RegularPagesRecursive instead of .Pages so every guide is listed (now that they're regular pages), including the nested frameworks/laravel guide that the non-recursive .Pages missed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
dvdksn
force-pushed
the
worktree-guides-revamp
branch
from
ff4b077 to
fe8c2af
Compare
Hugo's --printUnusedTemplates (run with --panicOnWarning in CI) flagged
five templates left unused after the guides revamp. Delete them:
- _partials/guide-tags.html tags are shown as landing sections now,
not chips
- _partials/guides-stepper.html no multi-page series remain
- _partials/sidebar/guides.html guide pages use a mainnav-only left rail
- guides/list.html all guides are single pages; the section
root uses the landing layout
- redirect/single.html its only users were the DHI redirect
shims removed in the taxonomy pass
Also drop the now-dead type==guides branch from baseof's default left
block (it referenced the deleted sidebar/guides.html).
Verified: hugo --gc --minify --panicOnWarning --printUnusedTemplates
builds clean with no unused templates.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- genai-video-bot, pre-seeding: remove stray "---" lines that a Phase 1 front-matter delimiter fix mistakenly inserted after lines ending in dashes (the .env separator and a psql table rule). Those lines broke out of indented code fences, so markdownlint saw code as headings (MD022/MD023/MD025) and a dangling fence (MD040). - cpp: repoint a stale body link from the old /guides/language/cpp/ multistage/ path (collapsed away) to /guides/cpp/, fixing the htmltest broken-link error. Front-matter aliases keep the old paths intact. Verified: markdownlint clean on both files; hugo --gc --minify --panicOnWarning --printUnusedTemplates builds clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Guide rows are now plain title/summary links: drop the rounded-corner card, hover background, and hover arrow; the title is a regular hover:underline link. - Turn the left "Browse" rail into a topic filter. Clicking a topic shows only that topic's guides (with an "All guides" reset and a count + Clear bar); the default view still renders every guide, so in-page find and the text search keep working across the full list. Text search and topic filter are mutually exclusive and share the same flat-list view. - Drop the old jump-scroll/scrollspy nav behavior in favor of filtering. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The section spacing and the nav highlight colors were only applied via Alpine :class bindings, so before Alpine booted the sections rendered with no padding (then jumped down once it applied) and the nav buttons rendered with no color (all looking "selected" until inactive ones dimmed). - Move the grouped section spacing (border-t, py-12) into the static class so first paint matches the initial state. - Give the nav container a default gray text color so buttons inherit the inactive look pre-Alpine. - Preserve the flat-list-while-filtering look with a .guides-flat > section rule toggled on the container only when filtering, so it never affects first paint. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A full revamp of the
/guidessection — taxonomy, structure, and UX.Preview: https://deploy-preview-25338--docsdocker.netlify.app/guides/
Taxonomy & structure
data/languages.yamland alllanguages:front matter).Landing page (
/guides/)Guide content pages
92ch) with the TOC taking the remaining width.prose.Notes
series.htmlis retained — it's still used byget-startedpages.Validation
Follow-ups
🤖 Generated with Claude Code