smalldocs.site

Build a website: find the pages, read their metadata, render them, lay them out, and write _site.

class Page

source

Page(src: PurePosixPath, out: PurePosixPath, front: dict, meta: dict, body: str, html: str = '', env: dict = <factory>, mtime: float = 0.0)

One page of the site: where it comes from and goes to, its options, and once rendered, its HTML.

Parameter Type Default Description
src PurePosixPath required The source, relative to the project root, such as guide/intro.qmd
out PurePosixPath required The output, relative to the output folder, such as guide/intro.html
front dict required The page’s own front matter
meta dict required Every option that applies to it: project, folder, then front matter
body str required Its Markdown, without the front matter (a notebook already turned into Markdown)
html str '' The rendered body
env dict <factory> What rendering found: headings, search text, maths, …
mtime float 0.0 When the source last changed

parse_date

source

parse_date(value: object, mtime: float = 0.0) -> date | None

Read a date as Quarto does: ISO text, a YAML date, today, now or last-modified.

Parameter Type Default Description
value object required The value of date:
mtime float 0.0 The source’s modification time, for last-modified
returns date | None The date, or None

is_glob

source

is_glob(s: str) -> bool

Say whether a path has glob characters.

Parameter Type Default Description
s str required A path, as written in the config
returns bool Whether the string has glob characters

rel

source

rel(target: PurePosixPath | str, page: Page | None) -> str

Write a link from a page to another output file, relative, as Quarto does.

Parameter Type Default Description
target PurePosixPath | str required A path relative to the output root
page Page | None required The page the link is written on; None for the root
returns str The path from the page to the target

class Site

source

Site(project: Project, quiet: bool = False, preview: bool = False)

A project being built.

Parameter Type Default Description
project Project required The project to build
quiet bool False Print nothing but errors
preview bool False Add the reload script for smalldocs preview

Site.say

source

Site.say(msg: str) -> None

Print a line, unless quiet.

Parameter Type Default Description
msg str required The line to print

Site.warn

source

Site.warn(msg: str) -> None

Keep a warning, once.

Parameter Type Default Description
msg str required The warning

Site.ignored

source

Site.ignored(path: Path) -> bool

Leave out files under _ or . folders, the output folder, and virtual environments.

Parameter Type Default Description
path Path required A file under the root
returns bool Whether a file is left out of the site

Site.walk

source

Site.walk() -> list[Path]

List the project’s files, in order, without the ones Quarto leaves out.

Parameter Type Default Description
returns list[Path] Every file under the root that is not left out

Site.discover

source

Site.discover() -> list[PurePosixPath]

Find the pages: project.render when it is given, else every .qmd, .md and .ipynb that is not left out.

Parameter Type Default Description
returns list[PurePosixPath] The sources of the pages to render

Site.read

source

Site.read(src: PurePosixPath) -> Page

Read a page’s source and options.

Parameter Type Default Description
src PurePosixPath required The page’s source, relative to the root
returns Page The page with its options, not yet rendered

Site.find_page

source

Site.find_page(target: PurePosixPath) -> Page | None

Find the page a path points at: the source itself, or a folder’s index page.

Parameter Type Default Description
target PurePosixPath required A path relative to the root: a source, an output, or a folder
returns Page | None The page for a source path, or a folder’s index

Site.resolve

source

Site.resolve(href: str, page: Page | None, record: bool = True) -> str

Rewrite a link: pages to their .html, /x from the root, and local files copied as resources.

Parameter Type Default Description
href str required A link as written in a page, or in the config
page Page | None required The page it is written on; None for the config, which is relative to the root
record bool True Note a broken link
returns str The link to write in the HTML

Site.run_scripts

source

Site.run_scripts(key: str, inputs: list[PurePosixPath]) -> None

Run project.pre-render or project.post-render, with Quarto’s environment variables.

Parameter Type Default Description
key str required pre-render or post-render
inputs list[PurePosixPath] required The pages being rendered

Site.load_symbols

source

Site.load_symbols() -> None

Read the name index that turns a name in backticks into a link: _symbols.json, when linkify is on.

Site.render_page

source

Site.render_page(page: Page) -> None

Render one page’s Markdown into HTML.

Parameter Type Default Description
page Page required The page to render

Site.check_output

source

Site.check_output() -> None

Refuse an output folder that a build must not empty: the project, a folder above it, or a folder that is not a built site.

Site.build

source

Site.build() -> int

Build the whole site into the output folder.

Parameter Type Default Description
returns int The number of pages written

Site.theme_files

source

Site.theme_files() -> list[tuple[str, str]]

Find the themes in format.html.theme: one name, a list, or light: and dark:.

Parameter Type Default Description
returns list[tuple[str, str]] (name, mode) for each theme stylesheet the site uses

Site.copy_assets

source

Site.copy_assets(nav: layout.SiteNav) -> None

Copy the theme, Bootstrap, the icons, search and smalldocs’ own CSS and JavaScript into site_libs.

Parameter Type Default Description
nav layout.SiteNav required The site’s navigation

Site.copy_resources

source

Site.copy_resources() -> None

Copy the files that pages link to, and project.resources, keeping their paths.

Site.walk_all

source

Site.walk_all() -> list[Path]

List every file, for resources, which may name a hidden file such as .nojekyll.

Parameter Type Default Description
returns list[Path] Every file under the root but the output folder, hidden ones too

Site.write_sitemap

source

Site.write_sitemap() -> None

Write sitemap.xml when website.site-url is set.

cell_defaults

source

cell_defaults(opts: dict) -> dict

Read the options that hide code or output in every cell of a page: echo: false, or execute: {echo: false}.

Parameter Type Default Description
opts dict required A page’s merged options
returns dict echo, output and include as the page and execute: set them

build

source

build(root: Path | str = '.', quiet: bool = False, preview: bool = False) -> Site

Load a project and build it.

Parameter Type Default Description
root Path | str '.' The project folder
quiet bool False Print nothing but errors and warnings
preview bool False Add the reload script, for smalldocs preview
returns Site The built site, with its warnings