fix: 25 bugs found while dogfooding the docs site (crashes, .md export, search, config)#43
Merged
Merged
Conversation
… explicit empty nav
Found while dogfooding the docs site. Five Configuration bugs:
- code_theme_class/code_theme_dark_class const_get raised NameError on a
typo'd/unloaded Rouge theme, crashing every page with a code block; now
degrades to the default theme (base) / nil (dark).
- version_badge_text dropped a plain String value (respond_to?(:call) guard);
now coerces a non-callable to its string form so c.version_badge = "v1.2" works.
- nav_groups used @nav.equal?(DEFAULT_NAV) object identity, so any assigned
lambda — even -> { {} } — skipped registry derivation; now tracks explicit
assignment via a flag so an explicit empty nav wins and an untouched nav
still derives from nav_registries.
- Comments referenced a nonexistent Docs:: namespace; corrected to DocsUI::.
TDD: RED specs added for each (theme degrade, String badge, explicit empty nav).
Refs #8
Claude-Session: https://claude.ai/code/session_01FPQb6z3YwcKRMbvoJhdxnX
…s site
A capability+render audit of the dogfood docs site surfaced 25 confirmed bugs
(5 config ones fixed in the previous commit). This commit fixes the remaining
20, each with a RED-first spec:
Broken features
- api_templates: RequestExample no longer aborts with JSON::ParserError on a
non-JSON String body (compact_json only compacts valid JSON, else verbatim).
- registry: Registry#nav_items now guards view_class + honors
group_by_attribute, so a hash-entries registry no longer NoMethodErrors.
- install_generator: the stimulus-registration fallback no longer writes an
eager line when the site lazy-loads (double-registration).
Wrong output
- section: page-scoped anchor-id de-dup (shared Phlex render context) so two
same-slug sections no longer emit duplicate ids that break the TOC/scroll-spy.
- request_example: drop a colon-less auth header instead of emitting `-H "X: "`.
- markdown_export/{blocks,inline,table}: correct callout title export, fence
backtick-containing inline code, and size GFM tables to the widest row.
- code: stamp the filename title bar with the md-skip marker so it no longer
leaks above the fence in the .md twin.
- error_table: treat a blank :param string as absent (no empty <code>, no
spurious Param column).
- search_index: fence-aware section split — a `## ` inside a code fence is no
longer indexed as a phantom heading.
- shortcut: de-dup a chord that sets both :mod and :ctrl ("Ctrl Ctrl" → "Ctrl").
Papercuts / cosmetics
- sidebar: brand link honors config.brand_href (matched Shell#topbar).
- table: malformed typed cells raise instead of leaking the literal array.
- field_table: a field with no :description degrades to the em-dash placeholder.
- prop_table: a malformed empty row no longer emits an empty <code>.
- page: on_page defaults to DocsKit.configuration.on_page_default (matches doc).
- code: comment separates code_lexer_aliases (highlighting) from
code_language_labels (Example tab labels).
- page_generator: no redundant slug:/view: keywords when they match the derived
defaults.
- example_spec: comment corrected — :curl resolves to Rouge's console lexer.
538 examples, 0 failures; rubocop clean.
Refs #8
Claude-Session: https://claude.ai/code/session_01FPQb6z3YwcKRMbvoJhdxnX
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 & why
While dogfooding docs-kit's own docs site, I ran a capability + render audit of the whole gem and it surfaced 25 confirmed bugs — each reproduced end-to-end before fixing. This PR lands all 25 fixes (TDD, RED-first spec per bug). The docs rewrite that motivated the audit follows in a separate PR.
Refs #8.
The bugs, by impact
Broken features (crash / abort)
c.code_theme = "…Doesnotexist") raisedNameErroron every page with a code blockcode_theme_class/code_theme_dark_classdegrade to the default theme / nilDocsUI::RequestExampleaborted withJSON::ParserErroron a non-JSON String bodycompact_jsononly compacts valid JSON, else passes the body verbatimRegistry#nav_itemscouldNoMethodErroron a hash-entriesregistryview_class+ honorsgroup_by_attribute(mirrors#grouped)Wrong output
DocsUI::Sectionemitted duplicate DOM ids for same-slug titles → broke in-page anchors, the auto-TOC, and scroll-spy. Now page-scoped id de-dup via Phlex's shared render context..mdtwin export: mis-exported callout titles, corrupted inline code containing a backtick, and produced ragged GFM tables; afilename:leaked as a stray paragraph above the fence. All fixed inmarkdown_export/{blocks,inline,table}+code.##line inside a code fence as a real heading → phantom search entries. Now fence-aware.RequestExampleemitted a malformed-H "Token: "when the auth header had no colon;ErrorTableshowed an empty<code>/spurious Param column for a blank param;ShortcutrenderedCtrl Ctrlfor amod+ctrlchord.c.version_badge = "v1.2"(a String) silently rendered nothing;c.nav = -> { {} }(an explicit empty nav) was ignored because of anequal?(DEFAULT_NAV)object-identity check.Papercuts / cosmetics
config.brand_href(matchedShell#topbar).:descriptiondegrades to the em-dash placeholder; a malformed empty PropTable row no longer emits an empty<code>.DocsUI::Page#on_pagenow returnsconfiguration.on_page_default(matches its doc); config comments fixed (Docs::→DocsUI::);DocsUI::Code's comment separates thecode_lexer_aliases(highlighting) vscode_language_labels(tab labels) knobs; the page generator no longer emits redundantslug:/view:keywords; anexample_speccomment corrected.How it was found
A multi-agent audit mapped all 12 capability areas from source, rendered every page + the
.mdtwin +/llms.txt+ search end-to-end, flagged suspected bugs, and verified each by reproduction (39 agents, 0 errors). The 25 that reproduced are here; the fixes were applied one-file-per-agent (disjoint), each with its own spec.Verification
bundle exec rspec— 538 examples, 0 failures (was 505; ~33 new regression examples).bundle exec rubocop— clean (105 files)..mdtwin, and search render 200 after the fixes.https://claude.ai/code/session_01FPQb6z3YwcKRMbvoJhdxnX