Skip to content

About these docs

This page explains how the Pomme documentation is organized and how to work on it.

The documentation separates pages by what you’re trying to do:

  • Get started pages help you install Pomme and create your first VM.
  • Concept pages explain how Pomme works and why it behaves the way it does.
  • How-to guides give you the steps to complete one task.
  • Reference pages list facts to look up, such as commands, flags, fields, and exit codes.
  • Resources include troubleshooting, a glossary, and release notes.

The documentation follows the Google developer documentation style guide. The repository file Website/CONTRIBUTING.md summarizes the rules that these pages use most, including page structure, voice, formatting, and a word list.

The site checks prose with Vale and the Google style package.

The switch next to the theme selector turns on Crawler mode, which retells the guides in the voice of a sarcastic game-show System at /crawler/. Crawler mode changes the narration only. Its commands, flags, examples, and tables match the normal pages. Pages that it doesn’t retell, such as the command-line reference, show their normal text under a notice. The repository file Website/CRAWLER_VOICE.md describes how to write and maintain these pages.

The command-line reference is generated from the help text of the installed pomme executable, so it matches the version that you run. Each generated page names the version and commit that it came from.

The site uses Starlight, and it’s published at https://pommevm.dev from the main branch. To preview a change, build and view the site on your own Mac.

To build and view the site, do the following:

  1. Install Node.js.

  2. In a terminal, go to the Website directory of the Pomme repository:

    Terminal window
    cd Website
  3. Install the site’s dependencies:

    Terminal window
    npm install
  4. Start the development server:

    Terminal window
    npm run dev
  5. In a browser, open http://localhost:4321.

The development server reloads pages when you save a change. The site’s search box works only in a built site. To build the site and serve the result, run npm run build and then npm run preview.

The following commands check and regenerate site content:

Command Description
npm run lint:style Checks every page against the Google style rules.
npm run reference Regenerates the command-line reference from ~/.local/bin/pomme. To use a different executable, set POMME_RUNNER to its absolute path.
npm run check:crawler Checks that each Crawler mode page keeps the code blocks and tables of its normal page, and that its links stay in Crawler mode.
npm run build Builds the static site into Website/dist and checks that every page compiles.