Python companion

# Python companion

Use the optional Python package only for notebook conversion, source extraction, or Node CLI delegation.

The Python package is an optional companion for Python environments. It provides
native notebook conversion and source extraction; it is not another renderer or
a replacement installer for the npm package.

Rendering still uses the Node.js CLI and Astro engine. Node.js 22.12 or newer is required for `init`, `dev`, `build`, `preview`, and `deploy`.

## When to install it

Do not install Python to create or publish a normal TidyPress site. Use the npm
package and Node.js workflow from the [Quickstart](./getting-started).

Install the companion only when you need its two Python-native utilities:
notebook conversion or source-comment extraction.

```bash
pip install tidypress
```

That installation is sufficient for `convert` and `extract-docs`. Install the
Node CLI separately when you also want site commands:

```bash
npm install tidypress
# or: npm install --global tidypress
```

For site commands, the wrapper resolves the Node CLI in this order:

1. `TIDYPRESS_CLI_JS`
2. a local monorepo or project `node_modules/tidypress`
3. `tidypress` on `PATH`

It does not download or invoke packages through `npx` by default.
`TIDYPRESS_USE_NPX=1` is an explicit diagnostic/CI escape hatch, not a required
installation step.

## Site commands

These commands are delegated to the Node CLI — the same surface as `npx tidypress`:

```bash
tidypress init [--preset <name>]
tidypress dev
tidypress build
tidypress preview
tidypress clean
tidypress deploy
# build/llms.txt on every build
tidypress import devto --username <username/slug-or-article-url>
tidypress doctor
tidypress migrate-sections
tidypress add-version <label>
tidypress domain setup [domain] --platform <platform>
tidypress release-check
```

`import devto` fetches real markdown. Other import providers write review
scaffolds. Experimental Node commands (`editor`, `export`, `ai`) can be
forwarded, but intentionally stop with `EXPERIMENTAL_NOT_IMPLEMENTED` even
after opt-in. They are reserved command contracts, not working features.

## Notebook conversion

`convert` is Python-native:

```bash
tidypress convert analysis.ipynb
```

By default, output goes to the **docs collection**:

```txt
site/src/content/docs/analysis.mdx
```

Point at **writing** when the notebook is a public essay, not a manual page:

```bash
tidypress convert analysis.ipynb --output site/src/content/writing/analysis.mdx
```

Or choose any path under the publish root:

```bash
tidypress convert analysis.ipynb --output site/src/content/docs/reports/analysis.mdx
```

The converter preserves markdown cells, code cells, text outputs, and PNG image outputs.

## Source extraction

`extract-docs` writes a simple API notes file from Python, TypeScript, or Go comments:

```bash
tidypress extract-docs src/ --lang py
tidypress extract-docs src/ --lang ts
tidypress extract-docs src/ --lang go
```

Default output:

```txt
site/src/content/docs/api/<lang>.md
```

This is a convenience helper for small projects. For large API references, keep using the dedicated tooling for that ecosystem.

## Agents and markdown

Agents that edit files in git use the same commands as you do: add markdown under `src/content/`, run `tidypress build`, deploy `build/`. Point the model at `build/llms.txt` or the live `/llms.txt` URL for full published content. Details: [The repository is the editing protocol](/writing/repository-is-the-editing-protocol).

## Help and init presets

```bash
tidypress --help
tidypress init --help  # Python wrapper only
```

The Python entrypoint lists the same init presets as the Node CLI: `lab`, `blog`,
`persona`, `docs-writing`, `body-of-work`, `body-of-work-docs`, and `custom`.
`default` is an alias for `lab`. The Node CLI itself currently exposes only
root `tidypress --help`; command-specific help is not implemented there.

## Streaming build and deploy

`tidypress build` and `tidypress deploy` stream Node CLI output live through an async subprocess. Add `--sync` to use the legacy blocking runner (for scripts that capture output).

## YAML bridge

`tidypress.yaml` is validated against the shared JSON Schema from `@tidypress/config` before Python commands read bridged flags.

The wrapper can read `tidypress.yaml` or `tidypress.yml`:

```yaml
python:
  convert:
    input_path: analysis.ipynb
    output_path: site/src/content/docs/analysis.mdx
```

Run with an explicit config:

```bash
tidypress convert --config ./tidypress.yaml
```

The Python package is an optional companion for Python environments. It provides native notebook conversion and source extraction; it is not another renderer or a replacement installer for the npm package.

Rendering still uses the Node.js CLI and Astro engine. Node.js 22.12 or newer is required for init, dev, build, preview, and deploy.

When to install it

Do not install Python to create or publish a normal TidyPress site. Use the npm package and Node.js workflow from the Quickstart.

Install the companion only when you need its two Python-native utilities: notebook conversion or source-comment extraction.

pip install tidypress

That installation is sufficient for convert and extract-docs. Install the Node CLI separately when you also want site commands:

npm install tidypress
# or: npm install --global tidypress

For site commands, the wrapper resolves the Node CLI in this order:

TIDYPRESS_CLI_JS
a local monorepo or project node_modules/tidypress
tidypress on PATH

It does not download or invoke packages through npx by default. TIDYPRESS_USE_NPX=1 is an explicit diagnostic/CI escape hatch, not a required installation step.

Site commands

These commands are delegated to the Node CLI — the same surface as npx tidypress:

tidypress init [--preset <name>]
tidypress dev
tidypress build
tidypress preview
tidypress clean
tidypress deploy
# build/llms.txt on every build
tidypress import devto --username <username/slug-or-article-url>
tidypress doctor
tidypress migrate-sections
tidypress add-version <label>
tidypress domain setup [domain] --platform <platform>
tidypress release-check

import devto fetches real markdown. Other import providers write review scaffolds. Experimental Node commands (editor, export, ai) can be forwarded, but intentionally stop with EXPERIMENTAL_NOT_IMPLEMENTED even after opt-in. They are reserved command contracts, not working features.

Notebook conversion

convert is Python-native:

tidypress convert analysis.ipynb

By default, output goes to the docs collection:

site/src/content/docs/analysis.mdx

Point at writing when the notebook is a public essay, not a manual page:

tidypress convert analysis.ipynb --output site/src/content/writing/analysis.mdx

Or choose any path under the publish root:

tidypress convert analysis.ipynb --output site/src/content/docs/reports/analysis.mdx

The converter preserves markdown cells, code cells, text outputs, and PNG image outputs.

Source extraction

extract-docs writes a simple API notes file from Python, TypeScript, or Go comments:

tidypress extract-docs src/ --lang py
tidypress extract-docs src/ --lang ts
tidypress extract-docs src/ --lang go

Default output:

site/src/content/docs/api/<lang>.md

This is a convenience helper for small projects. For large API references, keep using the dedicated tooling for that ecosystem.

Agents and markdown

Agents that edit files in git use the same commands as you do: add markdown under src/content/, run tidypress build, deploy build/. Point the model at build/llms.txt or the live /llms.txt URL for full published content. Details: The repository is the editing protocol.

Help and init presets

tidypress --help
tidypress init --help  # Python wrapper only

The Python entrypoint lists the same init presets as the Node CLI: lab, blog, persona, docs-writing, body-of-work, body-of-work-docs, and custom. default is an alias for lab. The Node CLI itself currently exposes only root tidypress --help; command-specific help is not implemented there.

Streaming build and deploy

tidypress build and tidypress deploy stream Node CLI output live through an async subprocess. Add --sync to use the legacy blocking runner (for scripts that capture output).

YAML bridge

tidypress.yaml is validated against the shared JSON Schema from @tidypress/config before Python commands read bridged flags.

The wrapper can read tidypress.yaml or tidypress.yml:

python:
  convert:
    input_path: analysis.ipynb
    output_path: site/src/content/docs/analysis.mdx

Run with an explicit config:

tidypress convert --config ./tidypress.yaml