Project Manual
Contents

Generating Sites Overview

Simple Docs separates documentation source, generated files, and the server that publishes those files. Choose a workflow based on where the Markdown is stored and whether Python is available on the build machine.

Available workflows#

  1. Build the bundled example with Python.
  2. Build external Markdown with Python.
  3. Build external Markdown with the builder container.
  4. Create an offline ZIP that opens without a server.
  5. Select or add a visual theme.
  6. Customize the manual name, header mark, and favicon.
  7. Serve generated files with Python or nginx.

Use Python builds when Python 3.11 or newer is available. Use container builds when the generator should run in an isolated environment. After either build, follow serving generated sites. For shorter commands, use the Make helpers. Theme selection and authoring are covered in create and select themes. Branding changes are covered in customize branding.

Source layout#

The source path must point directly to a documentation source directory:

/path/to/project/docs/
├── 01-getting-started/
│   └── 01-introduction.md
├── 02-reference/
│   └── 01-commands.md
└── images/

The documentation source directory may be inside this repository, inside another Git repository, or in a private directory that is not tracked by Git.

The section slug images is reserved for the image directory in generated output. Use a different section name, such as 02-image-guide/.

Generated files#

Hosted workflows produce a static site and compressed deployment bundle. An optional offline ZIP can be extracted and opened directly in a browser:

/path/to/build/
├── site/
│   ├── assets/
│   │   └── theme/
│   └── manual/
├── manual-site.tar.gz
└── manual-site-offline.zip

Only generated HTML, CSS, JavaScript, JSON, and images are placed in these outputs. Source Markdown is not included. The hosted site and tar bundle use clean server URLs. The offline ZIP uses relative file URLs and embedded search data so it works without a server.

Keep paths separate#

Always use separate locations for source, site output, and archive output. The generator rejects overlapping paths before deleting or replacing generated files.

Successful builds create hidden ownership markers beside the site directory and archive. These markers allow later builds to replace their own output while protecting unrelated files.