fix: broken links, docs sidebar inconsistency, nav light-mode contrast#18
Merged
Merged
Conversation
…mode
Fixes two confirmed bugs from a manual site audit:
1. 12 broken links (404s), traced to two root causes:
- 7 nav/footer links pointed to trailing-slash directory URLs
(/blog/, /solutions/, /docs/, /questions/, /compare/, /examples/,
/use-cases/) but the site's build.format:'file' + trailingSlash:
'never' config emits flat *.html files, not dir/index.html. Every
such link across the whole site (crumbs, sidebar, cards) has been
corrected to the *.html form the build actually produces, and new
landing pages were added for each of these sections (blog, compare,
docs, questions, solutions, docs/guides) built from the real
existing content in each folder, not fabricated pages.
- 2 dead links to /docs/guides/capability-authoring.html and
/docs/guides/workflow-authoring.html, referenced from the docs
sidebar and several content pages, pointing to guides that were
never built. Redirected to real existing content that already
covers the same material (quickstart.html, concepts.html#workflows)
rather than inventing new guide pages.
- /examples/ and /use-cases/ had no page at all. Built both from
content that already exists elsewhere on the site (the capability
contract example used on the homepage/docs, and the use-case
descriptions already on solutions pages) rather than fabricating
new claims.
2. The docs sidebar was hardcoded HTML duplicated across all 5 docs
pages, and had drifted into three different structures (quickstart
and concepts each had a unique variant; architecture, cli-reference,
and troubleshooting shared a third, the one with the dead guide
links). Extracted to a single DocsSidebar.astro component with an
`active` prop, used consistently by all 5 pages plus the two new
docs index pages.
3. Nav contrast bug in light mode: the homepage hero has a hardcoded-
dark background regardless of theme (brand art), but the nav's
transparent (unscrolled) state used theme-aware --fg/--fg-muted,
which flips to near-black in light mode — rendering the wordmark,
nav links, and GitHub button nearly invisible against the dark hero.
Scoped a fix to body.home only (verified no other page has a
hardcoded-dark hero) forcing light nav text while transparent,
falling back to normal theme-aware color once scrolled/solid.
Verified: 0 broken internal links across all 88 built pages (up from
80 — 8 new landing/index pages), 0 canonical URLs with a trailing
slash, docs sidebar renders identically (same links, correct active
state) across all 5 docs pages plus computed styles confirming legible
nav text in light mode on the homepage.
Co-Authored-By: Claude Sonnet 5 <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.
Summary
Manual site audit found real, confirmed bugs — verified with a link-checker script and computed styles, not eyeballing.
12 broken links → 0. Two root causes:
/blog/,/solutions/, etc.) but the build (build.format:'file'+trailingSlash:'never') emits flat*.htmlfiles, notdir/index.html. Fixed every reference site-wide and added real landing pages for blog, compare, docs, questions, solutions, docs/guides, examples, and use-cases — built from content that already exists elsewhere on the site, not fabricated.capability-authoring.html,workflow-authoring.html), referenced from the docs sidebar and 4 other pages. Redirected to real existing content covering the same material instead of inventing new guides.Docs sidebar consistency. Found 3 different hardcoded sidebar structures across 5 docs pages (quickstart, concepts, and architecture/cli-reference/troubleshooting each had their own variant). Extracted to
DocsSidebar.astrowith anactiveprop, used identically everywhere.Nav invisible in light mode. The homepage hero is hardcoded-dark (brand art, no theme override), but the transparent nav used theme-aware colors that flip to near-black in light mode — making the wordmark, nav links, and GitHub button nearly invisible. Scoped fix to the homepage only (confirmed no other page has this issue) forcing light nav text while transparent.
Test plan
🤖 Generated with Claude Code