Writing docs

All documentation, code comments, and commit messages in Pluto use ASD-STE100 Simplified Technical English.

The style

• Use short sentences.
• Put one instruction in each sentence.
• Use active voice.
• Use simple, consistent words. Use the same word for the same thing.

Document only what the source says

Before you write a page, read its source: the code, the skill files of the project, and the FEATURES.md file. A README can be out of date, so check it against the code. When the code and a skill file disagree, trust the code. Do not invent an option, a route, or a behavior. If a source is unclear, leave the detail out.

Do not name a client site in the docs.

Update the docs with every change

A change is not done until its docs are up to date. In the same pull request as the code, update:

• The pages of this site that describe the behavior, the options, the commands, or the setup steps that changed. Add a page when a feature has none.
• The skill file and the FEATURES.md line of each project that changed.
• The README, when the change touches what it shows. A README stays short: what the project is, how to install it, and a link to these docs.

Pages are Markdown files

The pages are Markdown files in the content/ folder of the docs repository. Nuxt Content reads them.

• Prefix a file or a folder with a number to set its order: 1.getting-started, 2.installation.md.
• Use a leading zero when a folder has 10 or more pages: 01.layers.md, 10.mail.md.
• Put a .navigation.yml file in each folder with a title and an icon.

title: Getting started
icon: i-lucide-rocket

Frontmatter

Each page has a title and a description. Add a navigation.icon with a Lucide icon where it fits.

---
title: Layers
description: Learn how the core layer and other layers work together.
navigation:
  icon: i-lucide-layers
---

MDC components

Use these components where they help:

::warning
Do not put a secret in the build environment.
::

Give a code block a file name or a label in square brackets:

```ts [nuxt.config.ts]
export default defineNuxtConfig({})
```

Wrap placeholders such as <label> in backticks. A bare angle bracket in prose is parsed as HTML.

Edit pages in the admin

This site extends the @plutocms/docs layer. The layer lets editors change these files in the Pluto admin at /admin. See Docs.

• In development, the admin reads and writes the local content/ folder. You are signed in as a local user.
• In production, the admin reads and writes the GitHub repository. Each save is a commit, and the commit message has no [skip ci] marker, so the site redeploys.
• The site uses the hybrid render mode. A saved page shows on the site at once, before the new build is live. See Build time, run time, or both.
• The site uses the npm packages. Set PLUTO_LOCAL_ROOT=.. in .env to use your local ../pluto checkout (core and the docs layer). PLUTO_USE_LOCAL=false turns it off again. See Workspace.

The admin edit form has fields for the title, the description, the navigation, and the SEO values. They map to the title, description, navigation, and seo keys of the frontmatter.

Check your work

Run the dev server and open your page. Run the lint and the build before you open a pull request. In hybrid mode, the build does not prerender the docs pages, so it does not find broken links. Open the pages that you changed and check their links.

bun run dev
bun run lint
bun run build