Configuration describes the public system around your Markdown. Keep it small, add one concern at a time, and use the config reference when you need exact fields.
Start from the smallest valid file
import { defineConfig } from 'tidypress'
export default defineConfig({
name: 'Acme Engineering',
description: 'Product notes, guides, and technical decisions.',
siteUrl: 'https://engineering.acme.com',
}) siteUrl is strongly recommended for production. TidyPress omits placeholder
hosts from canonical production metadata and warns during builds.
Define the content graph
collections: {
docs: {
enabled: true,
basePath: '/docs',
label: 'Docs',
},
writing: {
enabled: true,
basePath: '/writing',
kind: 'writing',
label: 'Writing',
},
projects: {
enabled: true,
basePath: '/projects',
kind: 'projects',
label: 'Projects',
},
pages: {
enabled: true,
kind: 'page',
label: 'Pages',
},
} The collection key maps to src/content/<key>/. basePath controls the URL.
kind selects built-in behavior. The reserved docs key already has docs
behavior and must not set a kind.
Build navigation around user goals
navigation: {
header: [
{ type: 'link', label: 'Docs', href: '/docs/getting-started' },
{ type: 'link', label: 'Writing', href: '/writing' },
{ type: 'search', position: 'end' },
{ type: 'theme-toggle', position: 'end' },
],
sidebar: [
{
type: 'group',
label: 'Start here',
expanded: true,
children: [
{ type: 'page', page: 'getting-started', label: 'Quickstart' },
{ type: 'page', page: 'concepts', label: 'Core concepts' },
],
},
{
type: 'group',
label: 'Reference',
children: [{ type: 'autogenerated', directory: 'reference' }],
},
],
} Header nodes support links, dropdowns, search, theme toggle, and project
components. Sidebar nodes support pages, links, nested groups, separators,
project components, and autogenerated directories. The older flat nav and
docs.sidebar forms remain compatibility shorthands.
Add identity and ownership
branding: {
icon: '/mark.svg',
favicon: '/favicon.svg',
},
repository: {
url: 'https://github.com/acme/product',
branch: 'main',
editPath: 'site/src/content',
},
footer: {
copyright: '© {year} Acme',
showCredit: true,
menus: [
{
label: 'Explore',
links: [
{ label: 'Docs', href: '/docs' },
{ label: 'Writing', href: '/writing' },
],
},
],
links: [
{ label: 'GitHub', href: 'https://github.com/acme/product', icon: 'github' },
{ label: 'RSS', href: '/writing/rss.xml', icon: 'rss' },
],
} Files under public/ are served from /. Repository settings enable edit links
on docs pages. Footer menus adds optional labeled link groups above the compact
footer line. main.start and main.end remain available for a small utility
band; the deprecated aside field maps to main.end. Set showCredit: false
only when you intentionally remove the default product credit.
Strict navigation budgets default to three core desktop items and two mobile items. Change those limits explicitly when the design has room:
navPolicy: {
mode: 'strict',
maxVisibleDesktop: 4,
maxVisibleMobile: 2,
} Choose homepage emphasis
home: {
order: ['projects', 'writing', 'docs'],
previewLimit: 4,
collections: {
projects: { layout: 'card', showDescription: true },
writing: { layout: 'list', showDate: true },
},
} previewLimit applies to every homepage section. The baseline homepage renders
collection previews. A project can replace the
public Home component for a full product landing page while continuing to use
the same resolved home data.
Validate before adding more
npx tidypress doctor
npx tidypress build Config validation rejects unknown capability names, invalid enums, unsafe parent paths, duplicate pages, and unsupported reserved-collection combinations. A successful build remains the final integration check because project Astro, Markdown, and plugin modules are compiled there.