Built with Astro, hosted on Cloudflare Pages behind Cloudflare. Domain registered in 2020.
tidypress.pages.dev is built with Astro, hosted on Cloudflare Pages behind Cloudflare.
| Technology | Version | First seen |
|---|---|---|
| JavaScript Frameworks & Libraries1 | ||
| – | 7 Nov 2026 | |
| Frontend Build Tools & CSS1 | ||
| – | 7 Nov 2026 | |
| CDN & Hosting2 | ||
| – | 7 Nov 2026 | |
| Fonts & Icon Fonts1 | ||
| – | 7 Nov 2026 | |
Registration from the registry's RDAP record, the certificate the site serves, and its rank in public traffic lists.
The crew hasn’t read this site’s colors yet. We read a palette when we capture a site’s screenshot, busiest sites first. Meanwhile, browse palettes from other sites.
aaden.ns.cloudflare.comevangeline.ns.cloudflare.com# As a condition of accessing this website, you agree to abide by the following # content signals: # (a) If a content-signal = yes, you may collect content for the corresponding # use. # (b) If a content-signal = no, you may not collect content for the # corresponding use. # (c) If the website operator does not include a content signal for a # corresponding use, the website operator neither grants nor restricts # permission via content signal with respect to the corresponding use. # The content signals and their meanings are: # search: building a search index and providing search results (e.g., returning # hyperlinks and short excerpts from your website's contents). Search does not # include providing AI-generated search summaries. # ai-input: inputting content into one or more AI models (e.g., retrieval # augmented generation, grounding, or other real-time taking of content for # generative AI search answers). # ai-train: training or fine-tuning AI models. # ANY RESTRICTIONS EXPRESSED VIA CONTENT SIGNALS ARE EXPRESS RESERVATIONS OF # RIGHTS UNDER ARTICLE 4 OF THE EUROPEAN UNION DIRECTIVE 2019/790 ON COPYRIGHT # AND RELATED RIGHTS IN THE DIGITAL SINGLE MARKET.
# tidypress
> A publishing framework for Git-native authorship.
- [Home](https://tidypress.pages.dev/)
## docs
### [Diagnostics and escape hatches](https://tidypress.pages.dev/docs/advanced-configuration)
Resolve publish-root ambiguity, clear generated state, and isolate extension failures.
Start with `tidypress doctor`. The checks below are for ambiguous repositories,
engine upgrades, and project extension failures—not normal configuration.
## Confirm the publish root
The CLI searches the current directory, then conventional `site/` and nearby
locations for `tidypress.config.ts`. When more than one candidate is plausible,
run from the intended publish root or set a temporary override:
```bash
TIDYPRESS_PUBLISH_ROOT=./site npx tidypress doctor
```
Do not persist this variable unless CI genuinely cannot express the working
directory. The config file location is the normal contract.
## Clear generated state
```bash
npx tidypress clean
npx tidypress build
```
`clean` removes the publish-root output and the active project's TidyPress cache.
It does not delete authored Markdown, config, public assets, agent settings, or
environment files.
## Isolate project extensions
If a project builds before a presentation extension is enabled:
1. Check every project module path begins with `./` and stays inside the publish root.
2. Remove one `plugins`, `markdown`, `mdx.components`, `ui`, or custom `render` entry at a time.
3. Re-run `doctor` and `build` after each change.
4. Treat a missing export or broken registered Astro view as a real build error.
TidyPress intentionally does not swallow a registered view failure and fall back
to unrelated baseline markup.
## Inspect generated contracts
After a successful build, verify:
```txt
site/build/index.html
site/build/pagefind/
site/build/llms.txt
site/build/sitemap-index.xml # when a production siteUrl is available
```
Pagefind and sitemap filenames may include additional generated files. Validate
the public behavior rather than editing anything inside `build/`.
## No hidden environment installer
`npm install tidypress`, `tidypress --version`, and ordinary CLI commands do not
install agent skills or modify the shell. Skill installation is explicit:
```bash
npx tidypress skills install
```
It writes only the TidyPress skill folder in the detected supported agent
location and preserves existing files unless `--force` is supplied.
---
### [Analytics](https://tidypress.pages.dev/docs/analytics)
Add optional privacy-friendly analytics scripts to the built site.
```ts
analytics: { type: 'none' }
```
## Supported adapters
```ts
analytics: {
type: 'plausible',
endpoint: 'https://plausible.io/js/script.js',
siteId: 'example.com',
}
```
| Type | Notes |
|------|-------|
| `none` | default; no analytics script |
| `plausible` | Plausible-style script injection |
| `fathom` | Fathom-style script injection |
| `umami` | Umami script |
## Plausible
```ts
analytics: {
type: 'plausible',
endpoint: 'https://plausible.io/js/script.js',
siteId: 'docs.example.com',
}
```
## Fathom
```ts
analytics: {
type: 'fathom',
endpoint: 'https://cdn.usefathom.com/script.js',
siteId: 'ABCDEFGH',
}
```
## Umami
```ts
analytics: {
type: 'umami',
endpoint: 'https://analytics.example.com/script.js',
siteId: '00000000-0000-0000-0000-000000000000',
}
```
TidyPress renders the script tag with the configured endpoint and site id.
---
### [How TidyPress works](https://tidypress.pages.dev/docs/architecture)
How the CLI, config package, Astro engine, build output, and cache fit together.
TidyPress is split into four npm packages and one optional Python companion.
```txt
packages/
├── cli/ # commands, project setup, builds, deploy helpers
├── config/ # typed config, defaults, validation, normalization
├── engine/ # Astro runtime, layouts, routing, components, search UI
└── astro/ # opt-in Astro integration for explicit Astro projects
wrappers/
└── python/ # Python entrypoint and Python-native helpers
```
## Build flow
When you run `tidypress dev` or `tidypress build`, the CLI resolves your **publish root** and runs the pinned `@tidypress/engine` package. Your markdown stays in place; only a static artifact and a local cache are created.
`init` scaffolds `site/` by default — the conventional publish root for config, content, and `build/`. In a monorepo, config may sit at the project root instead, as in `apps/site/`. The CLI resolves whichever folder contains `tidypress.config.ts`.
```txt
site/
├── tidypress.config.ts
├── src/content/
│ ├── writing/ # dated posts (RSS, tags, archive)
│ ├── projects/ # cards + optional pages (lab preset)
│ └── docs/ # docs collection — sidebar-ordered guides at /docs/…
├── public/
└── build/
```
Steps:
1. The CLI resolves the publish root and validates config.
2. Plugin manifest codegen writes to the cache directory.
3. Astro runs from `node_modules/@tidypress/engine` with `TIDYPRESS_PROJECT_ROOT` pointing at your project.
4. Static HTML is written to `build/`.
5. Pagefind indexes `build/`.
6. The CLI writes `build/llms.txt` with full published markdown for agents. Disable with `capabilities.disable: ['llmsTxt']` or `tidypress build --no-llms-txt`.
Power users can add `@tidypress/astro` and `astro.config.mjs` via `tidypress init --with-astro`.
## CLI package
`packages/cli` owns commands:
- `init`
- `dev`
- `build`
- `preview`
- `clean`
- `deploy`
- `migrate-sections`
- `add-version`
- `domain`
- `import`
- guarded experimental commands: `editor`, `export`, `ai`
The default command is `dev`. Ports default to `4321`.
Deploy commands work from static output in `build/`.
## Config package
`packages/config` defines `defineConfig()`, defaults, capabilities, collections, nav policy, theme tokens, i18n strings, versions, analytics, and legacy migration from `sections` to `collections`.
Only `name` is required. Defaults enable starter collections:
```txt
docs -> /docs
writing -> /writing
pages -> root-level custom pages
```
`collections` is the current section model. `sections` is the legacy shim.
## Engine package
`packages/engine` is an Astro project published as an npm package. It owns:
- layouts
- routing strategies
- collection views
- MDX components
- sidebar and table-of-contents UI
- theme CSS
- Pagefind search UI
- sitemap and metadata output
Bundled client assets land under `assets/` in `build/`.
## Content model
Under the publish root, `src/content/` holds **collections**—typed folders configured in `tidypress.config.ts`.
**Writing** — dated posts with RSS, the default public voice:
```txt
site/src/content/writing/
```
**Projects / works** — home-page work, `kind: 'projects'`:
```txt
site/src/content/projects/
site/src/content/works/
```
**Docs collection** — sidebar-ordered pages at `/docs/…`:
```txt
site/src/content/docs/
```
Forms: `doc` for reference pages, `manual` for procedural guides. Other collection keys use the kinds in config and [Conventions](./conventions).
## Search
Search is powered by [Pagefind](https://pagefind.app/).
`tidypress build` renders HTML, then builds the Pagefind index inside `build/`.
## Python companion
The Python package provides notebook conversion and source-comment extraction.
It can delegate site commands to a separately installed Node.js CLI, but it is
not a second renderer or the normal installation path for a site.
## Extension points
Advanced projects can extend rendering with:
- `collections.<key>.render`
- `extensions.docForms`
- project-local presentation modules
- optional Astro view files (resolved via `@project/`)
- `@tidypress/astro` integration for explicit Astro projects
See [CI and deployment](/docs/manual/ci) for caching and upload guidance.
---
### [Body of work](https://tidypress.pages.dev/docs/body-of-work)
Works, projects, writing, reference, process, and pages — product docs use the docs collection separately.
TidyPress models a public body of work with collection **keys** and built-in **kinds**. The `body-of-work` preset is generated from `publicationSurfaceDefinitions` in `@tidypress/config` — six surfaces, not product docs.
## Quick start
```bash
npx tidypress init --preset body-of-work --site-url https://yoursite.example
```
For work **and** product documentation in one site:
```bash
npx tidypress init --preset body-of-work-docs --site-url https://yoursite.example
```
| Key | Kind | Purpose |
|-----|------|---------|
| `works` | `projects` | Case studies, major artifacts |
| `projects` | `projects` | Repos, apps, tools, experiments |
| `writing` | `writing` | Essays, technical notes |
| `reference` | `content` | API, config, CLI reference in the docs sidebar shell |
| `process` | `content` | ADRs, decisions, build logs |
| `pages` | `page` | About, now, contact, uses, resume |
The homepage shows **works**, **projects**, and **writing**. **Reference** and **process** link from the **footer**, not the header, so mobile nav stays readable. Add them to `home.order` to surface them on the home page.
## Product docs
The **`docs`** collection is sidebar-ordered product documentation — tutorials, how-tos, and guides. The default `body-of-work` preset disables it; use **`body-of-work-docs`** or **`docs-writing`** to enable it from init.
```bash
npx tidypress init --preset body-of-work-docs
```
Or enable `collections.docs` later and add content under `src/content/docs/`.
## siteUrl
Set **`siteUrl`** in `tidypress.config.ts` before deploy. While it is unset or
still a placeholder, TidyPress omits absolute canonical and Open Graph URLs,
omits the production sitemap, and keeps RSS links relative. `tidypress doctor`
and `tidypress build` remind you to set the production origin.
## Reference vs docs
| Surface | Use for |
|---------|---------|
| `docs` | Teaching and product documentation |
| `reference` | Facts: API, config, CLI |
| `process` | Decisions: ADRs, roadmaps |
## Featured on the home page
Set `featured: true` in frontmatter for writing and projects-kind collections (including a `works` key).
## Related
- [Configuration](./configuration) — presets
- [Examples](./examples)
- [Advanced configuration](./advanced-configuration) — `build/llms.txt` for agents
---
### [Capabilities](https://tidypress.pages.dev/docs/capabilities)
Exact stable and experimental feature gates recognized by TidyPress.
Capabilities are a closed registry. Unknown names fail configuration validation;
they are not general feature flags for arbitrary project code.
## Registry
| Key | Scope | Default | Meaning |
|---|---|---:|---|
| `docs` | collection | on | Built-in docs collection and routes |
| `writing` | collection | on | Writing collection and routes |
| `pages` | collection | on | Root-page collection and routes |
| `theming` | feature | on | Theme switching and theme surface |
| `themingCustom` | feature | off | Required for `theme.mode: 'custom'` |
| `llmsTxt` | feature | on | Full published Markdown build artifact |
| `editor` | experimental | off | Guard for the unimplemented editor scaffold |
| `export` | experimental | off | Guard for the unimplemented export scaffold |
| `ai` | experimental | off | Guard for the unimplemented AI scaffold |
`projects`, `search`, `rss`, `archive`, `tags`, `readingTime`, `i18n`, and
`versioning` are **not** capability keys. Configure those through their actual
collection or feature fields.
## Resolution
```ts
capabilities: {
disable: ['pages', 'llmsTxt'],
enable: ['themingCustom'],
}
```
Resolution order is baseline defaults, direct collection/experimental config,
`capabilities.disable`, then `capabilities.enable`. A name cannot appear in both
lists.
## Collections
For built-in `docs`, `writing`, and `pages`, direct collection `enabled` values
participate in capability resolution:
```ts
collections: {
docs: { enabled: false, basePath: '/docs' },
}
```
Starter presets set both the public collection shape and the relevant gates.
## Custom theming
```ts
capabilities: { enable: ['themingCustom'] },
theme: {
mode: 'custom',
tokens: {
light: { bg: '#ffffff', fg: '#111111' },
dark: { bg: '#0a0a0a', fg: '#fafafa' },
},
}
```
Custom mode requires complete light and dark token objects. The baseline
guardrailed mode remains active when the custom capability is absent.
## Experimental means unavailable
The `editor`, `export`, and `ai` commands currently validate both a config gate
and an explicit CLI flag, then exit with `EXPERIMENTAL_NOT_IMPLEMENTED`. Their
presence reserves and tests the future interface; it is not a promise that the
feature works in the current release.
---
### [Components](https://tidypress.pages.dev/docs/components)
TidyPress-native MDX primitives for guides, cards, media, code, API reference, and interactive documentation.
Components are available in `.mdx` files without imports.
They inherit semantic theme tokens and expose stable `tidy-*` classes and `data-component` parts. Projects and theme plugins can replace any built-in by registering the same MDX component name.
## Cards and grids
Use `CardGroup` for linked destination cards. It collapses to one column on small screens. `Columns` is the neutral layout primitive; `Grid` is an alias.
```jsx
<CardGroup columns={2}>
<Card title="Quickstart" href="/docs/getting-started" icon="terminal">
Build and preview a site in a few minutes.
</Card>
<Card title="Configuration" href="/docs/configuration" icon="settings" eyebrow="Reference">
Understand every project-level setting.
</Card>
</CardGroup>
```
<p class="tidy-example-label">Example — CardGroup</p>
<CardGroup columns={2}>
<Card title="Quickstart" href="/docs/getting-started" icon="terminal">
Build and preview a site in a few minutes.
</Card>
<Card title="Configuration" href="/docs/configuration" icon="settings" eyebrow="Reference">
Understand every project-level setting.
</Card>
</CardGroup>
```jsx
<Grid columns={2}>
<Panel title="Content">Main reading region</Panel>
<Panel title="Context">Supporting information</Panel>
</Grid>
```
<p class="tidy-example-label">Example — Columns / Grid</p>
<Grid columns={2}>
<Panel title="Content">Main reading region</Panel>
<Panel title="Context">Supporting information</Panel>
</Grid>
| Component | Prop | Type | Default |
|-----------|------|------|---------|
| `Card` | `title` | string | required |
| `Card` | `href` | string | unlinked card |
| `Card` | `icon` / `eyebrow` | string | — |
| `Card` | `external` | boolean | inferred from URL |
| `CardGroup` | `columns` | `1 \| 2 \| 3 \| 4` | `2` |
| `Columns` / `Grid` | `columns` | `1 \| 2 \| 3 \| 4` | `2` |
| `Columns` / `Grid` | `gap` | `"sm" \| "md" \| "lg"` | `"md"` |
`Card` also accepts an `icon` named slot for project SVG or Astro icon components.
## Accordions
`Accordion` uses native `<details>` semantics, so it remains keyboard-accessible and useful without JavaScript.
```jsx
<AccordionGroup>
<Accordion title="Where does content live?" open>
Under `site/src/content/` in Git-tracked Markdown or MDX files.
</Accordion>
<Accordion title="Can I replace this component?">
Yes. Register your own `Accordion` through `mdx.components` or a plugin.
</Accordion>
</AccordionGroup>
```
<p class="tidy-example-label">Example — AccordionGroup</p>
<AccordionGroup>
<Accordion title="Where does content live?" open>
Under `site/src/content/` in Git-tracked Markdown or MDX files.
</Accordion>
<Accordion title="Can I replace this component?">
Yes. Register your own `Accordion` through `mdx.components` or a plugin.
</Accordion>
</AccordionGroup>
| Component | Prop | Type | Default |
|-----------|------|------|---------|
| `Accordion` | `title` | string | required |
| `Accordion` | `open` | boolean | `false` |
| `Accordion` | `icon` | string | — |
## Badges, banners, and panels
All three share the tones `neutral`, `accent`, `info`, `success`, `warning`, and `danger`.
```jsx
<Badge tone="success">Stable</Badge>
<Banner title="Build output" tone="info">
The static site is written to `site/build/`.
</Banner>
<Panel title="Runtime status" eyebrow="TidyPress" icon="terminal" tone="success">
Content, routes, and search are ready.
</Panel>
```
<p class="tidy-example-label">Example — Badge, Banner, and Panel</p>
<Badge tone="success">Stable</Badge>
<Banner title="Build output" tone="info">
The static site is written to `site/build/`.
</Banner>
<Panel title="Runtime status" eyebrow="TidyPress" icon="terminal" tone="success">
Content, routes, and search are ready.
</Panel>
`Badge` accepts an optional `href`. `Panel` is a structured information container with a separated header, content region, and optional footer; unlike `Callout`, it is not an inline editorial aside. It accepts an `icon` name and named `icon`, `header`, and `footer` slots for imported Astro components.
## Code groups and keyboard input
`CodeGroup` turns direct fenced-code children into an accessible tab set. Labels must match the number and order of code blocks. Arrow, Home, and End keys navigate tabs.
````jsx
<CodeGroup labels={["npm", "pnpm"]}>
```bash
npm install -g tidypress
```
```bash
pnpm add -g tidypress
```
</CodeGroup>
Press <Kbd>Cmd</Kbd> + <Kbd>K</Kbd>.
````
<p class="tidy-example-label">Example — CodeGroup and Kbd</p>
<CodeGroup labels={["npm", "pnpm"]}>
```bash
npm install -g tidypress
```
```bash
pnpm add -g tidypress
```
</CodeGroup>
Press <Kbd>Cmd</Kbd> + <Kbd>K</Kbd>.
## Frame
`Frame` gives live embeds, diagrams, interactive previews, or arbitrary content a consistent presentation surface. It is deliberately broader than `Image`: use `Image` for semantic media and `Frame` when the framed content is an application, iframe, rendered artifact, or custom composition.
```jsx
<Frame caption="The generated build artifact, embedded as a live document.">
<iframe
src="/embeds/build-receipt.html"
title="Generated static build receipt"
height="260"
loading="lazy"
/>
</Frame>
```
<p class="tidy-example-label">Example — Frame</p>
<Frame caption="The generated build artifact, embedded as a live document.">
<iframe
src="/embeds/build-receipt.html"
title="Generated static build receipt"
height="260"
loading="lazy"
/>
</Frame>
| Prop | Type | Default |
|------|------|---------|
| `caption` | string | — |
| `href` | string | — |
| `class` | string | — |
## Image
Use `Image` for semantic still media, optional dimensions, and captions.
```jsx
<Image
src="/images/flower.jpg"
alt="Colorful tulips in bloom"
caption="Vivid spring flowers"
/>
```
<p class="tidy-example-label">Example — Image</p>
<Image
src="/images/flower.jpg"
alt="Colorful tulips in bloom"
caption="Vivid spring flowers"
/>
| Prop | Type | Default |
|------|------|---------|
| `src` | `string \| ImageMetadata` | required |
| `alt` | string | required |
| `caption` | string | — |
| `width` | number | — |
| `height` | number | — |
| `zoom` | boolean | global `mdx.imageZoom` setting (`true` by default) |
The same image can use plain Markdown when no component caption or sizing is needed:
```md

```
Markdown and MDX content images open in a centered focused viewer. Set `zoom={false}`
on an individual `Image`, or set `mdx.imageZoom: false` in site config to disable
the behavior globally.
## Video
Use `Video` for native footage with TidyPress playback, audio, replay, and viewport behavior.
```jsx
<Video
src="/videos/flower.mp4"
poster="/images/flower.jpg"
title="TidyPress video demonstration"
caption="Custom playback, mute, and replay controls."
autoplayOnView
/>
```
<p class="tidy-example-label">Example — Video</p>
<Video
src="/videos/flower.mp4"
poster="/images/flower.jpg"
title="TidyPress video demonstration"
caption="Custom playback, mute, and replay controls."
autoplayOnView
/>
The | – |
| 7 Nov 2026 |