@avelon/docs-site

@avelon/docs-site builds the Avelon documentation site from the same Markdown the repo already ships. The landing page is the Avelon map: vocabulary, then the commands and types you reach for. Fenced examples are syntax-colored. Reach for this package when you need to regenerate index.html after a README or catalog change.

Installation

bun install

This package lives in the Avelon workspace. You run it from the repository, not as an application dependency.

Basic Usage

import { mkdir } from 'node:fs/promises'
import { buildSite } from '@avelon/docs-site'

await mkdir('/tmp/avelon-docs', { recursive: true })
await buildSite({
  repoRoot: process.cwd(),
  outDir: '/tmp/avelon-docs',
})

bun run build

build writes dist/index.html as the Avelon map, dist/packages/<name>/index.html from each package README, and dist/drivers/index.html from docs/15-driver-authoring.md.

Landing page

The first page is the map of the framework. A vocabulary table names the Avelon words. Catalog sections then list what you want, what you reach for, and a one-line note. Package READMEs are not the homepage; they hang off /packages.

Method Reference

Method / export	Signature	Description
`CATALOG`	`readonly CatalogSection[]`	Grouped jobs and Avelon names rendered as the landing tables.
`CatalogRow`	`interface`	`term`, `youReachFor`, and `notes`.
`CatalogSection`	`interface`	`title` plus `rows`.
`VOCABULARY`	`readonly VocabularyEntry[]`	Named Avelon words and one-line jobs.
`VocabularyEntry`	`interface`	`name` and `job`.
`buildSite`	`(options: BuildSiteOptions) => Promise<BuildSiteResult>`	Writes `index.html` and derived pages.
`buildFromRepo`	`() => Promise<BuildSiteResult>`	Builds into this package's `dist/` from the repo root.
`BuildSiteOptions`	`interface`	`repoRoot` and `outDir`.
`BuildSiteResult`	`interface`	`landingPage` and `pages`.
`markdownToHtml`	`(source: string) => string`	Converts house-style Markdown to HTML, with syntax-colored fences.
`headingId`	`(text: string) => string`	Stable slug for a heading, used as the HTML `id`.
`escapeHtml`	`(value: string) => string`	Escapes text for HTML.

Testing

import { mkdtemp } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { buildSite } from '@avelon/docs-site'

const outDir = await mkdtemp(join(tmpdir(), 'avelon-docs-'))
const result = await buildSite({ repoRoot: process.cwd(), outDir })
await Bun.file(result.landingPage).text()

bun test
bun run typecheck
reeve docs:check