js/commands/doc/theme

js/commands/doc/theme.ts

fino:commands/doc/theme — the page component contract for fino doc.

Every page fino doc build emits is produced by a component. This module defines the props that component receives and ships the default one, so replacing the look of a documentation site means writing a component rather than patching the generator.

A theme is an ordinary module whose default export is a fino:ui component taking DocsPageProps. It renders in an isolated realm, so its props are plain JSON and its output is a portable tree: a theme cannot reach the generator's filesystem, its parser, or its process.

Each page arrives twice over. page carries the structured record — the parsed ModuleDoc, GuideDoc, or index data — for a theme that wants to lay out symbols itself. prepared carries the same content already rendered to HTML, because Markdown, cross-reference resolution, and syntax highlighting need the parser and cannot happen inside the realm. Use prepared for the prose and page for the structure, or ignore either one.

import { h } from 'fino:ui';
import { rawHtml } from 'fino:ui/html';
import type { DocsPageProps } from 'fino:commands/doc/theme';

export default function Page(props: DocsPageProps) {
  return h('html', null,
    h('head', null, h('title', null, props.page.title)),
    h('body', null, rawHtml(props.prepared.contentHtml)),
  );
}

Interfaces

interface DocsNavNode {

One entry in the documentation navigation tree.

Directory nodes carry children and no href. Leaf nodes carry an href relative to the site root, which relativeHref() rewrites for the page being rendered.

Properties

label: string

Display label for this entry.

href?: string

Site-root-relative target, absent for grouping nodes.

kind?: 'api' | 'guide'

Which collection this entry belongs to.

children: DocsNavNode[]

Nested entries, empty for leaves.

interface DocsSite {

Site-wide data shared by every page.

Properties

title: string

Site title, inferred from package.json or Cargo.toml unless overridden.

nav: DocsNavNode[]

Navigation tree covering every guide and module.

cssHref: string

Site-root-relative stylesheet path written by the generator.

scriptHref: string

Site-root-relative client script path written by the generator.

modules: ModuleDoc[]

Every documented module, in output order.

guides: GuideDoc[]

Every authored guide, in output order.

interface DocsModulePage {

An API reference page for one module.

Properties

kind: 'module'
href: string

Site-root-relative output path for this page.

title: string

Page title, without the site title.

module: ModuleDoc

Parsed module record, identical to its api.json entry.

interface DocsGuidePage {

A page for one authored Markdown guide.

Properties

kind: 'guide'
href: string
title: string
guide: GuideDoc

Parsed guide record, including its original Markdown in text.

interface DocsIndexPage {

The site landing page, built from the project README.

Properties

kind: 'index'
href: string
title: string

interface DocsPrepared {

Content the generator rendered ahead of the theme.

Markdown, cross-reference links, and syntax highlighting need the doc parser, which does not exist inside the rendering realm. These are trusted HTML strings from the generator; pass them to rawHtml().

Properties

contentHtml: string

Complete page body: symbol sections, guide prose, or the rendered README.

pageIndexHtml: string

In-page table of contents, or an empty string when the page has none.

module?: HtmlModule

Structured module content, present only for module pages.

guide?: HtmlGuide

Structured guide content, present only for guide pages.

interface DocsPageProps {

Props passed to a documentation page component.

Properties

site: DocsSite

Data shared by every page in the site.

page: DocsPage

The page being rendered.

prepared: DocsPrepared

Generator-rendered HTML for this page.

Types

type DocsPage = DocsModulePage | DocsGuidePage | DocsIndexPage

The page currently being rendered.

Functions

function relativeHref(fromHref: string, toHref: string): string

Rewrite a site-root-relative href for the page currently being rendered.

Navigation and asset paths arrive relative to the site root so one navigation tree serves every page. Absolute URLs and fragments pass through unchanged.

import { relativeHref } from 'fino:commands/doc/theme';

const href = relativeHref('net/http.html', 'index.html');

function Sidebar(props: { site: DocsSite; currentHref: string }): VNode

Render the default documentation sidebar.

Exported so a theme that wants its own chrome can keep the standard navigation, or wrap it.

function ModuleBody(props: { module: HtmlModule }): VNode

Render the standard body of one module reference page.

The generator uses this to build DocsPrepared.contentHtml for module pages, so a theme that wants custom chrome around the standard symbol layout renders exactly what the default theme does.

import { h } from 'fino:ui';
import { ModuleBody } from 'fino:commands/doc/theme';

const body = h('article', null, h(ModuleBody, { module: prepared.module! }));

function GuideBody(props: { guide: HtmlGuide }): VNode

Render the standard body of one guide page.

The generator uses this for DocsPrepared.contentHtml on guide pages.

function DocsPageComponent(props: DocsPageProps): VNode

The documentation page component used when no --theme is given.

It renders the standard three-column layout: navigation, page body, and an in-page table of contents when the page has one.