Contributing

Writing the documentation

How this Docus site is organised, how to preview and build it, the writing rules, and how it is published.

This site is a Docus project (a Nuxt layer) in the docs/ folder of the repository. It is outside the product and outside the Rust build.

Layout

Path	Purpose
`docs/content/`	All pages, as Markdown.
`docs/content/index.md`	Landing page.
`docs/content/<N>.<section>/`	One folder per section: `1.getting-started`, `2.guide`, `3.reference`, `4.contributing`. Each has a `.navigation.yml` with the section `title` and `icon`.
`docs/nuxt.config.ts`	Site name and URL, the asset folders served from `assets/`, the font list, and switches that keep the build static.
`docs/app/app.config.ts`	Header title and logo, GitHub link for "Edit this page", colours.
`docs/app/app.css`	Sets Poppins as the sans-serif font.
`docs/package.json`, `docs/package-lock.json`	The three npm dependencies: `docus`, `nuxt`, `better-sqlite3`.

The numeric filename prefix sets the navigation order. The prefix is dropped from the route. For example:

1.getting-started/2.installation.md becomes /getting-started/installation.
4.contributing/8.documentation.md becomes /contributing/documentation.

Prefixes sort as text. A folder with ten or more pages zero-pads all of them (2.guide/01.interface.md … 2.guide/16.privacy-and-security.md).

What `docs/` may contain

AGENTS.md section 5.2 limits the folder to:

package.json and package-lock.json;
nuxt.config.ts;
app/app.config.ts and app/app.css;
the .navigation.yml file in each section folder;
Markdown under content/.

No Vue components, pages, plugins, server code or other handwritten JS/TS. The only npm dependencies are docus, nuxt and better-sqlite3. Adding another needs the owner's approval.

This is a written exception to the "Rust only" rule, which covers the product and the build (xtask). It does not allow JS/TS anywhere else.

Preview locally

You need Node 22 or newer and npm.

cd docs
npm ci
npm run dev

Open http://localhost:3000. Pages reload as you save.

Reproduce the Pages build

GitHub Pages serves the site under /postguy/, so the build sets a base URL:

cd docs
npm ci
NUXT_APP_BASE_URL=/postguy/ npm run generate

The static site is written to docs/.output/public.
The generated folders docs/node_modules/, docs/.nuxt/, docs/.output/ and docs/.data/ are git-ignored. cargo xtask assets skips them.
nitro.prerender.failOnError is on, so a broken internal link fails the build.

Writing rules

Frontmatter

Every page has title and description, and nothing else. Do not add an H1 in the body, because Docus renders the title. Start the body with prose or ##.

Put every double-brace variable and every {{% ... %}} shortcode in inline code or a fenced block. In plain prose the Markdown engine treats double braces as a data binding and renders nothing. Avoid bare single-brace attribute-like sequences in prose for the same reason.

Links

Link between pages with site routes (/guide/variables), never relative file paths. Link to repository files with https://github.com/zuramai/postguy/blob/main/<path>.

Icons, images and fonts

Use only i-lucide-* icons. Commit no images and no screenshots. The logo in the header is the only picture. Do not add a font.

Honest status

Check parity/postman-features.toml for the feature. Anything partial or planned gets a note saying what is missing. Describe the MCP server as planned only.

Verify facts in code

Check every fact (flag, default, limit, label, shortcut) against the source before you write it. If you cannot confirm it, leave it out.

Components

Component	Use
`::note`, `::tip`, `::warning`, `::caution`	Callouts.
`::tabs` with `:::tabs-item{label="macOS"}`	Per-platform instructions.
`::steps`	Numbered tutorials. Each step starts with a `###` heading.
`::code-group`	Alternative snippets side by side.
`::card-group` with `:::card{title="..." icon="i-lucide-..." to="/..."}`	Link cards.

Use tables for lists of facts. Use fenced blocks with a language tag (json, sh, js, toml, text).

A callout example:

::warning
Secret variables are not encrypted at rest.
::

Describing other products

Mention Postman only as a factual compatibility statement, for example "imports Postman Collection v2.0 and v2.1". Do not use screenshots of it, comparisons or marketing language. Do not describe behaviour beyond what Postguy's code does. See Assets and clean-room.

Logo and fonts

The header logo and the Poppins faces are served from the original files in assets/logo/ and assets/fonts/.

nitro.publicAssets in nuxt.config.ts maps them to the /logo and /fonts URLs. They are never copied into docs/.
ATTRIBUTION.toml records this under the usage of each file.
The configuration disables the remote font download for Nuxt UI's default face. Poppins is the only font used, as AGENTS.md section 1.4 requires.
Generated social-preview images and the Docus MCP server are switched off for the same reasons: no unattributed font rendering, and no server routes on static hosting.

Publishing

.github/workflows/docs.yml builds and deploys the site.

Event	Result
Pull request touching `docs/`, `assets/logo/`, `assets/fonts/**` or the workflow	`npm ci` and `npm run generate` with `NUXT_APP_BASE_URL=/postguy/`. No upload. A broken page fails the check.
Push to `main` touching the same paths	The build. Then the `public` output is uploaded as the Pages artifact and deployed by `actions/deploy-pages`.
Manual dispatch	The build. The deploy job runs when started from `main`.

The site is published at zuramai.github.io/postguy. The in-app Help menu's Documentation item opens this address.

For the deploy job to succeed, enable GitHub Pages in the repository settings (Settings, Pages) with Source set to "GitHub Actions". Until then the build passes and the deploy fails. This is a one-time manual step for the owner.

If the site later moves to a custom domain:

Change site.url in nuxt.config.ts.
Set NUXT_APP_BASE_URL to / in the workflow.
Update the documentation address in crates/ui-egui/src/commands.rs.

Keep pages true

Update the matching page in the same pull request as any user-facing change. When a feature's status changes in parity/postman-features.toml, update Feature status and the notes on the affected guide page.

Edit this pageorReport an issue

Releasing

How a tagged release builds the macOS, Windows and Linux packages, which secrets sign them, and how to run each packaging script locally.