feat: compact category index list + plain-text SEO descriptions#35
Open
Zodiarche wants to merge 2 commits into
Open
feat: compact category index list + plain-text SEO descriptions#35Zodiarche wants to merge 2 commits into
Zodiarche wants to merge 2 commits into
Conversation
Swizzle the theme-safe DocCardList to replace the boxed 2-column card grid on generated-index pages with a single scannable list. The grid did not scale for sections with many guides (Ruby, battle engine) and broke the reading order of the numbered Ruby course. Use only the public plugin-content-docs/client API to stay upgrade-tolerant, and drop the now-unused global card CSS.
The description frontmatter feeds the meta description tag and the new category cards, both rendered as raw text, so Markdown markers leaked into search snippets. Strip bold/code markers from the Ruby chapter descriptions in both locales; the body intro paragraphs keep their emphasis. Update CONTRIBUTING to require plain-text descriptions.
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
Two related changes to the category index (
generated-index) pages.1. Compact list rendering
The stock 2-column grid of boxed, truncated cards did not scale. Sections with many guides (Ruby: 16 chapters, battle engine: 16 guides) became a long wall of cards, and a grid breaks the reading order of the numbered Ruby course. The pages now render a single scannable list — one row per entry (title + description + chevron).
Implemented by swizzling
DocCardList, the only card component the theme marks assafeto eject, using only the public@docusaurus/plugin-content-docs/clientAPI (notheme-common/internalimports), so it stays upgrade-tolerant. The previous global card CSS incustom.cssis removed.2. Plain-text frontmatter descriptions (SEO)
The
descriptionfrontmatter feeds the<meta name="description">tag and the cards, both rendered as raw text. Several Ruby chapters had Markdown in their descriptions, leaking**bold**/`code`into search snippets. The markers are stripped from every affected description in both locales (26 files, one line each); the body intro paragraphs keep their emphasis.CONTRIBUTING.mdnow requires plain-text descriptions to prevent regressions.Test plan
bun run typecheck✅bun run build(both locales,onBrokenLinks: throw) ✅<meta name="description">contains Markdown across the site; cards render descriptions as plain text.bun startandbun run start:fr→/ruby,/psdk/battle-engine.Notes