Skip to content

Add Seed Bible extension API reference documentation - #148

Open
KallynGowdy wants to merge 9 commits into
mainfrom
claude/awesome-hypatia-ud5cza
Open

KallynGowdy wants to merge 9 commits into
mainfrom
claude/awesome-hypatia-ud5cza

Conversation

@KallynGowdy

Copy link
Copy Markdown
Collaborator

Summary

This PR adds comprehensive API reference documentation for the Seed Bible extension development platform. The reference is automatically generated from the seed-bible npm package's type declarations, ensuring it always matches what developers install.

Key Changes

  • New generator script (.vuepress/seed-bible/generate-reference.mjs): Uses TypeDoc and typedoc-plugin-markdown to generate markdown documentation from the seed-bible package's type declarations. The script:

    • Processes three entry points: seed-bible/extensions, seed-bible/extensions/testing, and seed-bible/components
    • Generates organized reference pages with a sidebar structure
    • Handles unexported types used by exports but not directly importable
    • Outputs a sidebar.json file for VuePress integration
  • Documentation landing page (docs/seed-bible/README.md): Introduces the Seed Bible extension platform with:

    • Quick start instructions
    • Links to external developer guides
    • Overview of the three main packages developers import from
    • Guide to reading the API reference
  • VuePress configuration updates (docs/.vuepress/config.ts):

    • Added Seed Bible navbar link (English-only, consistent across all languages)
    • Integrated generated sidebar into the site structure
    • Added seedBibleReferenceSidebar() function to load the generated sidebar.json
    • Added tsx to Shiki syntax highlighting languages
  • Build process integration (docs/package.json):

    • Added generate:seed-bible-reference script
    • Updated dev and build scripts to generate reference before building
    • Added dependencies: seed-bible, typedoc, typedoc-plugin-markdown, typedoc-plugin-missing-exports, preact, and @preact/signals
  • Translation handling (tools/translate-docs.ts): Excluded seed-bible/ directory from translation since the API reference is English-only and auto-generated

  • Git configuration (docs/.gitignore): Added seed-bible/reference/ to ignore generated files

  • Navigation labels (docs/.vuepress/labels.json): Added "Seed Bible" label for navbar

Notable Implementation Details

  • The generator creates a custom ReferenceRouter class that strips the seed-bible/ prefix from module names, so pages land at reference/extensions/ rather than reference/seed-bible/extensions/
  • TypeDoc's internalModule is set to "Unexported types" to document types that are used but not exported, with explanatory text added to that page
  • The sidebar structure maps TypeDoc's navigation tree to VuePress sidebar items with proper link resolution
  • Generated reference pages are excluded from version control but included in builds via the automated generation step

The docs site now has a Seed Bible section (navbar: "Seed Bible") with an
API reference for third-party extension developers. It covers the three
entry points a sandboxed extension imports: seed-bible/extensions,
seed-bible/extensions/testing and seed-bible/components. Every class,
interface, type, function and component gets its own page, types link to
each other, and the sidebar lists each package's members by kind.

The pages are generated by TypeDoc (with typedoc-plugin-markdown) from the
type declarations of the seed-bible npm package that docs/package.json
pins, so they match what developers install. `pnpm dev` and `pnpm build`
regenerate them; they are git ignored. Types the packages use without
exporting are listed on an "Unexported types" page per package so no
link dead-ends.

The section is English only, so translate-docs skips it and every
language's navbar links to the English pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LsURzJUPiQG5pGJ5B9mac
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The top of the Seed Bible extensions page now has an "Agent bootstrap"
card with a "Copy instructions" button. The instructions are a prompt for
a coding agent (Claude Code, Codex, ...): ask what to build, scaffold the
project with create-seed-bible-extension, read the API's type
declarations and reference, follow the extension rules (permissions,
promises and SandboxError, signals, translations, shared components),
test with createTestHost, and run check, lint and test.

The prompt lives in the page's markdown, in a collapsible block, so it is
readable and searchable without JavaScript. AgentBootstrap.vue copies it
and wraps it for reading.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LsURzJUPiQG5pGJ5B9mac
The "Seed Bible Developer Docs" card on the home page said "Coming
December" and linked nowhere. It now links to /seed-bible/ with
"Extension API reference →", like the other cards. Every language links
to the English pages, since the section is English only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LsURzJUPiQG5pGJ5B9mac
The Open Ecosystem page's Seed Bible card said "Developer docs coming
December", and the footer listed "Seed Bible (Coming soon)" as plain
text. The card now ends in an "Extension API reference →" link and the
footer item is a "Seed Bible extensions" link, both to /seed-bible/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LsURzJUPiQG5pGJ5B9mac
The Seed Bible section now includes the developer guide, the extension
API guide and the security model, under /seed-bible/guide/, with a
"Guides" group in the sidebar. They're written in the seed-bible
repository's docs/, so generate-guides.mjs downloads them from the
release tag of the seed-bible version in docs/package.json: the same
release the API reference documents. Downloads are cached in
.vuepress/.cache.

GitHub and VuePress name heading anchors differently, so links between
and within the guides are rewritten to VuePress's anchors (an unknown
anchor fails the build), and links to other files in seed-bible point at
them on GitHub at that tag.

`pnpm generate:seed-bible` (run by dev and build) now generates both the
reference and the guides. The landing page links to the guides here
instead of on GitHub.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LsURzJUPiQG5pGJ5B9mac
The guides mention types and calls as inline code and show their shapes
in code blocks, but nothing linked to the generated reference pages.
generate-guides.mjs now indexes the reference (every documented name,
plus each sb.<property> and sb.<property>.<member> on the SandboxContext
page, with the anchors VuePress gives them) and adds links:

- Inline code naming something documented (`SandboxNote`,
  `sb.notes.create`, or `create` within the sb.notes section) links to
  it, the first time it appears in each section.
- A heading naming something (### `sb.notes`) gets a "Reference:" line.
- A TypeScript code block using documented types gets a "Reference:"
  line listing them, since links can't go inside code.

Names shorter than three characters aren't linked: the `T` component
would otherwise catch every type parameter.

Linked inline code also gets a visible underline across the site. The
existing light underline vanished against code's grey background, so a
linked `SandboxNote` looked like plain code (this also affected linked
code on the getting started, OpenAPI and SDK pages).

The markdown helpers both generators use moved to markdown.mjs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LsURzJUPiQG5pGJ5B9mac
Properties whose type is an object, like SandboxContext's `app` and
`notes`, were shown as `app: object;`, and function signatures named
their parameters without types (`toast: (message) => Promise<void>`),
because typedoc-plugin-markdown collapses both by default. The reference
now turns on expandObjects and expandParameters, so each signature shows
the whole type: `app: { isMobile: …; toast: (message: string) => … }`.

The plugin indents nested object types unevenly, which the expanded
types made obvious, so the generator formats every signature code block
with Prettier afterwards. Examples written in the doc comments are left
exactly as written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LsURzJUPiQG5pGJ5B9mac
Types named in the Seed Bible pages' TypeScript code blocks now link to
their reference pages: `SandboxNote` in `Promise<SandboxNote[]>` opens
the SandboxNote page. This covers the generated reference's signatures
and the guides' code alike.

Markdown can't put links inside code, so referenceCodeLinks.mjs is a
VuePress plugin that wraps the Shiki code block renderer and links each
documented name (three letters or longer) in the highlighted HTML. It
only touches text between tags inside the <pre>, so attributes, line
numbers and the copy button's plain text are unaffected. A type's own
page doesn't link to itself, and pages outside /seed-bible/ and non-code
blocks (like the agent bootstrap's text) are left alone. Linked names
keep their highlighting colour, with an underline.

The "Reference:" lines generate-guides.mjs added after the guides' code
blocks only repeated these links, so they're gone; the ones under
headings stay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LsURzJUPiQG5pGJ5B9mac
The type links inside code blocks are plain <a> tags added to the
rendered HTML, which the VuePress router doesn't handle, so clicking one
reloaded the whole site. A click listener in client.ts now sends them
through the router, like the sidebar's links. Clicks meant for a new tab
or window (Ctrl/Cmd, Shift, Alt or a middle click) are left to the
browser.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LsURzJUPiQG5pGJ5B9mac

This branch was successfully deployed

1 active deployment
docs-preview — 3fc6779e Deployed Nov 19, 2026 by KallynGowdy via Deploy preview #51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants