tidypress
DocsWritingGitHub
On this page

Config reference

Top-level fields accepted by defineConfig in tidypress.config.ts.

 import { defineConfig } from 'tidypress'
 
export default defineConfig({ name: 'my-site' })

Only name is required. defineConfig preserves type inference; normalization adds defaults and rejects invalid capability keys, unsafe project paths, and unsupported enum values.

Identity and metadata

name string required
Site name used in navigation, metadata, and default footer copy.
description string
Default metadata and homepage description.
siteUrl string URL
Production origin for canonical URLs, Open Graph, RSS, and sitemap. Placeholder hosts are omitted from production metadata.
branding object
icon and favicon public asset paths.
repository object
url, branch, and editPath for edit-page links.

Content model

collections Record<string, TidyPressCollection>

Collection key to { enabled, basePath, kind, label, display, render }. Built-in kinds are content, writing, page, and projects. The docs key is reserved for product documentation and does not accept kind or collection-level render.

writing object

Writing index description and entry display settings. entry.paging accepts bottom (the default), top, none, or a boolean; entry.showTags controls entry-page tags.

docs object
Compact legacy sidebar groups and global docs paging placement.
pages Array<string | { slug, navLabel? }>
Root pages to expose and optionally add to navigation.
home object
Collection order, preview limits, per-collection display, and lab | blog | docs-writing | persona display preset.
hero object
Opt-in baseline hero with enabled, role, pronunciation, lead, image, and links.
navigation.header TidyPressNavigationNode[]

Recursive links, dropdowns, search, theme toggle, and project component nodes. Nodes can target start, center, or end.

navigation.sidebar TidyPressSidebarNode[]

Recursive page, link, group, separator, component, and autogenerated-directory nodes. Groups may link their heading to an overview with page; setting expanded to a boolean makes a group collapsible and selects its initial state.

nav NavItem[]
Legacy flat header shorthand.
navbar object
position, hideOnScroll, width, and optional background.
footer array | object
Optional menus link groups, main-band start/end slots, copyright, showCredit, credit overrides, and compact-line icon/text links. Deprecated aside maps to main.end.
navPolicy object
strict | relaxed validation plus maxVisibleDesktop and maxVisibleMobile visibility budgets.

Presentation

typography object
Text scale: small, medium, or large; default and extra are accepted aliases.
theme object
Mode, baseline preset, semantic token surfaces, code preset, fonts, CSS variables, and project CSS.
ui object
Named component overrides, stable slot contributions, and registered page layouts.
mdx.components Record<string, string>
MDX component name to project-local Astro path.
mdx.imageZoom boolean

Default: true

Open Markdown and MDX content images in the built-in focused viewer. Individual MDX images can opt out.
styles string[]
Project-relative CSS or public/external stylesheet URLs.
scripts Array<string | TidyPressScript>
Project modules or linked scripts with module/classic, async, and defer policy.
markdown object
Project-local/package remarkPlugins and rehypePlugins.
plugins string[]
Project-local modules created with definePlugin.

Search, analytics, and publication variants

search object
Initial shortcuts, excluded paths, and an optional project-local browser search provider.
analytics object
none, plausible, fathom, or umami plus explicit endpoint and site ID.
versions Array<{ label, path }>
Folder-based docs versions. Omit for a single maintained line.
i18n object
Default locale, locale list, and per-locale UI string overrides. Omit for a single-language site.
dateLocale string
Locale passed to date formatting.
dateFormat Intl.DateTimeFormatOptions
Date display options; formatting uses UTC.

Capabilities and extensions

capabilities object
Explicit enable and disable lists. See the capability registry for exact keys.
experimental object
Legacy/config source for editor, export, and ai; commands still require explicit enable flags.
extensions.docForms record
Register custom docs form labels, presentation modules, and view directories.
sections object deprecated
Compatibility input migrated to collections during normalization.

Project path rule

Project code paths begin with ./ and resolve from the publish root. Parent traversal is rejected. Linked styles and scripts may use public paths or absolute URLs where their field supports them.