Skip to content
Pomme

About these docs

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

How the documentation is organized

Section titled “How the documentation is organized”

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.

Style

Section titled “Style”

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.

Command-line reference

Section titled “Command-line reference”

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.

Build the site locally

Section titled “Build the site locally”

The site uses Starlight. You build and view it on your own Mac; it isn’t published.

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.

Check and regenerate content

Section titled “Check and regenerate content”

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 build Builds the static site into Website/dist and checks that every page compiles.