tidypress

A publishing framework for Git-native authorship.

Website · Docs · npm · PyPI · Issues

Markdown in git. tidypress init, dev, build - static output you own. Writing, projects, and a docs collection in one publish root.

TidyPress gives an engineer's repo a public shape: writing, projects, docs when useful, references, and the static build artifact that actually shipped.

Install

Node.js 22.12 or newer is required for rendering.

npm install tidypress
# or
pnpm add tidypress

Python users can optionally install the companion package for notebook conversion and source extraction:

pip install tidypress

The Python package is not a second installer or renderer. pip install tidypress alone supports its Python-native helpers; site commands require the Node.js CLI installed separately with npm or pnpm.

Install size

tidypress ships Astro, Vite, Pagefind, and related tooling in one package so init and build work without assembling a stack. The install is larger than a markdown linter; that is the tradeoff for a reliable first site.

A thinner install (peer dependencies, split CLI vs engine packages) is possible later and would trade first-run simplicity for a smaller download. The current core optimizes DX over tarball size.

Quickstart

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

Open http://localhost:4321.

Production build:

npx tidypress build
npx tidypress preview

Output:

site/build/

File shape

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

Docs are stable instructions. Writing is dated context. Pages map to root routes.

Why

Your repo already contains the material. TidyPress supplies the repeatable site shape:

• writing and projects on the home page
• docs collection for sidebar-ordered guides at /docs/… (enable per preset or config)
• markdown and MDX in git, one CLI, static output
• Pagefind search, RSS for writing, archive and tags
• deploy anywhere you host static files

Examples

Run examples from the repo root after pnpm install:

pnpm --filter @tidypress/example-lab build
pnpm --filter @tidypress/example-blog build
pnpm --filter @tidypress/example-persona build
pnpm --filter @tidypress/example-minimal build
pnpm --filter @tidypress/example-custom-collections build
pnpm --filter @tidypress/example-i18n-versioned build

See examples/.

Packages

Package	Role
tidypress	CLI: init, dev, build, preview, deploy (build/ includes llms.txt)
@tidypress/engine	Astro rendering runtime
@tidypress/config	config schema, defaults, normalization
wrappers/python	Python entrypoint and Python-native helpers

End users install tidypress.

Agent skills (Cursor, Claude Code, Codex)

TidyPress ships Agent Skills so coding agents know the CLI, config, and monorepo conventions.

npx tidypress skills install

Skill installation is explicit. Package installation and ordinary CLI commands do not write to agent directories, edit environment variables, or change agent settings. The compatibility alias is npx tidypress --install-skills.

See skills/README.md.

Contributors

See CONTRIBUTING.md for setup, pull requests, and optional AI-assisted workflow. CODE_OF_CONDUCT.md · SECURITY.md

pnpm install
pnpm test
pnpm build

Release notes live in RELEASING.md.

Backlog (contributors)

Explicit backlog items (P3 stretch, import scaffolds) are listed in RELEASING.md. They are not regressions.