The commands

Each command of smalldocs, with its options.

Each command takes the folder of the project, which holds _smalldocs.yml or _quarto.yml. If you give no folder, the command uses the folder you are in.

render

smalldocs render [DIR] [--quiet] [--strict]

The command builds the site. With --quiet, it prints only warnings and errors. With --strict, a warning makes the exit code 1. A broken link and an option that smalldocs ignores are warnings.

preview

smalldocs preview [DIR] [--port 4200] [--host 127.0.0.1] [--no-browser]

The command builds the site, serves it and opens a browser. When a file of the project changes, it builds the site again, and the browser loads the new pages. If a build fails, the command prints the error and keeps the last good site. It listens on this computer only. To listen on other addresses, give --host.

check

smalldocs check [DIR]

The command builds the site into a temporary folder, and keeps your output folder as it is. It still writes the API pages and runs the pre-render and post-render commands, as a build does. Then it lists what to fix:

  • the options that smalldocs ignores
  • the broken links
  • the Markdown that smalldocs does not read or does not run, with the file and the line of each. Examples are citations, cross-references, grid tables and code cells

If it finds anything, the exit code is 1.

api

smalldocs api build|check|list [--dir DIR]
smalldocs api module NAME [--dir DIR]

The command makes the reference pages, checks the docments, lists the documented names, or prints one module as Markdown. See The API reference.

publish

smalldocs publish gh-pages [DIR] [--branch gh-pages] [--remote origin] [--no-render] [-m MESSAGE]

The command builds the site and pushes it to the branch. It works in a temporary worktree, so your files and your current branch do not change. Your git hooks do not run for the commit of the site.

The command refuses some branches, because they hold your source files:

  • your current branch
  • the default branch of the remote
  • main and master
  • a branch that shares history with your code and holds no site

With --no-render, the command publishes the output folder as it is.

Exit codes

Code Meaning
0 Done
1 Done, with something to fix: --strict with warnings, or check and api check with findings
2 Stopped: no _smalldocs.yml or _quarto.yml, a bad option, a failed script, or a port in use