Skip to content

Consolidate docs code blocks into a shared Astro <CodeBlock> component #850

Description

@zachdunn

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:

  • 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:
    1. 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).
    2. 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).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions