Files
basecoat/rsd-astro-docs-handoff.md
T

5.2 KiB

RSD Astro Docs Authoring Handoff

Purpose

Capture the current thinking for showing rendered Basecoat examples plus source code when ReallySimpleDocs is used as an Astro integration.

The next session should decide whether Basecoat keeps its current Nunjucks-generated RSD docs flow, or whether RSD should grow an Astro-native optional examples API for richer docs pages.

Current state

  • ReallySimpleDocs now ships as an Astro integration package.
  • RSD content is currently plain Markdown rendered through marked.
  • RSD docs pages are generated by:
    • /Users/hunvreus/Workspace/reallysimpledocs/src/runtime/pages/doc.astro
    • /Users/hunvreus/Workspace/reallysimpledocs/src/runtime/components/DocsLayout.astro
    • /Users/hunvreus/Workspace/reallysimpledocs/src/runtime/lib/docs.js
  • RSD does not currently support MDX, Astro components inside docs Markdown, or React islands inside docs content.
  • RSD does load Basecoat CSS/JS for generated docs pages, so raw Basecoat HTML works.
  • Basecoat already has a richer docs source flow:
    • source docs under /Users/hunvreus/Workspace/basecoat/docs/src
    • Nunjucks macros under /Users/hunvreus/Workspace/basecoat/docs/src/_includes/macros
    • generated RSD-compatible docs under /Users/hunvreus/Workspace/basecoat/docs/generated
    • generator: /Users/hunvreus/Workspace/basecoat/scripts/generate-rsd-docs.js

Existing Basecoat pattern

Basecoat currently authors examples with Nunjucks and renders them to portable Markdown/HTML before RSD sees them.

Example source:

{% set code_html %}
{{ tabs(
  id="demo-tabs-with-panels",
  tabsets=tabsets_demo,
  main_attrs={ "class": "w-full" }
) }}
{% endset %}

{{ code_preview("tabs", code_html | prettyHtml, "max-w-[400px] w-full") }}

Relevant macro:

  • /Users/hunvreus/Workspace/basecoat/docs/src/_includes/macros/code_preview.njk

That macro renders:

  • a Basecoat tabs component
  • a Preview tab containing rendered HTML
  • a Code tab containing escaped source
  • no React, no MDX, no client hydration beyond Basecoat JS

This is good for Basecoat because Basecoat is framework-agnostic and already ships Nunjucks/Jinja macros.

Decision so far

Nunjucks is not Astro-native.

For a generic Astro site using RSD, the Astro-native options are:

  • .astro components
  • MDX for components inside docs
  • optional framework islands only when needed

For RSD itself, do not make React the default path. It would pull RSD away from the current lightweight, portable Markdown model.

Likely best direction

Keep RSD core simple:

  • Markdown pages
  • generated HTML
  • Basecoat JS
  • search, Markdown exports, llms.txt, and llms-full.txt

Then add richer authoring as an optional layer.

Two viable layers:

  1. Basecoat-specific generated docs flow

    • Keep using Nunjucks macros and scripts/generate-rsd-docs.js.
    • Improve macros as needed.
    • Output remains plain Markdown/HTML consumed by RSD.
    • Best for Basecoat itself.
  2. Astro-native optional RSD examples API

    • Add optional MDX support later.
    • Provide components such as Preview.astro, CodeBlock.astro, Callout.astro, maybe Tabs.astro.
    • Prefer file-based examples so source and rendered output stay in sync.

Preferred Astro-native example shape:

import Preview from "reallysimpledocs/components/Preview.astro";
import ButtonDemo from "../examples/ButtonDemo.astro";
import buttonSource from "../examples/ButtonDemo.astro?raw";

<Preview code={buttonSource}>
  <ButtonDemo />
</Preview>

This is more Astro-native than Nunjucks, but it requires RSD to support MDX or an Astro content path. It also makes docs less portable than plain Markdown.

Avoid for now

  • Do not add React just for examples.

  • Do not make MDX the default content model.

  • Do not invent directive syntax such as:

    ::preview{class="max-w-sm"}
    ...
    ::
    

    RSD uses marked today, so directive syntax would require another parser or custom extension. It is not currently supported.

Open questions

  • Should Basecoat keep source docs in Nunjucks permanently, or move docs authoring to Astro/MDX once RSD is Astro-first?
  • Should RSD expose Preview.astro and related components as public package API?
  • If RSD supports MDX later, should that be:
    • an opt-in mode,
    • a separate integration option,
    • or a separate package?
  • How should source-code extraction work?
    • explicit code prop,
    • file import with ?raw,
    • or a build-time plugin that captures source from children?

Suggested next steps

  1. Keep Basecoat's existing Nunjucks generator working for the current RSD beta.
  2. Improve code_preview.njk only if the rendered RSD output needs better Basecoat markup or accessibility.
  3. In RSD, do not add React or MDX until there is a concrete consumer need.
  4. If richer Astro-native examples become necessary, prototype a small Preview.astro with file-based ?raw source imports.
  5. Validate any prototype against:
    • RSD static build
    • search index output
    • Markdown exports
    • llms.txt / llms-full.txt
    • Basecoat JS behavior

Validation commands

For Basecoat generated docs:

cd /Users/hunvreus/Workspace/basecoat
npm run build
npm run docs:build

For RSD package behavior:

cd /Users/hunvreus/Workspace/reallysimpledocs
npm run check