Writing a theme

A theme is a small manifest plus React components that yaakdoc renders on the server with Vite. You write the layout and the styles; yaakdoc's unstyled components and hooks provide the content.

npm i @yaakdoc/react react react-dom

Anatomy of a themeCopy Anchor Link

my-theme/
├── theme.ts          manifest, loaded by yaakdoc in Node
└── src/
    ├── entry.tsx     server entry: { Layout, components?, Head? }
    ├── client.ts     client entry: the islands to hydrate
    └── styles.css    styles (any CSS Vite supports: plain CSS, Tailwind, ...)

Use it with "theme": "./my-theme".

The manifestCopy Anchor Link

// Keep this file free of React imports: yaakdoc loads it in Node.
import { defineTheme } from "@yaakdoc/react/theme";
import { z } from "zod";

export default defineTheme({
  name: "my-theme",
  entry: "./src/entry.tsx",
  client: "./src/client.ts",
  styles: ["./src/styles.css"],

  // Font files (from your styles) to preload, so the first paint doesn't use a fallback font.
  // A role is skipped when the user sets `branding.fonts.sans` / `branding.fonts.mono`.
  preloadFonts: {
    sans: ["inter-latin-wght-normal.woff2"],
  },

  // Shiki themes for syntax highlighting.
  highlight: {
    light: "github-light",
    dark: "github-dark",
  },

  // Validates `themeOptions` and fills in defaults.
  options: z.object({
    accent: z.string().default("violet"),
  }),

  // Vite plugins the theme needs, e.g. Tailwind CSS.
  vitePlugins: async () => [
    (await import("@tailwindcss/vite")).default()
  ],

  // What `yaakdoc eject` copies, and the packages it lists.
  eject: {
    files: ["theme.ts", "src/**"],
    dependencies: ["@yaakdoc/react"],
  },
});

Theme source is processed by Vite, so TSX works without a build step, and a theme package can ship its source as is.

The layoutCopy Anchor Link

entry.tsx default-exports a ThemeRuntime. Its Layout renders the page <body>. yaakdoc renders <html> and <head>: meta tags, assets, the branding CSS variables and the color mode script.

import {
  Content,
  Footer,
  Logo,
  NavTree,
  type ThemeRuntime,
} from "@yaakdoc/react";

import { ColorModeToggle, NavFilter } from "@yaakdoc/react/islands";

const theme: ThemeRuntime = {
  Layout: ({ page }) => (
    <div className="layout">
      <aside id="sidebar">
        <Logo />
        <NavFilter target="#sidebar [data-yd=nav]" />
        <NavTree />
      </aside>

      <ColorModeToggle />

      <Content />

      <Footer />
    </div>
  ),
};

export default theme;

<Content /> renders whatever the current page is. page.kind tells you which kind it is:

In pages: "single" mode, the index page contains the whole reference. <Content /> handles both modes, but you can compose the pieces yourself.

Data hooksCopy Anchor Link

A prepared request already contains everything a theme needs:

• href and markdownUrl
• resolvedUrl, with variables resolved and secrets as {{placeholders}}
• descriptionHtml, sanitized Markdown
• bodyHtml, examples[].html and responses[] (Shiki-highlighted example responses with status, label and language)
• headers, params and auth, each with inheritedFrom information

A prepared custom page has title, description, sidebarTitle, icon, href, markdownUrl, summary and html.

ComponentsCopy Anchor Link

All components are unstyled. They render semantic markup with stable data-yd="..." attributes, and accept className.

A few attributes are useful when styling with plain CSS:

• [data-method="get"] on method badges.
• [data-yd="url-variable"] on the {{variables}} inside a RequestUrl.
• [data-yd-section] on documented sections, which the scroll spy uses.
• aria-current on the active navigation link.

Overriding componentsCopy Anchor Link

Every component above can be replaced everywhere, including inside other components, by registering an override under its name. The override receives the same props, plus Default, the original component:

const theme: ThemeRuntime = {
  Layout,
  components: {
    MethodBadge: ({ request, Default }) => {
      return (
        <Default request={request} className="badge" />
      );
    },
  },
};

Use overridable(name, Component) to make your own components overridable.

HelpersCopy Anchor Link

These keep themes consistent with the built-in components:

Branding tokensCopy Anchor Link

The user's branding arrives as CSS custom properties on :root:

• --yd-color-primary, --yd-color-accent, --yd-color-background and --yd-color-foreground, with per-mode values under [data-theme="light"] and [data-theme="dark"]
• --yd-font-sans and --yd-font-mono

Use them with fallbacks:

:root {
  --primary: var(--yd-color-primary, #6d28d9);
}

Color modeCopy Anchor Link

The color mode is applied before first paint as data-theme="light|dark" on <html>, and color-scheme is set to match. Without JavaScript, follow prefers-color-scheme.

Highlighted code uses Shiki's dual themes. Pick the right variant with:

.shiki,
.shiki span {
  color: light-dark(var(--shiki-light), var(--shiki-dark));
}

EnvironmentsCopy Anchor Link

When the config lists several environments, environment-dependent data is prepared once per environment:

• request.variants holds resolvedUrl and examples for each environment.
• document.variableSets holds the variables table for each environment.
• document.environments lists the options, default first.
• page.html of custom pages contains a variant of each block that uses variables, wrapped in [data-yd-env], so the switcher works on pages without extra code.

Render the variants with <EnvironmentVariants variants={...}>{(variant) => ...}</EnvironmentVariants>, and add a switcher with <EnvironmentSelect /> (or build your own with useEnvironment). yaakdoc adds a small head script and CSS, so a remembered choice shows up before first paint.

Entry pointsCopy Anchor Link