#Configuration

All configuration lives in ciderpress.config.ts at your repo root. Use defineConfig for type safety and autocompletion.

import { defineConfig } from 'ciderpress'

export default defineConfig({
  title: 'My Docs',
  description: 'Project documentation',
  pages: [{ title: 'Introduction', path: '/intro', include: 'docs/intro/*.md' }],
})

Configuration is loaded via c12. Supported file formats: .ts, .mts, .js, .mjs, .json, .jsonc, .yml, .yaml.

pages is the only required field. Every other top-level key is optional — minimal config produces a clean site with zero framework branding.

#Rich text

Display strings on the home page accept inline markup — no flag, no opt-in. Ciderpress parses it and drops anything unsafe.

This covers the hero, every home.blocks[] band (proof, features, showcase, split, tabs, cta), and workspace cards. Strings outside those surfaces — footer, sidebar.promo, sidebar link text, and announcement — render verbatim today, so markers in them show as literal characters.

** is the accent: a heading is already bold, so weight by itself would say nothing there — ** colours the phrase instead, in headings and body copy alike. Reach for <strong> on the rare occasion you want bold without the colour. == keeps the meaning it has in Obsidian, Typora, and markdown-it-mark — a highlight.

Because inline HTML is supported, <span class="cp-accent">text</span> and <mark>text</mark> are equivalent long forms of the two markers. Useful when you want the accent on part of a word, or inside copy that already uses asterisks.

Inline HTML is allowed for a, b, strong, i, em, code, kbd, mark, sup, sub, span, small, u, s, del, and ins, keeping only the class (or classname), title, and (on <a>) href attributes. An <a href> is validated exactly like a markdown link.

#Escaping

A backslash makes any marker literal — \*, \`, \=, \[, \], \<, and \\. Needed when copy has to name a glob or an expression:

description: 'Discovers \\*\\*/\\*.md across the repo'

An asterisk is only read as italic when it hugs its text, so 2 * 3 and a bare *.md already pass through untouched; reach for the backslash when a marker sits directly against a word.

home: {
  hero: {
    tagline: 'Point it at your `markdown`. <strong>No restructuring.</strong>',
  },
  blocks: [
    { type: 'split', title: 'One config, **validated at boot**' },
    { type: 'tabs', title: 'Now with ==OpenAPI==' },
    { type: 'cta', body: 'Questions? [Open an issue](https://github.com/acme/docs/issues).' },
  ],
}

#What gets dropped

Parsing produces React elements directly — markup is never injected as raw HTML, so nothing in a config string can execute.

• <script>, <style>, <iframe>, <object>, <embed>, <template>, <noscript> — removed with their contents
• Any other unrecognised tag — unwrapped, its text kept (<div>hi</div> renders hi)
• Every attribute outside the whitelist, including onclick and style
• Links whose scheme fails validation (javascript:, data:) — the label stays, the anchor goes

Block markdown — lists, headings, blockquotes, tables — is not supported. These fields are single-line display copy; use a markdown page for prose.

#Plain-text contexts

The same string is stripped to bare text wherever markup cannot render: the document <title>, <meta name="description">, and the tab strip's aria-label. One value serves both.

description: 'Beautiful Docs, **Zero Effort**',
// hero headline → Beautiful Docs, <strong class="cp-accent">Zero Effort</strong>
// <meta name="description"> → Beautiful Docs, Zero Effort

#Hero title accent

The hero headline accents its trailing half automatically. Bold anything in the title and that guess steps aside — you get exactly what you marked:

// automatic — trailing half is accented
description: 'Beautiful Docs, Zero Effort',
// explicit — only the marked words
description: 'Beautiful **Docs**, Zero Effort',

#Escape hatch

For layout beyond inline markup, override the theme components rather than reaching for HTML in config: HomeLayout accepts beforeHero / afterHero slots, and Hero, HomeSplit, HomeTabs, CTA, PageRail, RichText, and renderRichText are all exported from @ciderpress/ui.

#Site identity

Top-level scalar fields that identify the site itself.

defineConfig({
  title: 'Acme',
  description: 'Documentation for the Acme platform',
  base: '/',
  version: 'v1.0',
  pages: [/* ... */],
})

#seo

Set the production origin once; Ciderpress derives canonical URLs, absolute social metadata, and sitemap.xml from it. Rspress continues to provide the page title, description, and base Open Graph tags.

seo: {
  origin: 'https://docs.acme.com',
  titleTemplate: '%s | Acme',
  socialImage: '/social.png',
  openGraph: {
    siteName: 'Acme',
    locale: 'en_US',
  },
  twitter: {
    card: 'summary_large_image',
    site: '@acme',
  },
  robots: {
    index: true,
    follow: true,
  },
  sitemap: {
    changeFrequency: 'weekly',
    priority: '0.5',
  },
}

Rspress also generates llms.txt, llms-full.txt, and per-page Markdown automatically. These are root-level discovery files and do not require an HTML <head> tag.

#redirects

Redirect moved documentation routes after the Ciderpress app loads:

redirects: [
  { from: '^/old-guide$', to: '/guides/new-guide' },
  { from: ['^/v1/install$', '^/v2/install$'], to: '/getting-started/install' },
  { from: '^/legacy/(.*)$', to: '/archive/$1' },
]

Rules run in order, and each from value is compiled as a regular expression. Anchor a path with ^ and $ when it should match exactly.

These are client-side redirects. The app loads before the browser replaces its URL, and the server does not return a real 301 or 308. This is usually sufficient for internal documentation. For public documentation, prefer redirects configured in the hosting platform: they run before page load, avoid a visible flash, and preserve search-engine signals.

The host must serve Ciderpress's generated 404.html for unmatched routes. Netlify, Vercel, and GitHub Pages do this by default. If a host does not, configure its fallback route to 404.html.

#brand

Brand chrome — icon, wordmark, hero background, favicon, and the inline FOUC loader. Defaults to invisible: omit any field to render nothing in that slot.

brand: {
  icon:    IconConfig,
  logo:    string | LogoFn,
  banner:  string | BannerFn,
  favicon: ImageSource,
  loader:  'apple' | 'classic' | false | LoaderConfig,
}

#BannerFn

type BannerFn = (params: { theme: LogoContext }) => ImageSource | React.ReactNode

The function receives the active theme context and returns either an image source or a React node. Use the React-node variant for procedural canvas, WebGL, or inline SVG backgrounds that respond to theme tokens.

brand: {
  banner: ({ theme }) => <HeroCanvas variant={theme.variant} />,
}

Put component JSX in a .tsx module, import it from ciderpress.config.ts, and return createElement(HeroCanvas, props). Components run in the browser, so keep module initialization browser-safe and access DOM APIs from effects.

home.hero.background takes precedence when set. Otherwise, a plain-string banner is serialized as an image background and a function banner renders at runtime.

#LoaderConfig

type LoaderConfig =
  | {
      content: string
      label?: string
      minDisplayMs?: number
      maxDisplayMs?: number
    }
  | {
      component: ComponentType
      label?: string
      minDisplayMs?: number
      maxDisplayMs?: number
    }

label is read by screen readers. minDisplayMs and maxDisplayMs clamp visible duration so the loader doesn't flash or hang.

#theme

Theming uses a single array of theme entries. The first entry is the default unless one is explicitly marked. Both the named-theme picker and the light/dark variant toggle are independent — themeSwitcher and variantSwitcher.

theme: {
  themes:           ThemeEntry[],
  defaultVariant?:  'light' | 'dark' | 'system',
  themeSwitcher?:   boolean,
  variantSwitcher?: boolean,
  overrides?:       Partial<ThemeColors>,
}

#ThemeEntry

type ThemeEntry =
  | BuiltInThemeName
  | ThemeInput
  | { name: BuiltInThemeName; default?: boolean }
  | (ThemeInput & { default?: boolean })

Built-in names and full custom theme definitions share the same array. Either form accepts a default: true marker to override the "first entry wins" rule.

theme: {
  themes: [
    'honeycrisp',
    {
      name: 'acme',
      default: true,
      colors: {
        brand: '#ff5a1f',
        text:  '#1a1a1a',
      },
    },
  ],
  defaultVariant:  'dark',
  themeSwitcher:   true,
  variantSwitcher: true,
}

#pages

The information architecture tree. Required. Each entry is a Page — the same shape used for leaf documents, sidebar groups, and glob-discovered sections.

Renamed from sections (Page replaces the old Section interface). Children live on Page.pages (renamed from items).

#Page

interface Page {
  // ---- Identity ----
  title: TitleConfig
  description?: string
  path?: string
  icon?: IconConfig

  // ---- Source (declare exactly one) ----
  include?: string | string[]
  content?: string | (() => string | Promise<string>)
  pages?: Page[]

  // ---- Navigation behavior ----
  nav?: {
    hidden?: boolean
    collapsible?: boolean
    island?: boolean
    root?: boolean
  }

  // ---- Landing page ----
  landing?: boolean

  // ---- Card behavior ----
  card?: CardConfig

  // ---- Default page metadata ----
  defaults?: Frontmatter

  // ---- Glob-discovery options ----
  discover?: {
    sort?: SortStrategy
    recursive?: boolean
    ignore?: string[]
    indexFile?: string
  }

  // ---- Per-page integration ----
  openapi?: OpenAPISpec
}

#Identity

#Source — declare exactly one

#nav.* — navigation behavior

Grouped together so per-page chrome flags don't sprawl across the top level of Page.

#Landing + card

#CardConfig

interface CardConfig {
  icon?: IconConfig
  scope?: string
  description?: string
  tags?: string[]
  badge?: { src: string; alt: string }
}

Card content resolves from this priority order (highest first): card.description → source file frontmatter description → Page.description.

#defaults — default page metadata

Renamed from frontmatter. Same Frontmatter type — values here are merged into every child page's frontmatter; per-file YAML wins on conflict.

{
  title: 'API Reference',
  defaults: { aside: 'left', editLink: false },
  pages: [
    { title: 'Auth',  path: '/api/auth',  include: 'docs/api/auth.md' },
    { title: 'Users', path: '/api/users', include: 'docs/api/users.md' },
  ],
}

#discover.* — glob-discovery options

Only applies when include is a glob. Renamed from the flat Section.{sort,recursive,exclude,entryFile} fields.

#openapi

Per-page OpenAPI spec integration. Generates API operation pages under the page's path. See OpenAPISpec for the shape.

#Examples

Leaf page from a single file:

{
  title:   'Architecture',
  path:    '/architecture',
  include: 'docs/architecture.md',
}

Group with explicit children:

{
  title: 'Guides',
  path:  '/guides',
  pages: [
    { title: 'Quick Start', path: '/guides/quick-start', include: 'docs/guides/quick-start.md' },
    { title: 'Deployment',  path: '/guides/deployment',  include: 'docs/guides/deployment.md' },
  ],
}

Glob-discovered section with discovery options:

{
  title:       'Reference',
  path:        '/reference',
  description: 'API and CLI reference.',
  include:     'docs/reference/**/*.md',
  discover: {
    sort:      'alpha',
    recursive: true,
    ignore:    ['**/draft-*.md'],
    indexFile: 'overview',
  },
}

#apps, packages, workspaces

Top-level workspace surfaces. Kept flat — apps and packages are the common cases; workspaces is for arbitrary custom groups like "Integrations" or "Plugins".

apps:       Workspace[],
packages:   Workspace[],
workspaces: WorkspaceGroup[],

All three drive the home page card grid (via a showcase block in home.blocks), the auto-generated landing card on their parent, and the workspace introduction page.

#Workspace

interface Workspace {
  title: TitleConfig
  description: string
  path: string
  icon?: IconConfig
  tags?: string[]
  badge?: { src: string; alt: string }
  include?: string | string[]
  pages?: Page[]
  defaults?: Frontmatter
  discover?: {
    sort?: SortStrategy
    recursive?: boolean
    ignore?: string[]
    indexFile?: string
  }
  openapi?: OpenAPISpec
}

#WorkspaceGroup

interface WorkspaceGroup {
  title: string
  description?: string
  icon: IconConfig
  items: Workspace[]
  link?: string
}

workspaces: [
  {
    title: 'Integrations',
    icon: { id: 'pixelarticons:integration', color: 'orange' },
    items: [{ title: 'Stripe', description: 'Payment processing', path: '/integrations/stripe' }],
  },
]

#OpenAPISpec

Per-page or per-workspace OpenAPI integration. The same shape lives on Page.openapi and Workspace.openapi — declare it once at the mount point you want the API operation pages to live under.

interface OpenAPISpec {
  spec: string
  path: string
  title?: string
  sidebarLayout?: 'method-path' | 'title'
}

When declared on a Workspace, path must be nested under the workspace's own path — that's checked at validate time. See the OpenAPI reference for a full walkthrough.

#socials

Root-level array of social links. Single source of truth — both topbar.socials and footer.socials reference this list via true.

socials: SocialLink[]

#SocialLink

interface SocialLink {
  icon: SocialLinkIcon | { svg: string }
  url: string
  label?: string
}

The Rspress mode/content discriminator is no longer exposed — every link is a URL link.

Built-in SocialLinkIcon values:

import type { SocialLinkIcon } from '@ciderpress/config'

// 'discord' | 'facebook' | 'github' | 'instagram' | 'linkedin' | 'slack'
// | 'x' | 'youtube' | 'gitlab' | 'X' | 'bluesky' | 'npm'

Any icon outside this set must be supplied as { svg: '<svg>...</svg>' }.

#Boolean reference pattern

topbar.socials and footer.socials accept either true (reuse root socials) or SocialLink[] (override with a specific list for that surface).

socials: [
  { icon: 'github',  url: 'https://github.com/acme'  },
  { icon: 'discord', url: 'https://discord.gg/acme'  },
],
topbar: { socials: true },                                  // mirror root list
footer: { socials: [{ icon: 'github', url: '...' }] },      // footer-specific

#topbar

Top navigation bar — nav items, primary CTA, social row, announcement banner.

topbar: {
  nav:           'auto' | NavItem[],
  cta?:          ButtonConfig,
  socials?:      true | SocialLink[],
  announcement?: AnnouncementConfig,
}

#nav: 'auto' rule

Auto-nav emits one top-level entry per root pages entry that has a path. Children are not flattened into dropdowns. Roots with nav.hidden: true are skipped. Workspaces declared via top-level apps / packages / workspaces are not included — they show on the home grid only. For dropdowns or workspace items in the topbar, use the explicit NavItem[] form.

#NavItem

interface NavItem {
  title: string
  link?: string
  items?: NavItem[]
  activeMatch?: string
}

#AnnouncementConfig

interface AnnouncementConfig {
  id?: string
  lead?: string
  message: string
  cta?: { href: string; label: string }
  persistent?: boolean
}

#sidebar

Persistent sidebar chrome — links pinned above and below the nav tree, plus the optional promo card.

sidebar: {
  top?:    SidebarLink[],
  bottom?: SidebarLink[],
  promo?:  SidebarPromo,
}

#SidebarLink

Sidebar links use ButtonConfig directly — no separate type. The same text/href/variant/shape/icon vocabulary as every other button surface.

sidebar: {
  top: [
    { text: 'Home',   href: '/',                       icon: 'pixelarticons:home',   variant: 'ghost' },
  ],
  bottom: [
    { text: 'GitHub', href: 'https://github.com/acme', icon: 'pixelarticons:github', variant: 'secondary' },
  ],
}

#SidebarPromo

interface SidebarPromo {
  title: string
  body: string
  cta: ButtonConfig
}

#badges

Badge configuration — glob rules that apply a badge (or a named status) by route, plus the group flag for collapsible-doc groups. Badges render on the sidebar, breadcrumb, and section cards. A page's own frontmatter or defaults badge/status wins over a rule. See the Badges reference for the full model.

badges: {
  rules: [
    { match: '/api/experimental/**', status: 'alpha' },
    { match: ['/v2/**', '/beta/**'], badge: { text: 'v2', variant: 'info' } },
  ],
  group: true,
}

#BadgeRule

interface BadgeRule {
  match: string | string[]
  badge?: string | BadgeConfig | array
  status?: string | string[]
}

Declare at least one of badge or status. match supports *, **, and ?.

#statuses

The named status registry — the semantic layer over badges. A status is a reusable, documented preset referenced by id from a page's status field. Entries merge over the built-in defaults by id (matching ids override, new ids extend).

statuses: [
  {
    id: 'alpha',
    title: 'Alpha',
    description: 'Early and unstable — expect changes.',
    variant: 'warning',
  },
  {
    id: 'design-partner',
    title: 'Design Partner',
    description: 'Available to design partners only.',
    color: '#7c3aed',
  },
]

#footer

Unified footer config — the old top-level footer and site.footer are now one block.

footer: {
  message?:   string,
  copyright?: true | string | CopyrightConfig,
  columns?:   FooterColumn[],
  tagline?:   string,
  brandMark?: string,
  socials?:   true | SocialLink[],
}

#Smart copyright

copyright: true produces Copyright © <currentYear> <title>. using the top-level title and the year at build time. Pass a string to override verbatim, or a CopyrightConfig for structured company / DBA / year-range output.

#CopyrightConfig

interface CopyrightConfig {
  company?: string
  dba?: string
  year?: number | { from: number }
}

footer: {
  copyright: { company: 'Acme Inc.', dba: 'Acme', year: { from: 2021 } },
  // → "Copyright © 2021–2026 Acme Inc. (Acme)"
}

#FooterColumn

interface FooterColumn {
  heading: string
  links: Array<{ text: string; href: string }>
}

Security note — every href in footer.*, sidebar.*, and topbar.* is validated through a safe-URL helper that rejects javascript:, data:, vbscript:, and file: schemes. Relative paths, fragment anchors, http://, https://, mailto:, and tel: are allowed.

#editLink and reportLink

Per-page chrome — the "Edit on GitHub" and "Report an issue" links rendered under every doc page. Flattened to the top level to match the industry pattern (VitePress, Nextra). Set either to false to disable that action site-wide.

editLink?:   false | EditLinkConfig,
reportLink?: false | ReportLinkConfig,

#EditLinkConfig

interface EditLinkConfig {
  repo?: string
  branch?: string
  directory?: string
  label?: string
  url?: (page: ResolvedPage) => string
  onResolve?: (page: ResolvedPage) => void
}

editLink: {
  repo:      'acme/docs',
  branch:    'main',
  directory: 'docs',
  onResolve: (page) => track('edit-link.resolved', { path: page.path }),
},

#ReportLinkConfig

Identical shape to EditLinkConfig. repo may be either "org/repo" shorthand or a full issues URL; default label is "Report an issue".

reportLink: { repo: 'acme/docs' },
// or disable site-wide:
reportLink: false,

#feedback

Controls the "Was this page helpful?" yes/no widget rendered at the bottom of every doc page. Off by default.

feedback?: boolean | { question?: string }

// enable with the default question
feedback: true,
// enable with a custom question
feedback: { question: 'Did this help?' },

#home

Home page composition — a special-cased hero header plus an ordered array of blocks. Array order is render order, and any block type may appear more than once (multiple splits, multiple tab bands, etc.). Omit blocks to get the framework default deck: an auto-generated features grid plus a workspace showcase derived from the repo.

home: {
  hero?:   HomeHeroConfig,
  blocks?: HomeBlock[],
}

blocks: [] renders nothing below the hero. Omitting blocks renders the default deck — a features grid plus the workspace showcase. To keep that deck and add to it, write it out and append:

home: {
  blocks: [{ type: 'features' }, { type: 'showcase' }, { type: 'cta', title: 'Ready?' }],
}

#HomeBlock

A discriminated union on type. Every variant carries its own flat fields — there are no nested section configs.

home: {
  hero: { tagline: 'Ship faster.' },
  blocks: [
    { type: 'proof', lead: 'used by', names: ['acme', 'globex'] },
    { type: 'features', items: [/* ... */] },
    { type: 'split', title: 'One config', visual: { type: 'code', code: '// ...' } },
    { type: 'split', title: 'See it live', reverse: true, visual: { type: 'image', src: '/demo.png' } },
    { type: 'tabs', items: [{ label: 'Sync', visual: { type: 'code', code: '// ...' } }] },
    { type: 'cta', title: 'Ready to ship?' },
  ],
}

Every copy-bearing block shares the same flat heading trio — label (small uppercase kicker), title, and body.

#HomeHeroConfig

interface HomeHeroConfig {
  label?: string
  tagline?: string
  actions?: ButtonConfig[]
  demo?: false | HomeVisual
  background?: string | HomeHeroBackground
}

Omit demo entirely to keep the framework's built-in terminal animation.

#HomeHeroBackground

background: '/hero.jpg'
// shorthand for:
background: { src: '/hero.jpg' }
// lock foreground contrast to dark artwork:
background: { src: '/hero.jpg', mode: 'dark' }
// optional responsive crops:
background: {
  src: '/hero.jpg',
  sources: { tablet: '/hero-tablet.jpg', mobile: '/hero-mobile.jpg' },
}
// switch artwork with the active site variant:
background: {
  dark: {
    src: '/hero-dark.jpg',
    sources: { tablet: '/hero-dark-tablet.jpg', mobile: '/hero-dark-mobile.jpg' },
  },
  light: {
    src: '/hero-light.jpg',
    sources: { tablet: '/hero-light-tablet.jpg', mobile: '/hero-light-mobile.jpg' },
  },
}

Set mode for artwork designed for one color mode. Omit it for artwork that adapts to both site variants. Use { dark, light } to switch the image and foreground contrast with the active site variant. Each variant accepts the same src, sources, position, size, and repeat fields.

#HomeVisual

One union backs every visual on the page — hero.demo, split.visual, and each tab's visual. It is discriminated on type, which is required on all three variants.

type HomeVisual = HomeVisualCode | HomeVisualImage | HomeVisualTerminal

interface HomeVisualCode {
  type: 'code'
  code: string
  language?: string
}

interface HomeVisualImage {
  type: 'image'
  src: string
  alt?: string
  width?: number | string
  height?: number | string
}

interface HomeVisualTerminal {
  type: 'terminal'
  command: string
  lines: { kind: 'ok' | 'info' | 'cmt' | 'err'; text: string }[]
  windowTitle?: string
}

Terminal lines[].kind picks the prefix glyph: ok → ✓, info → ▸, cmt → ↻, err → ✗.

#HomeProofBlock

{
  type: 'proof',
  lead?: string,
  names?: (string | ProofLogo)[],
}

#ProofLogo

An entry may be a bare string or a logo object. Mix both in one strip.

{
  type: 'proof',
  lead: 'used by',
  names: [
    'Acme',
    { src: '/logos/beta.svg', alt: 'Beta' },
    { src: { dark: '/logos/gamma-dark.svg', light: '/logos/gamma-light.svg' }, alt: 'Gamma' },
    { src: '/logos/gamma.svg', alt: 'Gamma', href: 'https://gamma.dev', height: 24, mono: true },
  ],
}

mono reads only the asset's alpha channel, so trim the artwork's viewBox to the mark itself — surrounding padding becomes part of the silhouette.

Use { dark, light } when a full-colour mark needs separate artwork for contrast. A string keeps the same asset in both variants.

#HomeFeaturesBlock

{
  type: 'features',
  label?: string,
  title?: string,
  body?: string,
  items?: Feature[],
  columns?: 1 | 2 | 3 | 4,
  truncate?: TruncateConfig,
}

Each Feature:

interface Feature {
  title: string
  description: string
  link?: string
  icon?: IconConfig
}

#HomeShowcaseBlock

Generalized card grid. The default source is the combined apps + packages + workspaces list; point it at page paths for an arbitrary card set.

{
  type: 'showcase',
  label?: string,
  title?: string,
  body?: string,
  source?: 'workspaces' | string[],
  columns?: 1 | 2 | 3 | 4,
  truncate?: TruncateConfig,
}

{ type: 'showcase', columns: 3, source: ['/products/cli', '/products/api', '/products/web'] }

A source path that matches no page or workspace is skipped with a sync warning; if none of them resolve, the band renders nothing rather than falling back to the workspace deck.

#HomeSplitBlock

Two-column show-and-tell band — copy on one side, a HomeVisual on the other. Repeatable in any position.

{
  type: 'split',
  title: string,
  label?: string,
  body?: string,
  bullets?: string[],
  cta?: ButtonConfig,
  visual?: HomeVisual,
  reverse?: boolean,
}

The narrow single-column stack always leads with the copy, so a reversed band never pushes its visual above the headline.

#HomeTabsBlock

A strip of selectable tabs driving one panel. Clicking a tab swaps the panel's copy and visual; the first tab is selected on load. Keyboard navigation (arrow keys, Home/End) and the tab/tabpanel ARIA wiring are built in.

{
  type: 'tabs',
  items: HomeTabItem[],
  label?: string,
  title?: string,
  body?: string,
  orientation?: 'vertical' | 'horizontal',
  reverse?: boolean,
}

Each HomeTabItem:

interface HomeTabItem {
  label: string
  icon?: IconConfig
  title?: string
  body?: string
  bullets?: string[]
  cta?: ButtonConfig
  visual?: HomeVisual
}

{
  type: 'tabs',
  label: 'Capabilities',
  title: 'Pick a thread, follow it through.',
  orientation: 'vertical',
  items: [
    {
      label: 'Sync engine',
      icon: { id: 'pixelarticons:reload', color: 'green' },
      title: 'Your markdown, left where it is',
      body: 'Ciderpress reads your repo in place — no copying, no restructuring.',
      bullets: ['Glob discovery', 'Watch mode on every save'],
      visual: {
        type: 'terminal',
        command: 'ciderpress dev',
        lines: [{ kind: 'ok', text: 'synced 128 pages' }],
      },
    },
    {
      label: 'OpenAPI',
      title: 'Specs become reference pages',
      visual: { type: 'code', language: 'ts', code: "openapi: { spec: 'openapi.yaml' }" },
    },
  ],
}

Narrow breakpoints collapse both orientations to a single stacked column.

#HomeCtaBlock

{
  type: 'cta',
  label?: string,
  title?: string,
  body?: string,
  actions?: ButtonConfig[],
}

#TruncateConfig

Shared by features and showcase blocks. Values are maximum visible lines before CSS line-clamp clips with an ellipsis.

interface TruncateConfig {
  title?: number
  description?: number
}

#discover

Top-level cross-cutting discovery options. Only field is ignore — global glob patterns excluded from every page's auto-discovery.

discover?: {
  ignore?: string[],
}

discover: {
  ignore: ['**/draft-*.md', '**/internal/**', '**/_*.md'],
}

Per-page discover.ignore is appended to this list — globals always apply.

#templates

Directory or directories holding custom document templates used by ciderpress draft. Each is a .md/.mdx file with label/hint frontmatter; the filename is the template type. Paths are relative to the repo root.

templates?: string | string[]

templates: ['docs/.templates', 'shared/templates'],

A custom template whose filename matches a built-in (e.g. guide.md) overrides it. .mdx templates scaffold to .mdx files. Templates are validated by ciderpress templates check and as part of check/build. See Templates for the authoring format and the SDK.

#devServer

Dev-server configuration — controls how ciderpress dev binds and how the dev URL is presented in the terminal and browser auto-open. All fields are optional.

devServer?: {
  url?:  string,
  port?: number,
  host?: string,
  open?: boolean,
}

CLI precedence: --port / --host / --url > devServer.{port,host,url} > built-in defaults.

#Example — behind portless.sh

devServer: {
  url: 'https://docs.acme.localhost',
  open: true,
}

The dev server still binds localhost:6174; portless reverse-proxies the HTTPS hostname to that port. See the portless guide for setup.

#Example — exposing to LAN / Docker

devServer: {
  host: '0.0.0.0',
  port: 6174,
}

#Shared primitives

Types reused across multiple top-level keys. Same shape, same meaning, everywhere.

#IconConfig

type IconConfig = IconId | { id: IconId; color?: IconColor } | { src: string; alt?: string }

Uniform across every position — brand.icon, Page.icon, Workspace.icon, WorkspaceGroup.icon, Feature.icon, ButtonConfig.icon. Either a plain Iconify identifier ('pixelarticons:book-open'), an Iconify id with explicit color, or an arbitrary image source.

#TitleConfig

type TitleConfig =
  | string
  | {
      from: 'auto' | 'filename' | 'heading' | 'frontmatter'
      transform?: (text: string, slug: string) => string
    }

Uniform across every title field that supports derivation — Page.title and Workspace.title. Plain string for static titles, or a derivation rule for auto-discovered children. The transform hook receives the derived title and the filename slug. (WorkspaceGroup.title is a plain string only.)

#ButtonConfig

interface ButtonConfig {
  text: string
  href: string
  variant?: 'primary' | 'secondary' | 'ghost'
  shape?: 'square' | 'rounded' | 'circle'
  icon?: IconConfig
}

Unified button vocabulary. Replaces the three old button shapes (HeroAction.theme, SidebarLink.style, and the third unnamed variant). Used by home.hero.actions, the actions / cta fields on home.blocks[], topbar.cta, sidebar.top / sidebar.bottom / sidebar.promo.cta.

#ImageSource

type ImageSource =
  | string
  | {
      src: string
      alt?: string
      type?: string
      width?: number | string
      height?: number | string
    }

Universal image source — string path or a fully described image object. Used by brand.favicon, brand.banner (string form), Workspace.badge, and anywhere else an image is rendered.

#SortStrategy

type SortStrategy =
  'default' | 'alpha' | 'filename' | 'none' | ((a: ResolvedPage, b: ResolvedPage) => number)

Used by Page.discover.sort and Workspace.discover.sort.

'default' is the implicit fallback when discover.sort is omitted.

#Frontmatter

Page.defaults (and Workspace.defaults) take a Frontmatter value. It carries the page metadata fields Rspress understands plus Ciderpress's nested seo overrides.

{
  title: 'API Reference',
  defaults: {
    aside:    'left',
    editLink: false,
    pageType: 'doc',
  },
}

Per-file YAML frontmatter wins on conflict with defaults. See Frontmatter Fields for the full field schema.

#References

• Frontmatter — per-page metadata schema
• Icon Colors — color values accepted by IconConfig
• Content — how pages map your existing markdown into the site tree
• Workspaces — when to use apps, packages, or workspaces
• Themes — built-in theme names and custom theme definitions

#Resources

• c12 — the config loader used under the hood
• Iconify — icon identifier search