From Quarto

What is different from Quarto, and how to check a project before you move it.

smalldocs builds the website part of Quarto. A project that uses only that part builds with either tool. The two builds give the same pages, the same anchors and the same links.

Check a project first:

smalldocs check docs

The command builds the site into a temporary folder. Then it lists what smalldocs does not read:

If the command finds anything, its exit code is 1.

What works

smalldocs reads most of the options of Quarto for a website. The configuration lists them, with the default of each. Writing pages shows the Markdown that smalldocs reads. This Markdown includes callouts, tabsets, figures, table captions, footnotes, the margin, maths, diagrams and shortcodes.

A site also gets listings, search, a light and a dark theme, comments and Google Analytics, as in Quarto. A notebook shows its saved outputs, with the options of its cells. See Notebooks.

What smalldocs does not do yet

smalldocs gives a warning for each of these options, or shows the Markdown as text:

Quarto smalldocs
Cross-references, such as @fig-a, @tbl-a, @sec-a and @eq-a, with numbers, and the crossref options Not read. Write a link to the id, such as [the table](#tbl-a)
Figure divs, ::: {#fig-a}, and subfigures Not read. A picture alone in its paragraph is a figure
Labels on equations, $$...$$ {#eq-a} Not read
A negative width in layout, for an empty space Not read. The other widths work
Code annotations, # <1> Not read
Example lists, (@), and line blocks, | Not read
lightbox, footnotes-hover, reader-mode, code-tools, highlight-style Not read
website.announcement, body-header, body-footer, margin-header, margin-footer, cookie-consent Not read
listing: image-placeholder, image-align, image-lazy-loading, field-types, field-links, field-required Not read
search: copy-button, collapse-after, show-item-context, merge-navbar-crumbs Not read
_brand.yml Not read. Use a theme, or the options for fonts and colours
Citations and a bibliography Not read

What smalldocs will not do

Quarto smalldocs
PDF, Word, slides, books, manuscripts Websites only. A book is built as a website
Runs {python}, {r} and {ojs} cells, with jupyter, freeze, cache, engine and df-print Shows the code and runs nothing. A notebook shows its saved outputs. Each of these options gives a warning
Compiles .scss themes Takes any Bootswatch theme, your CSS, and the CSS of a theme extension. See Themes
embed-resources and self-contained Not read. The pages load the stylesheets and the scripts from site_libs
Lua filters Runs no Lua. The linkify of smalldocs does the work of linkify.lua, but links only names that look like code. See Lua filters
Graphviz {dot} blocks Not read. Make an SVG with Graphviz, and use it as a picture
listing.template, about pages, Algolia search Not read. A listing is a default, grid or table listing, and search reads search.json
Grid tables and raw LaTeX smalldocs check reports them. Write a pipe table

Different defaults

Two defaults of smalldocs differ from Quarto. They stay, so that sites that exist do not change:

  • The key / goes to the search box. Quarto also uses f and s. See Search.
  • A figure starts at the left of the column. Quarto puts it in the centre. See Figures.

What is the same

  • smalldocs reads _quarto.yml, and merges it with _metadata.yml and front matter in the same order as Quarto.
  • smalldocs makes the ids of headings by the rules of Pandoc. So links and anchors that were written for Quarto keep working.
  • A link to a .qmd, .md or .ipynb file becomes a link to the .html file. A link that starts with / starts at the root of the project.
  • The HTML of the page has the same classes and ids as in Quarto, such as #quarto-sidebar, #TOC, .callout-note, .panel-tabset and .quarto-grid-item. So most CSS that was written for a Quarto site works.
  • smalldocs runs pre-render and post-render with the same environment variables as Quarto.

Move a project

  1. Run smalldocs check, and fix what it lists.
  2. Run smalldocs preview. Compare each page with the page that Quarto made.
  3. In the recipe that builds the site, change quarto render to smalldocs render. Change quarto publish gh-pages to smalldocs publish gh-pages.
  4. If a script of the project writes its API reference, use the api section of smalldocs instead. Remove the script from pre-render. See The API reference.
  5. When Quarto no longer builds the project, change _quarto.yml to _smalldocs.yml. See A _quarto.yml.