You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Docs pages hand-roll their code blocks with a small zoo of patterns, and syntax-highlighted blocks now carry a per-page CSS workaround that's easy to get wrong:
Copy boxes use <div class="cmd"> + a data-copy button, repeated inline everywhere (14 in attach-pull-request-images.astro, 6 in agents.astro, etc.).
Read-only / output blocks use <div class="block"><pre>…</pre></div>.
Syntax-highlighted blocks use Astro's <Code lang=… theme="vitesse-dark" class="…-example" /> plus a page-local <style> block. That style is duplicated in every page that wants highlighting (comment-config.astro.yaml-example, github-screenshots.astro.bash-example) and must re-apply two non-obvious fixes each time:
Reset Shiki's inner <code> so it doesn't inherit .doc code's inline border/background (an inline box across many lines paints a border fragment on every line — the "per-line border" bug fixed in docs: tighten the github-screenshots page flow #849).
white-space: pre-wrap; overflow-wrap: anywhere for bash so long commands wrap — but not for yaml, where indentation matters.
Every new highlighted block re-derives all of this, which is how the per-line border shipped in the first place.
Proposal
A single shared Astro component (e.g. apps/web/src/components/CodeBlock.astro) that owns the whole surface:
props for code, lang, and a copy boolean (copyable command vs read-only) — folding today's .cmd, .block, and .*-example into one component
Shiki highlighting with the inner-<code> reset applied once, centrally
per-lang wrap behavior baked in (wrap bash/shell, scroll yaml)
the copy-button markup + bootDocsChrome wiring in one place
Not shadcn / not React. Public docs pages deliberately ship no framework JS (React is signed-in-only; see DocsLayout + the homepage//f/ web-component convention), so this should be a plain Astro component with the existing vanilla copy-button JS — a shadcn component would pull React onto public pages.
Scope / payoff
De-duplicates the .*-example CSS (currently in 2 pages, growing) and the copy-box boilerplate (~30+ hand-written blocks across docs).
Makes the highlighting gotchas un-repeatable — you can't forget the border reset if the component does it.
Should be reflected in the skills/docs-page-style skill's component vocabulary once it lands.
Follow-up to #847 (docs restructure + house skill) and #849 (which introduced the highlighted blocks and both CSS workarounds).
Problem
Docs pages hand-roll their code blocks with a small zoo of patterns, and syntax-highlighted blocks now carry a per-page CSS workaround that's easy to get wrong:
<div class="cmd">+ adata-copybutton, repeated inline everywhere (14 inattach-pull-request-images.astro, 6 inagents.astro, etc.).<div class="block"><pre>…</pre></div>.<Code lang=… theme="vitesse-dark" class="…-example" />plus a page-local<style>block. That style is duplicated in every page that wants highlighting (comment-config.astro.yaml-example,github-screenshots.astro.bash-example) and must re-apply two non-obvious fixes each time:<code>so it doesn't inherit.doc code's inline border/background (an inline box across many lines paints a border fragment on every line — the "per-line border" bug fixed in docs: tighten the github-screenshots page flow #849).white-space: pre-wrap; overflow-wrap: anywhereforbashso long commands wrap — but not foryaml, where indentation matters.Every new highlighted block re-derives all of this, which is how the per-line border shipped in the first place.
Proposal
A single shared Astro component (e.g.
apps/web/src/components/CodeBlock.astro) that owns the whole surface:code,lang, and acopyboolean (copyable command vs read-only) — folding today's.cmd,.block, and.*-exampleinto one component<code>reset applied once, centrallybash/shell, scrollyaml)bootDocsChromewiring in one placeNot shadcn / not React. Public docs pages deliberately ship no framework JS (React is signed-in-only; see DocsLayout + the homepage/
/f/web-component convention), so this should be a plain Astro component with the existing vanilla copy-button JS — a shadcn component would pull React onto public pages.Scope / payoff
.*-exampleCSS (currently in 2 pages, growing) and the copy-box boilerplate (~30+ hand-written blocks across docs).skills/docs-page-styleskill's component vocabulary once it lands.Follow-up to #847 (docs restructure + house skill) and #849 (which introduced the highlighted blocks and both CSS workarounds).