The configuration

project

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 these files:

• the files and folders whose names start with _ or .
• the output folder
• the folders env, venv, renv, node_modules, site-packages and __pycache__
• each file with the name README, such as README.md or readme.qmd

To build a page that one of these rules leaves out, list it in render.

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

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

Links in the navigation

An entry of the navbar, a menu, the tools, the sidebar or the footer can set these attributes of its link:

navbar:
  left:
    - text: Forum
      href: https://forum.example.com
      target: _blank                 # open the link in a new tab
      rel: noopener
      aria-label: The forum          # the text for a screen reader
      id: forum-link

Search

The search box is in the navbar. With no navbar, it is in the sidebar. These options change it:

website:
  search:
    location: sidebar                # navbar or sidebar
    type: overlay                    # textbox, or overlay: an icon that opens the box
    limit: 10                        # the number of results; 20 if you set none
    keyboard-shortcut: [f, /, s]     # the keys that go to the box

The key / goes to the search box when you set no keyboard-shortcut. Quarto uses f, / and s; write keyboard-shortcut: [f, /, s] to get the same keys. Ctrl-K and Cmd-K also go to the box. smalldocs does not read algolia and the other options of Quarto for search.

Drafts

A draft is a page that is not ready. A page with draft: true is a draft, and so is each page in website.drafts. website.draft-mode sets what a build does with a draft:

• gone, the default, leaves the draft out of the site.
• unlinked builds the draft, but the sidebar, the navbar, the listings, the search, the sitemap and the feeds leave it out. A reader with the address can open it.
• visible builds the draft as any other page.

website:
  draft-mode: unlinked
  drafts: [posts/next-post.qmd]

Comments

comments adds a service for comments to each page. Set it in website or in the options of a page. comments: false in the front matter of a page turns comments off on that page.

website:
  comments:
    giscus:
      repo: me/my-repo
      repo-id: R_kgDOABCDEF
      category: Announcements
      category-id: DIC_kwDOABCDEF

• giscus keeps comments in GitHub Discussions. It takes repo, repo-id, category, category-id, mapping, reactions-enabled, loading, input-position, language, and theme, which is a name or light and dark. The giscus website gives the ids.
• utterances keeps comments in GitHub issues. It takes repo, label, theme and issue-term.
• hypothesis lets readers write notes on the text. Give true, or the options of Hypothesis.

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. smalldocs reads theme only from the config of the project. It reads order only from the front matter of a page.

Options that smalldocs does not read

smalldocs gives a warning for each key of the config that it does not read. It checks the keys inside each section too, down to each entry of the navbar and the sidebar. So a key with a typing error does not go unseen:

warning: unknown key website.sidebar.stylee
warning: unknown key website.navbar.left[0].colour

In a _quarto.yml, each option under format.html that smalldocs does not read gives a warning too. Under execute, smalldocs reads echo, output and include. The other keys there are for running code, so each gives the warning below.

Front matter and a _metadata.yml file can hold keys of your own, such as version: 2. A shortcode such as meta can read them, so smalldocs gives no warning for them. It gives a warning only for an option of Quarto that it does not read, such as lightbox:

warning: guide/intro.qmd: lightbox is not read by smalldocs

Some options of Quarto tell it how to run the code of a page. They are jupyter, engine, knitr, freeze, cache, execute-dir, df-print, keep-ipynb, ipynb-filters and ipynb-shell-interactivity. smalldocs runs no code, so the warning for each of them says so:

warning: freeze is ignored: smalldocs runs no code

A warning does not stop the build. With smalldocs render --strict, the build ends with the exit code 1 when it gives a warning. Use --strict in the recipe that checks a project before a commit.

The options of smalldocs

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

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. Linkify links only names that look like code, such as a call, a dotted name or a class. A plain lowercase word, such as main, stays as code. See Links from the text.

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. See The index of names.

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 packages.

What a build writes

A build writes the pages, and these files, into the output folder:

• index.html, the home page, from index.qmd, index.md or index.ipynb at the top of the folder. The title of the site in the navbar links to it. A folder can have an index page too. A link to the folder opens it, and an auto section of the sidebar takes its title.
• search.json, the index of the search box. It has one entry for each section of each page, with the title of the section and its text. A page with search: false in its front matter is not in it.
• sitemap.xml, the list of pages for search engines, when site-url is set.
• site_libs, the stylesheets and the scripts of the site.
• A feed for each listing that asks for one, when site-url is set. See Listings.
• A copy of each file that a page links to, such as an image, and of the files of resources, css and favicon. Each copy keeps its path from the folder of the project.

With an api section, a build first writes the reference pages and _symbols.json into the folder of the project. Then it builds them as it builds the other pages. See The API reference.

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]

Under smalldocs:, theme names the theme that smalldocs uses, in place of format.html.theme. So Quarto can compile its Sass theme, and smalldocs can use the CSS of the same extension.

smalldocs also reads a custom format of an extension, such as format: tufte-html, as html. See Themes.

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.