smalldocs

Websites from Markdown, in Python

smalldocs builds a website from a folder of Markdown pages and notebooks. A file _smalldocs.yml in the folder holds the options of the site. smalldocs writes the site into the folder _site.

Each page of the site has a navbar at the top, a sidebar at the left and a table of contents at the right. smalldocs also makes reference pages from your Python code, and pages that list other pages, such as a blog.

The site can use any theme from Bootswatch. A theme is a stylesheet that sets the colours and the fonts of the site.

smalldocs is one Python package, and it needs no other programs. Install it from PyPI:

pip install smalldocs

Build a site, or preview it while you write:

smalldocs render docs      # writes docs/_site
smalldocs preview docs     # serves it at http://127.0.0.1:4200 and reloads on every change

What smalldocs does not do

smalldocs makes websites only. It does not make PDF files, Word files, slides or books. It does not run code. A notebook shows the outputs that were saved in it.

Where the conventions come from

smalldocs takes its conventions from Quarto, a larger tool that also makes PDFs and slides. The conventions are the .qmd pages, the Markdown of Pandoc, and the options of a site. So a Quarto website builds with smalldocs, with no change. If you use Quarto now, read From Quarto, and run smalldocs check.

The guide