tidypress
On this page

Getting started

Scaffold a git-native public site, run it locally, and ship static output.

TidyPress treats a public site as files in git: a config file, typed collections of markdown, a build step, static output you host yourself. Starter collections include writing, projects, and docs — sidebar-ordered guides at /docs/…. The default lab preset foregrounds writing and work on the home page and leaves the docs collection disabled until you enable it.

init scaffolds site/ at the project root — the publish root for config, content, and build/. The docs collection lives at src/content/docs/ and routes at /docs/… with sidebar layout and ordering.

Install

npm install tidypress
pnpm add tidypress
pip install tidypress

Note

Node.js 22.12 or newer is required for rendering. The Python package can run Python-native helpers, but site builds still use the Node.js CLI and Astro engine.

Start a project

From the root of your project:

npx tidypress init --site-url https://yoursite.example
npx tidypress dev

Open http://localhost:4321.

init creates a site/ folder. The lab preset seeds writing and projects; the docs/ subtree is present but disabled in config until you turn the collection on.

site/
├── tidypress.config.ts
├── public/
│   └── images/
└── src/
    └── content/
        ├── writing/    # dated posts (RSS, tags, archive)
        │   └── hello.md
        ├── projects/   # cards + optional pages (lab preset)
        ├── docs/       # docs collection — sidebar-ordered guides at /docs/…
        │   └── getting-started.md
        └── pages/      # root routes (e.g. /about)

The lab preset is the default: writing and projects on the home page, docs collection disabled in config. Replace the seeded files with your own material.

Other presets:

PresetShape
lab (default)writing + projects
personahero bar, projects, writing, about page
blogwriting only
docs-writingdocs + writing
body-of-workworks, projects, writing, reference, process
body-of-work-docsbody-of-work + enabled docs
customdocs + writing + a playbooks content collection

default is an alias for lab.

npx tidypress init --preset blog --site-url https://yoursite.example
npx tidypress init --preset persona --site-url https://yoursite.example
npx tidypress init --preset body-of-work --site-url https://yoursite.example
npx tidypress init --preset docs-writing --site-url https://yoursite.example
npx tidypress init --preset custom --site-url https://yoursite.example

Writing

Dated posts live in the writing collection:

---
title: Release notes
date: "2026-05-22"
description: Notes from the latest release.
---
 
What changed and why.

Path: site/src/content/writing/ under the publish root.

Project cards: site/src/content/projects/ on presets that include projects — lab, persona, body-of-work, and others.

Docs collection

The docs collection is sidebar-ordered markdown at /docs/…—tutorials, how-tos, reference. Enable it with preset docs-writing or body-of-work-docs, or set collections.docs.enabled: true in config.

---
title: Install
description: Install and configure the project.
order: 1
---
 
## Requirements
 
Write the page in markdown.

Path: site/src/content/docs/ — routes under /docs/…, sidebar order via order in frontmatter.

Build and preview

npx tidypress build
npx tidypress preview

Build output is written to:

site/build/

Search is generated during tidypress build, so the search modal is available in preview, not in the dev server.

Deploy the build/ folder with your static host, CI job, or tidypress deploy.

Generated files — do not edit

TidyPress keeps your markdown in place. It writes two kinds of generated output:

your project
└── site/
    ├── tidypress.config.ts
    ├── src/content/
    └── build/
 
~/.cache/tidypress/<key>/
  • build/ — HTML, assets, Pagefind search, llms.txt, and sitemap when siteUrl is production-ready. Upload only this folder. Skip llms.txt with tidypress build --no-llms-txt or capabilities.disable: ['llmsTxt'].
  • Cache — plugin codegen and Astro cache under ~/.cache/tidypress/. Safe to delete; recreated on the next dev or build.

If a local build behaves strangely after an engine upgrade, run:

npx tidypress clean
npx tidypress build

Static assets

Put files that should be served as-is in site/public/:

site/public/
├── images/diagram.png
├── downloads/spec.pdf
├── robots.txt
└── favicon.svg

Files under public/ are served from the site root. site/public/images/diagram.png becomes /images/diagram.png.

![Architecture diagram](/images/diagram.png)
[Download the spec](/downloads/spec.pdf)

downloads/ is only an example folder. Any file under public/ is served from the site root.

Next steps