Get started

Install smalldocs, make a site, preview it and publish it.

Install smalldocs

smalldocs needs Python 3.11 or later. Add it to a project as a development tool:

uv add --dev smalldocs     # or: pip install smalldocs

If the site documents the API of your package, install smalldocs in the environment of the package. smalldocs imports the package to read its code.

Make a site

A project is a folder with a _smalldocs.yml file and some pages. A page is a Markdown file, .md or .qmd, or a Jupyter notebook, .ipynb. A .qmd file is Markdown with some additions, such as callouts and tabs. Writing pages describes them. Front matter is the YAML block between two --- lines at the top of a page. It holds the options of the page, such as its title.

The smallest site has three files:

project:
  type: website

website:
  title: "My project"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

theme: cosmo
toc: true

---
title: My project
---

My project does one thing well. Read [about it](about.qmd).

---
title: About
---

## Who made it

We did.

Build the site

smalldocs render            # the folder you are in
smalldocs render docs       # or another folder

smalldocs writes the site into the output folder. The output folder is _site, or the folder that the option project.output-dir names. Each build deletes the old content of the output folder first. Open _site/index.html in a browser, or serve the folder.

Preview the site

smalldocs preview docs

The command builds the site, serves it at http://127.0.0.1:4200 and opens your browser. When you save a file, smalldocs builds the site again, and the browser loads the new pages. To use another port, give --port.

Generated pages do not start a loop

A pre-render script, or the API reference, writes pages during a build. After each build, preview notes the time of each file again. So the pages that a build writes do not start another build.

Publish the site

To put the site on GitHub Pages, run:

smalldocs publish gh-pages docs

The command builds the site and commits it to the branch gh-pages. It works in a temporary copy of the repository, called a worktree, and then pushes the branch to origin. Your files and your current branch do not change. In the settings of the repository on GitHub, set Pages to use the branch gh-pages.

You can also build the site in a GitHub Action, and upload _site. smalldocs needs only one pip install there.