Canonicalize and improve docs navigation and brand-asset previews

Problem

Five parts of the public documentation family currently obscure rather than support discovery:

1. A short detail-page table of contents is rendered as a wide, permanently open <details> block with links spread across columns. On the supplied AI Dev Tools prerequisites screenshot, three links consume a full-width strip and look decorative rather than showing where the reader is.
2. The /docs/ landing page puts course guides before Community and activities, even though the requested top-level orientation is the community and its shared activities.
3. /docs/general/brand-assets/ renders source PNGs as ordinary prose images. Large wordmarks and 1024px icons become an oversized vertical sequence instead of a usable preview/download catalogue.
4. Documentation canonicals still use trailing slashes, and the current guide order puts Brand Assets after Jobs: a reader can move from Suspicious Job Postings into Brand Assets as though those were the next pages in one topic.
5. The upstream docs root index.md still renders a legacy Visit DataTalks.Club body button. On the unified site this is a redundant self-handoff, and the user explicitly requested its removal from the supplied screenshot.

These are one bounded documentation-presentation issue: improve hierarchy and navigation while keeping headings, groups, routes and asset bytes source-derived, with only the two explicit source edits below.

Normative references

• _docs/design/design-system.md — reading measure, shell, focus, 44px targets, contrast, responsive layout and semantic navigation.
• _docs/architecture/database-only-content.md — public docs content/assets remain database-owned and source-ingested; presentation must not introduce a file-backed fallback.
• _docs/specs/03-github-content-and-people.md — published docs paths/content provenance.
• _docs/specs/02-url-link-seo-compatibility.md — canonical paths, one-hop compatibility redirects, raw-query preservation and link/SEO consistency; its current trailing-slash docs rule must be amended by this issue.
• Current implementation: templates/review/docs_home.html, templates/review/docs_detail.html, templates/review/_docs_styles.html, content/docs_presentation.py, content/review_views.py, and content/tests/test_docs_pages.py.
• Intake screenshot: 20260917-223058-01-annotated-image-20260917-203058.png at /docs/courses/ai-dev-tools-zoomcamp/prerequisites/#required-skills.

Scope

Detail-page table of contents

• Replace the wide, open docs-on-page disclosure with a compact semantic table-of-contents navigation for pages with at least three source headings.
• Derive link labels, levels and fragments only from the rendered source heading inventory. Preserve document order and hierarchy: H3/H4 entries belong visually and semantically beneath their nearest preceding higher-level heading rather than becoming one flat list.
• Present the short common case (three H2s) as a restrained single-column/compact block within the reading measure, not a two-column band stretched across the content width.
• Mark the current section with aria-current="location" and a non-color-only visual treatment. Initialize from a valid URL fragment, update after TOC activation, and update as the reader moves through sections when enhancement is available. With JavaScript unavailable, every normal anchor remains visible and functional.
• Apply a heading scroll offset so fragment navigation lands with the target heading visible below the sticky shell. Do not rewrite source IDs or create duplicate anchors.
• The supported article outline is one H1 page title followed by H2 sections, optional H3 subsections and optional H4 detail headings. Reject a source document before activation when it uses H5/H6 or skips downward over a level (for example H2→H4); do not flatten or silently normalize an invalid outline in the template.

Guide-rail hierarchy

• Make direct leaf pages visually distinct from group rows such as Community Guidelines and Jobs, which currently look identical to leaves such as Slack and Brand Assets.
• A group row visibly advertises that it contains child pages through a child count and/or chevron plus an accessible label even when that group is not the active branch. It remains a real link to the group page, not a fake disclosure control.
• When the current page is a group's descendant, expand exactly that active group. Render its child pages as a nested ordered list with clear indentation/connector and one aria-current="page" marker on the active page. Other groups remain compact but visibly identifiable as groups.
• Enforce one bounded guide hierarchy in projection validation: guide root → direct section-or-page → optional leaf page. Reject any document whose parent relationship would create a fourth level beneath a guide root; the rail must never silently truncate deeper source content.

Docs-home information order

• Move the data-derived Community and activities chapter to the first content position on /docs/, before Course guides, sectioned support guides and Course platform and FAQ.
• Preserve the current docs_hub.community entries, their source order, descriptions, page counts and destinations. This is a presentation-order change, not a hardcoded replacement list.
• The first chapter actually rendered receives the existing first-chapter seam treatment. If community data is absent, the next available chapter becomes first without leaving a phantom gap/rule.
• Search-results mode is unchanged.

Unified-site root CTA cleanup

• Remove the exact source-owned Visit DataTalks.Club button from the upstream docs root index.md and ingest that source revision so /docs no longer renders the redundant body CTA.
• This is the user-requested exception to body-content preservation. Remove it at source; do not hide it in the website template/CSS or add a title/link special case.
• Preserve the root heading, description, all other body content, global site navigation and normal routes back to the site home.

Canonical docs URLs and guide order

• Change the canonical documentation family to slashless paths:
  • hub: /docs;
  • nested pages: /docs/general/brand-assets, /docs/general/slack, and the same slashless form for every other published docs document.
• Every formerly canonical trailing-slash docs document/hub URL returns a one-hop permanent 301 to its exact slashless canonical while preserving the raw query string byte-for-byte. Do not build redirect chains through a parent/hub or Django APPEND_SLASH behavior.
• Emit slashless docs document URLs everywhere this application owns: canonical and Open Graph metadata, breadcrumbs, guide rail, docs-home groups, search results, page TOCs where a link is document-qualified, sibling/previous/next pagers, internal rendered docs links, sitemap/public route inventories and compatibility artifacts.
• Keep documentation asset paths under /docs/assets/... exactly as they are. They are files, not document aliases, and must neither lose extensions nor redirect through the document route.
• Unknown, malformed, wrong-case or near-match docs paths remain 404; do not guess a canonical from arbitrary input. The only new aliases are exact known canonical documents with one trailing slash.
• Update the authoritative URL compatibility spec to replace “Docs retain pretty trailing-slash paths” with this slashless document/one-hop alias contract.
• In the source-owned General guide order, place Brand Assets before the Jobs group/pages. Previous/Next, rail order and hub order all consume this one order so Suspicious Job Postings cannot lead next to Brand Assets.
• Keep order content-owned: update the reviewed docs navigation record/source through the approved ingest/Studio path rather than adding a title/path special-case sorter in runtime code.

Brand-assets presentation

• Add a page-scoped presentation for /docs/general/brand-assets/ that turns the existing source-authored label + preview + PNG/SVG link groups into a responsive, scannable asset catalogue.
• Keep wordmarks at a restrained preview width and icons/avatar at a smaller intrinsic-looking size; preserve aspect ratio and never upscale a bitmap merely to fill the reading column.
• Give each asset a clear visible label and working links to the original published PNG/SVG files. Labels, preview sources and download destinations remain derived from the ingested document markup/data.
• Use suitable preview surfaces so black/dark and white assets remain visible in both site themes. Preview surface, border and label/link contrast must not alter the asset pixels themselves.
• Scope selectors/transformation to the brand-assets page. The default .docs-body img contract and every unrelated documentation image retain their current behavior.

Non-goals

• No edit to documentation body Markdown, headings, descriptions, asset bytes or asset URLs except deletion of the exact redundant root Visit DataTalks.Club CTA. The other authorized source edit is the reviewed navigation position needed to put Brand Assets before Jobs.
• No global redesign of docs detail pages, guide rail, breadcrumbs, header/search, prose, pager or edit link.
• No redesign of the rail's overall desktop-sticky/mobile-stacked placement; this issue changes hierarchy cues and bounded nesting inside it.
• No reordering within Community and activities, course-family cards, support guides or search results.
• No sticky floating sidebar, scroll-jacking, smooth-scroll requirement or new client-side framework.
• No global thumbnail rule for prose images and no compression/re-encoding of brand assets.

Dependencies

• No blocking issue, schema change or new package is required.
• Presentation must operate against the existing database-derived heading list, docs hierarchy and managed asset routes.
• The Brand Assets/Jobs sequence and root CTA deletion must be changed in the reviewed upstream docs source and ingested in deployed environments; tests use synthetic source-shaped records. Neither may become a runtime hardcoded exception.

Acceptance criteria

Table of contents

• A docs detail page with at least three source headings renders one labelled semantic TOC navigation, not the current permanently open wide <details> treatment.
• /docs/courses/ai-dev-tools-zoomcamp/prerequisites shows Required skills, You do not need, and Intended audience as a compact ordered reading aid within the prose measure. It does not spread three links across a large two-column blank strip.
• TOC entries come from source-rendered H2–H4 headings in document order. Nested source headings render in matching nested hierarchy/indentation; no label or fragment is hand-authored for this route.
• Every TOC href resolves to exactly one heading ID in the rendered article. Direct loads of each fragment and keyboard activation land with the complete target heading visible below the shell via an appropriate scroll-margin-top.
• A valid initial fragment, TOC activation and scroll position produce one accurate aria-current="location" state. The active treatment includes shape/weight/marker in addition to color and never leaves multiple current links.
• With JavaScript disabled, all TOC links still navigate to their source anchors and the content remains readable. Enhancement never traps focus, steals ordinary reading scroll or rewrites browser history incorrectly.
• TOC links have a visible shared 3px focus treatment and at least 44px block-size targets. Long headings wrap without collision or horizontal overflow.
• Pages with fewer than three section headings keep the existing no-TOC behavior. Pages with many/mixed-level headings remain compact and usable rather than being truncated or flattened.
• The content contract accepts H1 + H2→H3→H4 without skipped downward levels. H5/H6 or a skipped level fails validation before publication with a bounded source diagnostic; no invalid heading is silently flattened, relabelled or omitted from the outline.

Guide rail

• A direct page row and a group row have observably different anatomy. Every group exposes its nestedness while collapsed through a visible child-count/chevron cue and an accessible name that says it contains pages; leaves do not advertise children.
• On a descendant route, exactly the active ancestor group expands and its children render in a nested <ol> with clear indentation/connector. Exactly one current page carries aria-current="page"; the parent remains visibly the active branch without falsely being the current page.
• Rail markup preserves ordered-list semantics at both levels and one focusable link per destination. Group cues are not extra misleading focus stops; every link keeps visible focus and the minimum target size.
• Projection validation permits at most guide root → direct section/page → optional leaf. A deeper parent chain fails closed with a bounded source-path diagnostic before a partial rail/tree is published.
• At desktop and mobile widths, long group/leaf titles, child counts and indentation wrap without overlap or horizontal overflow. The rail keeps its existing sticky desktop and in-flow mobile placement.

Docs home

• In the no-query /docs/ DOM and visual order, Community and activities is the first content chapter, before Course guides, every sectioned support guide, and Course platform and FAQ.
• Community rows, nested page links, counts and destinations are unchanged and remain derived from docs_hub.community/the source tree.
• Exactly one rendered chapter receives the first-chapter seam treatment. If docs_hub.community is empty, the first available remaining chapter moves up cleanly; the all-empty state remains intact.
• /docs/?q=… search mode keeps its existing result ranking, markup, clear-search action and empty state.
• The upstream root index.md no longer contains the exact Visit DataTalks.Club button, and the ingested /docs body renders no redundant CTA or empty wrapper in its place. The root heading, description, other source body content and global navigation remain unchanged.

Canonical paths and guide sequence

• /docs is the terminal 200 hub and self-canonical. /docs/ returns one 301 directly to /docs; query-bearing aliases preserve the raw query exactly.
• Every known nested documentation document is terminal 200 at its slashless path and self-canonical. Its exact trailing-slash alias returns one 301 directly to that slashless path, preserving raw query bytes.
• Canonical and Open Graph URLs, docs-home links, rendered source-internal docs links, breadcrumbs, guide rails, search results, TOCs, sibling links, Previous/Next pagers, sitemap and public-route inventories emit only slashless document paths.
• /docs/assets/... URLs, response bytes, cache behavior and compatibility paths are unchanged and are never handled as document redirects.
• Unknown/malformed/wrong-case/extra-segment docs paths return 404 without redirecting to a guessed page or the docs hub.
• The URL compatibility spec states the slashless canonical/one-hop trailing-slash alias contract and no longer claims docs canonicals retain trailing slashes.
• Within the source-derived General guide sequence, Brand Assets appears before Jobs and its descendants. Rail, hub and previous/next use that same order; Suspicious Job Postings does not offer Brand Assets as its next page.
• No runtime title/path special case imposes the Brand/Jobs order; changing the reviewed source navigation order and re-ingesting it is sufficient.

Brand assets

• /docs/general/brand-assets presents each source-authored main/black/white wordmark and icon, plus the avatar where supplied, in a clearly labelled preview group with its original available PNG/SVG link(s).
• Wordmark previews are visually restrained and icons/avatar do not render as reading-column-width 1024px images. All preserve intrinsic aspect ratio, avoid bitmap upscaling and remain recognizable.
• White assets have an appropriate dark preview ground; black/dark assets have an appropriate light preview ground; the main variants remain legible. This holds in both light and dark site themes without changing image bytes.
• Published asset endpoints, response bytes/checksums and source-derived alt text remain unchanged. Preview and download links return the intended original files.
• Brand-specific layout/styling is page-scoped. Representative unrelated docs pages with ordinary prose images render at their previous size/flow.
• The asset catalogue reflows cleanly at 1440px, 768px, 390px and 320px: labels/actions remain associated with the right preview, links meet the 44px target floor, and no preview or row creates document-level horizontal overflow.

Verification

• The engineer freezes an issue-isolated #420 candidate and generates the versioned selective-CI plan/report from that exact base/head/worktree. The tester independently recomputes it; unexplained source/render drift or shared unrelated paths invalidate the handoff.
• Because this change touches templates/browser behavior, the plan-required full Playwright component has either a fresh complete success for the frozen candidate or one exact, validated whole-component prior-success envelope that the current plan itself marks reused. Individual passing scenarios cannot be combined with a failing full run.
• Historical or unrelated registration-preview 404 and author-image 502 failures are attribution evidence, not a waiver. If they still reproduce and no valid reuse envelope exists, they remain release blockers and must be repaired through separately tracked work; #420 is then rebased/frozen and its plan rerun. No ad-hoc skip, xfail, quarantine or reduced browser tier is added under this issue.
• Light and dark screenshots are captured and inspected for /docs/, the AI Dev Tools prerequisites fragment, a mixed H2/H3 detail fixture, /docs/general/brand-assets/, and an unrelated image-bearing docs page at desktop and mobile widths under .tmp/screenshots/issue-420/.
• Focused tests cover TOC threshold/hierarchy/fragment validity/current state and invalid outline rejection; rail group/leaf anatomy, active expansion and maximum depth; docs-home ordering with/without community data; the full slashless canonical/alias/query/internal-link contract; Brand-before-Jobs sequence; search-mode regression; brand-page scoping, original asset URLs and unrelated-image regression.
• Focused Django checks and the applicable full Playwright tier for template/browser behavior pass with scrollWidth <= clientWidth at 1440px, 768px, 390px and 320px.

Browser scenarios

Prerequisites anchors

1. Open /docs/courses/ai-dev-tools-zoomcamp/prerequisites#required-skills on desktop and mobile.
2. Verify a compact TOC, one current marker and an unobscured Required skills heading.
3. Use keyboard only to activate the other two entries; verify focus, URL fragment, current marker and visible target heading.
4. Disable JavaScript and repeat fragment activation; navigation must still work.

Heading hierarchy and long content

1. Open a docs page/fixture with mixed H2/H3/H4 headings and long titles.
2. Verify nested hierarchy, source order, wrapping, single-current state while scrolling and no overflow.
3. Open pages with two headings and with no headings; verify no empty TOC is rendered.
4. Attempt to ingest/build a document with H2→H4 and another with H5; verify both are rejected with bounded diagnostics rather than flattened.

Rail hierarchy

1. Open /docs/general/slack and verify Community Guidelines is visibly a group, is the active branch, and expands a nested ordered list with Slack marked current.
2. Verify Jobs still advertises its child count/chevron while compact and that direct Brand Assets reads as a leaf.
3. Repeat on mobile with long synthetic group/leaf names and keyboard navigation; verify ordered semantics, one focus stop per link and no overflow.
4. Build a synthetic guide with one level deeper than guide root → section/page → leaf; verify projection validation fails closed.

Docs home states

1. Open /docs/ without a query and verify Community and activities is the first chapter, keeps all source-derived links, and no longer shows the redundant body Visit DataTalks.Club CTA.
2. Verify the upstream index.md deletion was ingested and that the global site navigation still provides the ordinary site-home route.
3. Render without community rows and verify the next chapter owns the opening seam with no gap.
4. Open a populated and empty search query; verify search mode is unchanged.

Canonical and alias routing

1. Open /docs, /docs/general/brand-assets and /docs/general/slack; verify terminal 200, slashless self-canonical/OG URLs and slashless internal navigation.
2. Open each exact trailing-slash form with repeated keys, blank values and percent-encoded query bytes; verify one 301 to the matching slashless path with the raw query preserved.
3. Verify representative unknown, wrong-case and extra-segment paths return 404 without a redirect.
4. Fetch representative /docs/assets/...png and .svg routes and verify no redirect and unchanged bytes.
5. Traverse General using the rail and Previous/Next; verify Brand Assets precedes Jobs and Suspicious Job Postings never crosses into Brand Assets.

Brand catalogue

1. Open /docs/general/brand-assets at 1440px, 768px, 390px and 320px in light mode and representative desktop/mobile dark mode.
2. Verify preview scale, label/action association, white/black asset legibility, keyboard focus and no overflow.
3. Follow every PNG/SVG action and compare the response checksum with the pre-change asset.
4. Open an unrelated docs page with a prose image and verify its presentation did not inherit the brand catalogue rules.

Start with templates/review/docs_home.html, templates/review/docs_detail.html, templates/review/_docs_styles.html, content/docs_presentation.py, and content/review_views.py; read the listed design and URL specs first. Run content/tests/test_docs_pages.py and inspect its synthetic source-shaped records, along with the upstream index.md and reviewed navigation source. Done means the acceptance criteria pass without runtime special cases, source-derived content remains intact, and slashless routes, hierarchy, TOC behavior, ordering, and asset previews are covered.