CLI reference — tidypress

This is the compact reference. Use the focused guides when you need context.

CLI

Global flags:

tidypress --help
tidypress --version
tidypress --verbose <command>

No command defaults to tidypress dev.

Core commands:

tidypress init [--preset <name>]
tidypress init [--starter <name>]
tidypress dev [--port <n>]
tidypress build [--output <dir>]
tidypress preview [--port <n>]
tidypress clean
tidypress deploy [target]
tidypress deploy [target] --with-ci
tidypress context [output]

Starter presets (default is an alias for lab):

Preset	Seeds
`lab`	writing + projects (default `init`)
`persona`	hero, projects, writing, about page
`blog`	writing only
`docs-writing`	docs + writing
`custom`	docs, writing, and a `playbooks` content collection

Maintenance and scaffold commands:

tidypress migrate-sections
tidypress doctor
tidypress release-check
tidypress add-version <label> [--set-latest]
tidypress domain setup [domain] --platform <platform>
tidypress import <medium|devto|substack|ghost> <url-or-path>
tidypress convert <file.ipynb> [--output <file.mdx>]      # Python wrapper
tidypress extract-docs <path> [--lang py|ts|go]           # Python wrapper

devto fetches public article markdown from the Dev.to API. Other import providers write a review scaffold.

domain, editor, export, and ai are scaffold or planning surfaces unless explicitly documented by their command output. The Python-only commands are available through the Python package entrypoint.

Experimental commands:

tidypress editor --enable-experimental-editor
tidypress export <pdf|epub|archive> [source] --enable-experimental-export
tidypress ai <suggest|translate|changelog> [args...] --enable-experimental-ai

Experimental commands require config and CLI opt-ins. See Advanced configuration.

Config fields

interface TidyPressConfig {
  name: string
  description?: string
  hero?: TidyPressHero
  home?: TidyPressHome // order, previewLimit, collections display, preset: lab | blog | docs-writing | persona
  nav?: NavItem[]
  footer?: FooterItem[]
  pages?: PageEntry[]
  collections?: TidyPressCollections
  siteUrl?: string
  repository?: TidyPressRepository
  search?: TidyPressSearch
  branding?: TidyPressBranding
  typography?: TidyPressTypography
  theme?: TidyPressTheme
  capabilities?: TidyPressCapabilities
  experimental?: TidyPressExperimental
  versions?: TidyPressVersion[]
  i18n?: TidyPressI18n
  analytics?: TidyPressAnalytics
  docs?: TidyPressDocs
  writing?: TidyPressWriting
  dateLocale?: string
  dateFormat?: Intl.DateTimeFormatOptions
  navPolicy?: TidyPressNavPolicy
  extensions?: TidyPressRenderingExtensions
  sections?: unknown // legacy shim
}

Only name is required.

Typography scale

type TidyPressTypographyScale = 'small' | 'medium' | 'large'

medium is the default when typography is omitted. default and extra are accepted aliases: default → medium, extra → large.

Collection kinds

type TidyPressCollectionKind = 'content' | 'writing' | 'projects' | 'page'

collections.docs is the main docs collection. It has no kind or render.

interface TidyPressHero {
  enabled?: boolean
  role?: string
  pronunciation?: string
  lead?: string
  image?: string
  links?: Array<{ label: string; href: string; external?: boolean }>
}

Hero renders only when hero.enabled === true.

Capability names

type TidyPressCapabilityName =
  | 'docs'
  | 'writing'
  | 'pages'
  | 'editor'
  | 'export'
  | 'ai'
  | 'theming'
  | 'themingCustom'

Theme token names

type TidyPressThemeTokenName =
  | 'bg'
  | 'fg'
  | 'muted'
  | 'border'
  | 'surface'
  | 'codeBg'
  | 'codeFg'

Frontmatter

Docs:

---
title: Getting started
description: First steps.
order: 1
form: doc
paging: bottom
tags: [setup, docs]
search: true
published: true
scheduled: 2026-06-01T09:00:00Z
---

Writing:

---
title: Release notes
date: "2026-05-22"
description: Notes from the latest release.
author: Raph
featured: true
ogImage: /images/release.png
tags: [release]
search: true
published: true
scheduled: 2026-06-01T09:00:00Z
---

Projects:

---
title: Sample project
description: One line about the work.
status: active
featured: true
url: https://example.com
linkOnly: true
repo: https://github.com/you/project
tags: [oss]
published: true
---

Pages:

---
title: About
description: About this project.
search: true
---

Docs forms

Form	Layout
`doc`	default docs page with sidebar, TOC, and chapter navigation
`manual`	procedural page chrome and step styling

Docs chapter navigation defaults to both top and bottom. Use paging: false, 'none', 'top', or 'bottom' globally under docs or per page frontmatter.

Components

Component	Purpose
`<Callout type?>`	note, warning, or tip
`<Tooltip tip>`	inline hover text
`<FileTree>`	collapsible file tree
`<Tabs labels>`	tabbed examples
`<Tab>`	one tab panel
`<Mermaid code>`	Mermaid diagram
`<Image src alt ...>`	optimized or public image with caption
`<Steps>`	numbered procedural wrapper
`<Step title?>`	single procedural step

See Components.

Build output

docs/build/
├── index.html
├── docs/
├── writing/
├── assets/
├── pagefind/
└── sitemap-index.xml

Search is generated by Pagefind during tidypress build.

Deploy targets

tidypress deploy                   # print build/ path
tidypress deploy ./public-docs     # copy build/ locally
tidypress deploy file:///tmp/site  # copy build/ locally
tidypress deploy vercel            # calls vercel CLI
tidypress deploy netlify           # calls netlify CLI
tidypress deploy surge             # calls surge CLI
tidypress deploy github-pages      # calls npx gh-pages
tidypress deploy cloudflare        # calls wrangler
tidypress deploy docker            # writes Dockerfile + docker-compose.yml
tidypress deploy static            # report build/ path for artifact-only deploy
tidypress deploy s3://bucket/path  # calls aws s3 sync
tidypress deploy ssh://host/path   # calls rsync
tidypress deploy gs://bucket/path  # prints external upload instructions

Provider targets require their local CLIs or tools. Targets that only report the build/ path are artifact flows, not full hosted deploys.

Python wrapper

pip install tidypress

The Python package delegates site commands to the Node.js CLI. Node.js 22.12 or newer is still required for rendering.

Python-native helpers include notebook conversion and source extraction.

See Python wrapper.