docs: restructure docs pages for scannability + house docs-style skill - #847
Conversation
…kill Rework the /docs hub and its eight subject pages to lead with one golden-path command, reserve copy boxes for commands pasted verbatim, keep full multi-argument commands out of inline text, drop fabricated terminal output, and cut prose. In DocsLayout, move the section-link anchor to a hover-only left gutter, make the whole heading click-to-anchor, and add a .pointer style so demoted secondary commands read as secondary. Codify the conventions as skills/docs-page-style so future docs pages get the same treatment.
|
|
Important Review skippedAuto reviews are limited based on label configuration. 🏷️ Required labels (at least one) (2)
🚫 Excluded labels (none allowed) (1)
Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
…block Rewrite the /docs intro to lead with the concrete why (GitHub has no upload API) before the capability list. On the reference page, replace five stacked copy rows with a single aligned command block. Fold both refinements back into skills/docs-page-style (reference-list-as-block; concrete-why earns its sentences).
On the attach page's staging section, drop the redundant 'uploads staged' copy box (the command is already named inline) so the example output block no longer sits under a look-alike command box. On comment-config, render the .uploads.yml example with Shiki (astro:components Code, vitesse-dark) so keys and values read apart from the explanatory comments. Document both in skills/docs-page-style.
Apply the docs restructure (#847) scannability treatment to the github-screenshots SKILL.md: split the bold-lead walls in Step 2 and the dev-server flags paragraph in Step 1 into short sentences and bulleted lists. Formatting only — every command, flag, and caveat is preserved.
1 participant
What
Rework the
/docshub and its eight subject pages to read like reputabledev-tool docs (Stripe, Vercel, Wrangler) instead of prose-heavy pages, and
codify the conventions as a reusable house skill so future docs pages get the
same treatment.
Why
The docs pages leaned on heavy paragraphs, examples for every variation, a copy
button on nearly every line, fabricated terminal output, and setup buried below
usage. Individually the sentences were fine; the structure made the reader
work. Benchmarking against reputable CLI docs surfaced the patterns we were
missing — one-sentence intros, a single golden path (never two competing
commands up top), install-first ordering, and copy affordances reserved for
commands you actually paste.
Changes
Page rework (hub + 8 subject pages)
data-copyvalues on the galleries page fixed (they pasted invalid commands)DocsLayout (site-wide)
#anchors moved to a hover-only left gutter (OpenRouter pattern)#glyph.pointerstyle so demoted secondary commands read as secondaryNew skill:
skills/docs-page-stylefull DocsLayout component vocabulary. The 8 subject-page rewrites in this PR
were produced by agents following it — the test run also caught the real bugs
and rule violations noted above.
Verify
astro checkclean; anchor ids other pages link to(
#staging,#before-after,#attach,#annotate,#put) preserved.source and sibling pages.
Screenshots to follow.