smalldocs.site

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

class Page

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

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
`draft`	bool	`False`	Whether it is a draft that `draft-mode` keeps: `visible` or `unlinked`

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 ThemeFile

source

ThemeFile(name: str, mode: str, src: Path, href: str, ext: extensions.Extension | None = None)

One theme stylesheet of the site: where its CSS comes from, and where the site keeps it.

Parameter	Type	Default	Description
`name`	str	required	The theme, as `theme` names it: a Bootswatch theme, a CSS file, or an extension
`mode`	str	required	`light` or `dark`
`src`	Path	required	The CSS file to copy
`href`	str	required	Its path in `site_libs`, such as `themes/cosmo.min.css` or `themes/ac215/ac215.css`
`ext`	extensions.Extension \| None	`None`	The extension it comes from, if any

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

source

Site.draft_mode() -> str

Read website.draft-mode: gone leaves drafts out, unlinked builds them with no links to them, visible builds them as other pages.

Parameter	Type	Default	Description
returns	str		`gone`, `unlinked` or `visible`

Site.is_draft

source

Site.is_draft(page: Page) -> bool

Say whether a page is a draft: draft: true in its options, or its path in website.drafts.

Parameter	Type	Default	Description
`page`	Page	required	A page that has been read
returns	bool		Whether the page is a draft

Site.hidden

source

Site.hidden(page: Page) -> bool

Say whether a page is an unlinked draft, which is built but which nothing lists.

Parameter	Type	Default	Description
`page`	Page	required	A page of the site
returns	bool		Whether the navigation, listings, search, the sitemap and feeds leave the page out

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[ThemeFile]

Find the themes in theme: one name, a list, or light: and dark:. A name is a Bootswatch theme, a CSS file, or an extension.

Parameter	Type	Default	Description
returns	list[ThemeFile]		One for each theme stylesheet the site uses: light first, then dark

Site.theme_file

source

Site.theme_file(name: str, mode: str) -> ThemeFile

Find one theme’s CSS: a file in the project, then an extension in _extensions/, then a Bootswatch theme.

Parameter	Type	Default	Description
`name`	str	required	A name in `theme`: a CSS file, an extension, or a Bootswatch theme
`mode`	str	required	`light` or `dark`
returns	ThemeFile		Where its CSS comes from and goes to

Site.theme_extra

source

Site.theme_extra(key: str) -> tuple[Path, PurePosixPath] | None

Find the theme’s logo or favicon, which the site uses only when it sets none.

Parameter	Type	Default	Description
`key`	str	required	`logo` or `favicon`
returns	tuple[Path, PurePosixPath] \| None		The file, and its path in the output folder, such as `site_libs/themes/ac215/logo.png`; None when the site sets its own

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_search

source

Site.write_search() -> None

Write search.json: one entry for each section of each page, as Quarto’s search reads.

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