The configuration

The options in _smalldocs.yml that smalldocs reads, and how it reads a _quarto.yml.

The config file of a project is _smalldocs.yml, in the folder of the project. smalldocs can also read _quarto.yml, the config file of Quarto. See A _quarto.yml below.

project:
  type: website
website:
  title: My project
theme: cosmo         # the options of each page are at the top level
toc: true
linkify: true        # the options of smalldocs are at the top level too; see Linkify below
api:
  packages: [mypkg]

An option is a key in _smalldocs.yml, in a _metadata.yml file or in the front matter of a page. smalldocs merges the options in this order, and a later value wins:

  1. The top level of _smalldocs.yml.
  2. A _metadata.yml file in each folder on the path to the page.
  3. The front matter of the page.

metadata-files is a list of more YAML files, with paths from the folder of the project. smalldocs merges them into _smalldocs.yml, and a key in _smalldocs.yml wins over the same key in these files.

If smalldocs does not read an option, the build gives a warning. With smalldocs render --strict, a warning makes the build fail.

project

Key What it does
type website. book, a type of project in Quarto, is built as a website, with its chapters as the sidebar. Another type stops the build
output-dir The output folder; _site by default. See the note below the table
render One glob, or a list of globs, of the pages to build. A glob is a path pattern; see Globs. A glob that starts with ! leaves pages out. Without render, every .qmd, .md and .ipynb file is a page
resources One glob, or a list of globs, of more files to copy into the site, such as .nojekyll or images/**
pre-render, post-render Commands to run before and after the build, in the folder of the project. A command that is one .py file runs with the Python of smalldocs. See the note below the table

A command of pre-render or post-render gets these environment variables. Their names come from Quarto, so a script written for Quarto still works:

  • QUARTO_PROJECT_DIR: the folder of the project
  • QUARTO_PROJECT_OUTPUT_DIR: the output folder, from the folder of the project
  • QUARTO_PROJECT_INPUT_FILES and QUARTO_PROJECT_OUTPUT_FILES: the pages and the files that the build writes, one on each line, as paths from the folder of the project
  • QUARTO_PROJECT_RENDER_ALL: 1, because each build makes every page
  • SMALLDOCS: 1, so a script can tell smalldocs from Quarto

Each build deletes the old content of the output folder. So smalldocs refuses an output folder in these cases:

  • The folder is the project, or a folder above the project.
  • The folder holds a .git folder.
  • The folder holds files, but no site_libs folder. A site_libs folder shows that an earlier build made the folder.

Without render, smalldocs leaves out some files. It leaves out files and folders whose names start with _ or ., the output folder, virtual environments and README.md.

Globs

A glob is a path pattern, such as guide/*.qmd. smalldocs reads globs by these rules, which are the rules of Quarto:

  • In a glob with a /, the * stays inside one folder, and ** crosses folders. So guide/* finds guide/a.qmd, but not guide/old/b.qmd. guide/** finds both.
  • A glob with no /, such as *.qmd, finds files in every folder.
  • A folder name, such as guide/, means the pages in the folder.

Sometimes a page links to a page that is not built, for example a draft. smalldocs reports the link, and it never copies the source of that page into the site.

website

Key What it does
title, description The name and the summary of the site
site-url The address of the site. smalldocs needs it for sitemap.xml and for feeds
repo-url, repo-branch, repo-subdir, repo-actions Links under the table of contents: edit, source, issue
navbar left, right, tools, title, logo, background, search. An entry is a page, or href and text, with an icon. menu makes a dropdown
sidebar contents, style (floating sits beside the text, and docked is a full-height panel at the left edge), title, logo, search, tools, collapse-level. A list gives several sidebars
page-navigation Links to the previous page and the next page of the sidebar
page-footer One text, or left, center and right. Each part is Markdown or a list of entries
search false turns search off
favicon, open-graph, bread-crumbs The icon in the browser tab. The Open Graph tags, which give the title and the picture that a link to the page shows in other apps. The breadcrumbs, the path of the page above its title; false hides them

The contents of a sidebar takes these entries:

sidebar:
  contents:
    - index.qmd                      # a page
    - section: Guide                 # a section that folds
      contents: guide/*              # a glob: by `order:`, then the index page, then by path
    - section: Reference
      href: api/index.qmd            # a section that is also a page
      contents:
        - api/one.qmd
    - auto: examples                 # one section for each folder, titled by its index page
    - text: Elsewhere
      href: https://example.com
    - text: "---"                    # a line

The options of a page

Write these options at the top level of _smalldocs.yml or of a _metadata.yml file. A page can also set them in its front matter.

Key What it does
theme A Bootswatch name, or light: and dark: for two themes and a toggle. See Themes
css Your stylesheets, after the stylesheet of the theme
toc, toc-depth, toc-title The table of contents at the right of the page
number-sections Numbers before the headings
code-copy The copy button on code. It is on by default
from Turns off a part of the Markdown. markdown-smart keeps quotes and dashes as you type them. markdown-tex_math_dollars reads each $ as a dollar. markdown-smart-tex_math_dollars does both
page-layout article (the default), full or custom
link-external-newwindow Open links to other sites in a new tab
include-in-header, include-before-body, include-after-body Files, or text: entries, to put into each page
echo, output, include, execute Hide the code or the output of every cell, in a notebook or in a page. execute: {echo: false} works too
title, subtitle, description, author, date, date-format, categories, image The title block, which is the title, subtitle, author and date at the top of the page. Also what a listing shows
draft true leaves the page out of the site
order The place of a page among the pages that a glob finds
listing A list of other pages. See Listings
title-block-banner A band of the primary colour behind the title

The options of smalldocs

These options belong to smalldocs. They are at the top level of _smalldocs.yml.

linkify: true          # a documented name in backticks links to its entry; on with `api`
symbols: _symbols.json # the index of names that linkify reads
api:                   # the API reference: see the API page
  packages: [mypkg]

Linkify

Linkify turns a name in backticks into a link to the entry of that name in the API reference. For example, `Site.build` and `Site.build()` link to the entry of Site.build. A name in backticks inside a link stays as it is.

Linkify reads the names and their links from the file _symbols.json, in the folder of the site. When the config has api, each build writes this file before it builds the pages. An apidocs.py script writes it too. Set symbols only for an index that another script writes.

smalldocs decides whether linkify is on in this order:

  1. linkify, if you set it. linkify: true turns it on, and linkify: false turns it off.
  2. api.linkify, if you set it.
  3. Otherwise, linkify is on when api has a packages list.

A _quarto.yml

smalldocs looks for _smalldocs.yml first. If the folder has no _smalldocs.yml, smalldocs reads _quarto.yml. If the folder has both files, smalldocs reads only _smalldocs.yml, and gives a warning.

A _quarto.yml has the same project and website sections. Two parts are in other places:

  • The options of a page are under format.html.
  • The options of smalldocs are under smalldocs:. Quarto ignores a top-level key that it does not know, so Quarto can still build the project.
format:
  html:
    theme: cosmo
    toc: true
smalldocs:
  linkify: true
  api:
    packages: [mypkg]

To move to _smalldocs.yml, rename the file. Move the keys of format.html and of smalldocs: to the top level. Then remove format and filters. If you write format, smalldocs or filters in _smalldocs.yml, the build gives a warning and does not read the key.

Lua filters

smalldocs runs no Lua. Its linkify is Python code. It does the same work as the Lua filter linkify.lua did for Quarto.

In a _quarto.yml, a file with the name linkify.lua in filters also turns on linkify, as step 3 of the list above. smalldocs does not read the file linkify.lua, and does not run it. The name only tells smalldocs to turn on linkify. The entry can be a path, such as filters/linkify.lua, or {path: linkify.lua}.

smalldocs does not run the other filters in filters. It gives a warning for each of them, but not for the entry quarto, which only marks where the filters of Quarto run.