tidypress
On this page

Getting started

Create a TidyPress project, run it locally, and build static output.

Create a docs/ folder, run the local server, write one page, then build static output.

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
npx tidypress dev

Open http://localhost:4321.

init creates a docs/ folder:

docs/
├── tidypress.config.ts
├── public/
│   └── images/
└── src/
    └── content/
        ├── docs/
        │   └── getting-started.md
        ├── writing/
        │   └── hello.md
        └── pages/

init defaults to the lab preset: writing and projects on the home page, docs disabled. Replace the seeded markdown with your own content.

Other presets:

PresetShape
lab (default)writing + projects
personahero bar, projects, writing, about page
blogwriting only (docs and pages off)
docs-writingdocs + writing
customdocs + writing + a playbooks content collection

default is an alias for lab.

npx tidypress init --preset blog
npx tidypress init --preset persona
npx tidypress init --preset docs-writing
npx tidypress init --preset custom

Write one docs page

Put documentation pages in docs/src/content/docs/:

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

Put dated posts in docs/src/content/writing/:

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

Build and preview

npx tidypress build
npx tidypress preview

Build output is written to:

docs/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
└── docs/
    ├── tidypress.config.ts      # your config
    ├── src/content/            # your markdown
    └── build/                  # static site — deploy this (gitignored)
 
~/.cache/tidypress/<key>/        # local compiler cache — not deployed
  • build/ — HTML, assets, Pagefind search, sitemap. Upload only this folder to production.
  • Cache — plugin codegen and Astro cache. 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 docs/public/:

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

Use absolute paths in markdown:

![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