Authoring components

Write ordinary Markdown for most pages. Use MDX when a page needs components, and import them from @tenphi/cookbook/components. Local MDX is supported by default; npm MDX requires an explicit trust: "mdx" source declaration.

Every panel requires a label. Arrow keys, Home, and End move between tabs; right-to-left layouts reverse the horizontal arrow direction. Without JavaScript, all panels remain readable under their headings.

import { Tab, Tabs } from "@tenphi/cookbook/components";

<Tabs label="Installation">
  <Tab label="npm">Run `npm install your-package`.</Tab>
  <Tab label="pnpm">Run `pnpm add your-package`.</Tab>
</Tabs>

Use kind="note", "tip", "caution", or "danger"; title overrides the visible label. The default kind is note. Status colors come from theme.palette.info, success, warning, and danger and adapt to all schemes and contrast modes.

<Callout kind="tip" title="Keep content close to code">
  Relative Markdown links continue to work after Cookbook assigns public routes.
</Callout>

Pass labeled source strings to create an accessible tabbed code group. language selects the Shiki grammar (defaults to plain text). Groups share semantic syntax colors, configured grammars/transformers, and copy controls with Markdown fences. Each panel retains keyboard-accessible tabs and readable fallback content.

<CodeGroup
  label="Install Cookbook"
  items={[
    { label: "npm", language: "shell", code: "npm install @tenphi/cookbook" },
    { label: "pnpm", language: "shell", code: "pnpm add @tenphi/cookbook" },
  ]}
/>

npm install @tenphi/cookbook

pnpm add @tenphi/cookbook

Use a card to link to another page, or omit href to present a standalone summary. Steps renders an ordered list; put ordinary li elements inside it.

import { Card, Steps } from "@tenphi/cookbook/components";

<Card title="On-page navigation" href="#on-page-navigation">
  Offer a compact contents list on smaller screens.
</Card>

<Steps>
  <li>Choose a content source.</li>
  <li>Configure the navigation.</li>
  <li>Build and check the output.</li>
</Steps>

1. Choose a content source.
2. Configure the navigation.
3. Build and check the output.

Preview runs HTML and optional JavaScript in a sandboxed iframe with a source disclosure. It cannot access the documentation page’s origin. Its css prop is for the isolated preview document; style the documentation shell with Tasty.

import { Preview } from "@tenphi/cookbook/components";

<Preview
  title="A simple button"
  html={'<button type="button">Try it</button>'}
  css={"button { padding: 0.75rem; }"}
/>

<!doctype html><meta charset="utf-8"><style>button { padding: 0.75rem; }</style><button type="button">Try it</button>

Logo renders the Cookbook mark. Use label when it carries meaning or decorative beside nearby text that already names the site. To display your own artwork in the header and drawer, configure site.logo.

Use a diff code fence to highlight additions and deletions. The + and - markers remain visible independently of their theme-aware backgrounds:

-formatOkhsl(v.h, v.s * 100, l * 100);
+formatOkhsl(v.h, v.s, l);

The public package exports each component’s props type, such as TabProps, CalloutProps, and CodeGroupProps. Styles and all named sub-elements are listed in Component styles.

Desktop pages show a table of contents. Opt into a compact disclosure below the header on smaller screens, globally in docs.config.ts:

tableOfContents: { mobile: true, minHeadingLevel: 2, maxHeadingLevel: 3 }

The same frontmatter field can change heading levels or set mobile: false on one page. tableOfContents: false disables both versions. Selecting a mobile contents link closes the disclosure and moves keyboard focus to the heading. The desktop contents list highlights the current section and scrolls its own list when the active link moves out of view. Customize theme.styles.MobileTableOfContents and TableOfContentsLayout.

Use a relative local image in frontmatter. Cookbook reads its intrinsic dimensions and reserves the correct aspect ratio as the layout responds to screen width:

hero:
  tagline: Build something useful.
  image:
    file: ./assets/hero.png
    alt: A preview of the documentation

Use light and dark instead of file for appearance variants; both must have the same aspect ratio. Remote or public-path images require explicit width and height. Hero images load eagerly with high fetch priority; use ordinary Markdown images for content farther down the page. theme.styles.Hero.Visual controls responsive sizing without changing the intrinsic dimensions.