smalldocs.layout

The page around the content, in Quarto’s markup: head, navbar, sidebar, title block, table of contents, footer.

as_list

as_list(v: object) -> list

Make a config value that may be one item or a list into a list.

Parameter	Type	Default	Description
`v`	object	required	A config value
returns	list		The value as a list: None is empty, a single value is one item

nav_attrs

source

nav_attrs(c: dict) -> dict

Read the link attributes of a navigation entry.

Parameter	Type	Default	Description
`c`	dict	required	An entry of a navbar, sidebar, footer or tools, from the config
returns	dict		Its `target`, `rel`, `aria-label` and `id`, the ones it sets

css_value

source

css_value(v: object) -> str | None

Check a value before it goes into CSS: no <, >, {, }, ;, backslash or line break.

Parameter	Type	Default	Description
`v`	object	required	A value from the config, for a CSS property
returns	str \| None		The value, or None when it could break out of a style block

css_color

source

css_color(v: object) -> str | None

Turn a colour of the config into CSS: a Bootstrap name reads the theme’s variable.

Parameter	Type	Default	Description
`v`	object	required	A colour from the config: a Bootstrap name such as `light`, or a CSS colour
returns	str \| None		The CSS colour, or None

rgb_of

source

rgb_of(color: str) -> tuple[int, int, int] | None

Read the red, green and blue of a hex or rgb() colour.

Parameter	Type	Default	Description
`color`	str	required	A CSS colour: `#rgb`, `#rrggbb`, or `rgb(r, g, b)`
returns	tuple[int, int, int] \| None		Its red, green and blue, or None for another form

logo_images

source

logo_images(logo: object, alt: str = '') -> list[tuple[str, str, str]]

Read a logo of the config: one image, or one for the light mode and one for the dark mode.

Parameter	Type	Default	Description
`logo`	object	required	`logo` from the config: a path, `{path, alt}`, or `{light, dark}` where each is a path or `{path, alt}`
`alt`	str	`''`	`logo-alt`, for an image with no `alt` of its own
returns	list[tuple[str, str, str]]		(path, alt text, extra class) for each image: `light-content` and `dark-content` for two modes

inline_md

source

inline_md(text: str, site: Site, page: Page | None) -> str

Render a short piece of Markdown from the config, such as a footer.

Parameter	Type	Default	Description
`text`	str	required	Markdown on one line, from the config
`site`	Site	required	The site, to rewrite links
`page`	Page \| None	required	The page the text goes on
returns	str		HTML without the paragraph around it

format_date

source

format_date(d: date | None, fmt: str | None = None) -> str

Write a date in one of Quarto’s formats: the default is MMMM D, YYYY.

Parameter	Type	Default	Description
`d`	date \| None	required	A date
`fmt`	str \| None	`None`	Quarto’s `date-format`, such as `MMMM D, YYYY`, or None for that one
returns	str		The date as text

class Item

source

Item(text: str, href: str = '', page: Page | None = None, children: list[Item] = <factory>, section: bool = False, icon: str = '', sep: bool = False, attrs: dict = <factory>)

One entry of a sidebar or navbar: a page, a link, a section or a separator.

Parameter	Type	Default	Description
`text`	str	required	What the entry says (HTML-safe text)
`href`	str	`''`	Where it goes: an output path from the root, or a full URL; empty for a section with no page
`page`	Page \| None	`None`	The page it is, if it is one
`children`	list[Item]	`<factory>`	The entries of a section or menu
`section`	bool	`False`	Whether it is a section
`icon`	str	`''`	A Bootstrap icon name
`sep`	bool	`False`	Whether it is a separator line
`attrs`	dict	`<factory>`	The link’s `target`, `rel`, `aria-label` and `id`, from the config

Item.pages

source

Item.pages() -> list[Page]

List the pages under this entry, in order.

Parameter	Type	Default	Description
returns	list[Page]		Every page in this entry and below it, in order

Item.contains

source

Item.contains(page: Page) -> bool

Say whether a page is in this entry.

Parameter	Type	Default	Description
`page`	Page	required	A page
returns	bool		Whether the page is here or below

class SiteNav

source

SiteNav(site: Site)

The site’s navigation: its sidebars, its navbar, and the order of pages.

Parameter	Type	Default	Description
`site`	Site	required	The site, with its pages read and rendered

SiteNav.page_item

source

SiteNav.page_item(page: Page, text: str | None = None, icon: str = '', attrs: dict | None = None) -> Item

Make the entry for a page.

Parameter	Type	Default	Description
`page`	Page	required	The page
`text`	str \| None	`None`	The text of the entry; None for the page’s title
`icon`	str	`''`	A Bootstrap icon name, or empty
`attrs`	dict \| None	`None`	The link’s `target`, `rel`, `aria-label` and `id`
returns	Item		An entry for a page

SiteNav.listed

source

SiteNav.listed() -> list[Page]

List the pages that the sidebar and the navbar may show: every page but an unlinked draft.

Parameter	Type	Default	Description
returns	list[Page]		The pages that navigation may show

SiteNav.glob

source

SiteNav.glob(pattern: str) -> list[Page]

Find the pages that match a glob, ordered by order:, then index first, then path.

Parameter	Type	Default	Description
`pattern`	str	required	A glob over source paths, from the config
returns	list[Page]		The pages that match, in Quarto’s order

SiteNav.auto

source

SiteNav.auto(pattern: str = '*') -> list[Item]

Make Quarto’s auto tree: one section for each folder, titled by its index page.

Parameter	Type	Default	Description
`pattern`	str	`'*'`	A glob, or `*` for every page
returns	list[Item]		A tree of entries for the pages under a pattern

SiteNav.tree_items

source

SiteNav.tree_items(node: dict, path: PurePosixPath) -> list[Item]

Turn one folder of the auto tree into entries.

Parameter	Type	Default	Description
`node`	dict	required	One folder of the tree: its pages and its subfolders
`path`	PurePosixPath	required	The folder’s path
returns	list[Item]		The entries of one folder of the auto tree

SiteNav.expand

source

SiteNav.expand(contents: list, nav: bool = False) -> list[Item]

Read a contents: list: paths, globs, auto, sections, links and separators.

Parameter	Type	Default	Description
`contents`	list	required	The `contents:` of a sidebar or section, or a navbar side
`nav`	bool	`False`	Whether these are navbar entries, where `menu:` makes a dropdown
returns	list[Item]		The entries

SiteNav.sidebar_for

source

SiteNav.sidebar_for(page: Page) -> dict | None

Find the sidebar to show on a page.

Parameter	Type	Default	Description
`page`	Page	required	The page being laid out
returns	dict \| None		The sidebar that holds the page, else the first, else None

SiteNav.order

source

SiteNav.order(page: Page) -> list[Page]

List the pages of the page’s sidebar in order, for previous and next.

Parameter	Type	Default	Description
`page`	Page	required	The page being laid out
returns	list[Page]		The pages in the order of the page’s sidebar

SiteNav.crumbs

source

SiteNav.crumbs(page: Page) -> list[Item]

Find the breadcrumbs of a page: the sections that hold it.

Parameter	Type	Default	Description
`page`	Page	required	The page being laid out
returns	list[Item]		The sections above the page, then the page

is_glob_str

source

is_glob_str(s: str) -> bool

Say whether a string is a glob.

Parameter	Type	Default	Description
`s`	str	required	A string from the config
returns	bool		Whether the string has glob characters

class Layout

source

Layout(site: Site, nav: SiteNav, page: Page)

Lay out one page.

Parameter	Type	Default	Description
`site`	Site	required	The site
`nav`	SiteNav	required	Its navigation
`page`	Page	required	The page to lay out

Layout.href

source

Layout.href(item_href: str) -> str

Write an entry’s link from this page: an output path from the root, or a link as given in the config.

Parameter	Type	Default	Description
`item_href`	str	required	An entry’s link: an output path, or a link from the config
returns	str		The link from this page

Layout.root_rel

source

Layout.root_rel(href: str) -> str

Make a link from the config start at the project root.

Parameter	Type	Default	Description
`href`	str	required	A link from the config
returns	str		A config link, made to start at the root

Layout.logo

source

Layout.logo(own: object, alt: str = '') -> list[tuple[str, str, str]]

Find the logo: the site’s own, or else the one its theme extension gives.

Parameter	Type	Default	Description
`own`	object	required	The logo that the site sets, if any: a path, or a mapping such as `{light, dark}`
`alt`	str	`''`	`logo-alt`, the text of an image with no `alt` of its own
returns	list[tuple[str, str, str]]		(link, alt text, extra class) for each image: the site’s, else the theme’s; empty when there is none

Layout.logo_html

source

Layout.logo_html(own: object, alt: str) -> str

Write the logo: one image, or an image for the light mode and one for the dark mode.

Parameter	Type	Default	Description
`own`	object	required	The logo that the site sets, if any
`alt`	str	required	`logo-alt`
returns	str		The images, or empty when there is no logo

Layout.icon

source

Layout.icon(name: str) -> list

Make a Bootstrap icon.

Parameter	Type	Default	Description
`name`	str	required	A Bootstrap icon name, or empty
returns	list		An icon element, or nothing

Layout.option

source

Layout.option(key: str) -> object

Read an option of the page, or else of website:.

Parameter	Type	Default	Description
`key`	str	required	An option that a page or `website:` can set, such as `back-to-top-navigation`
returns	object		The page’s value, else the website’s

Layout.head

source

Layout.head() -> Head

Make the head: title, meta, the theme, icons, our CSS, the site’s CSS, and maths when the page has some.

Parameter	Type	Default	Description
returns	Head		The `<head>` element

Layout.absolute

source

Layout.absolute(img: object) -> str

Write the full URL of the page’s image, for Open Graph and Twitter.

Parameter	Type	Default	Description
`img`	object	required	An image path from the front matter or the config
returns	str		Its full URL, from `website.site-url`

Layout.page_style

source

Layout.page_style() -> str

Turn mainfont, monofont, fontsize, linestretch, linkcolor, backgroundcolor, fontcolor and max-width into CSS variables.

Parameter	Type	Default	Description
returns	str		CSS that sets the page’s fonts, colours and width, or empty

Layout.twitter_card

source

Layout.twitter_card(full: str, desc: object, img: object) -> list

Make the Twitter card tags from website.twitter-card: true, or card-style, creator, site, title, description and image.

Parameter	Type	Default	Description
`full`	str	required	The title of the page, as the browser tab shows it
`desc`	object	required	The description of the page, or None
`img`	object	required	The image of the page, or None
returns	list		The `twitter:` meta tags, or nothing

Layout.analytics

source

Layout.analytics() -> list

Make Google Analytics’ gtag scripts from website.google-analytics: a tracking id, or tracking-id, anonymize-ip and storage.

Parameter	Type	Default	Description
returns	list		The Google Analytics scripts, or nothing

Layout.comments

source

Layout.comments() -> dict

Read comments: the website’s, merged with the page’s; comments: false on a page turns them off.

Parameter	Type	Default	Description
returns	dict		The comment services of the page: `giscus`, `utterances`, `hypothesis`

Layout.hypothesis

source

Layout.hypothesis() -> list

Make the scripts of Hypothesis, the annotation service: comments.hypothesis is true or its options.

Parameter	Type	Default	Description
returns	list		The scripts of Hypothesis, in the head, or nothing

Layout.comment_threads

source

Layout.comment_threads() -> list

Make the comment threads of giscus or utterances, with their options.

Parameter	Type	Default	Description
returns	list		The scripts of giscus and utterances, after the page’s content, or nothing

Layout.offset

source

Layout.offset() -> str

Find the path from the page’s folder up to the root.

Parameter	Type	Default	Description
returns	str		The path from the page up to the root, such as `../`

Layout.includes

source

Layout.includes(key: str) -> list[str]

Read include-in-header, include-before-body or include-after-body: files, or text: entries.

Parameter	Type	Default	Description
`key`	str	required	`include-in-header`, `include-before-body` or `include-after-body`
returns	list[str]		The text of each include

Layout.search_on

source

Layout.search_on() -> bool

Say whether the site has search: on, unless website.search: false.

Parameter	Type	Default	Description
returns	bool		Whether the site shows a search box

Layout.search_opts

source

Layout.search_opts() -> dict

Read the options of website.search, when it is a mapping.

Parameter	Type	Default	Description
returns	dict		The options of `website.search`, or an empty dict

Layout.search_where

source

Layout.search_where() -> str | None

Find where the search box goes: the navbar, unless search.location: sidebar or the site has no navbar.

Parameter	Type	Default	Description
returns	str \| None		`navbar`, `sidebar`, or None for no search box

Layout.nav_item

source

Layout.nav_item(it: Item, in_menu: bool = False) -> Li

Make one navbar entry: a link, or a dropdown menu.

Parameter	Type	Default	Description
`it`	Item	required	The entry
`in_menu`	bool	`False`	Whether it is inside a dropdown menu
returns	Li		The navbar entry

Layout.tool_attrs

source

Layout.tool_attrs(t: dict) -> dict

Read the attributes of a tool’s link: its label, from aria-label, text or icon, and target, rel and id.

Parameter	Type	Default	Description
`t`	dict	required	A tool from the config: `icon`, `href` or `url`, `text`, and link attributes
returns	dict		The tool link’s `aria-label`, `target`, `rel` and `id`

Layout.navbar

source

Layout.navbar() -> list

Make the navbar: the title, the left and right entries, tools, the theme toggle and search.

Parameter	Type	Default	Description
returns	list		The navbar’s elements, or nothing when there is none

Layout.search_box

source

Layout.search_box() -> Div

Make the search box; smalldocs.js fills the results. search.type: overlay shows an icon that opens the box.

Parameter	Type	Default	Description
returns	Div		The search box

Layout.side_item

source

Layout.side_item(it: Item, depth: int) -> Li

Make one sidebar entry: a page, a link, or a section that folds.

Parameter	Type	Default	Description
`it`	Item	required	The entry
`depth`	int	required	How deep it sits in the sidebar
returns	Li		The sidebar entry

Layout.sidebar_part

source

Layout.sidebar_part(key: str) -> list

Make sidebar.header or sidebar.footer: Markdown, or a file of Markdown, rendered.

Parameter	Type	Default	Description
`key`	str	required	`header` or `footer`
returns	list		The part’s element, or nothing

Layout.panel_look

source

Layout.panel_look(opts: dict, name: str, where: str) -> tuple[str, dict]

Read background, foreground and border of the sidebar or the footer: CSS variables on it, and its classes.

Parameter	Type	Default	Description
`opts`	dict	required	`website.sidebar` or `website.page-footer`
`name`	str	required	`sidebar` or `footer`, for the classes and the variables
`where`	str	required	The option’s name in a warning, such as `page-footer`
returns	tuple[str, dict]		Classes to add to the panel, and its attributes

Layout.sidebar_html

source

Layout.sidebar_html(toc: list | None = None) -> list

Make the sidebar, with the site title and search when there is no navbar.

Parameter	Type	Default	Description
`toc`	list \| None	`None`	A table of contents to put in the sidebar, for `toc-location: left`
returns	list		The sidebar’s elements, or nothing when there is none

Layout.secondary_nav

source

Layout.secondary_nav() -> list

Make the narrow-screen bar that opens the sidebar, with the breadcrumbs.

Parameter	Type	Default	Description
returns	list		The bar’s elements, or nothing when there is no sidebar

Layout.crumbs_html

source

Layout.crumbs_html() -> list

Make the breadcrumbs: the sections that hold the page.

Parameter	Type	Default	Description
returns	list		The breadcrumbs’ elements, or nothing

Layout.title_block

source

Layout.title_block() -> list

Make the title block: title, subtitle, categories, description, authors, date and keywords.

Parameter	Type	Default	Description
returns	list		The title block’s elements

Layout.category_link

source

Layout.category_link(cat: str) -> str

Link a category to the listing page that lists this page, filtered to it, as Quarto does.

Parameter	Type	Default	Description
`cat`	str	required	A category of the page
returns	str		HTML: the category, linked to the listing that shows it

Layout.toc_location

source

Layout.toc_location() -> tuple[str | None, bool]

Read toc-location: right, left, body, left-body or right-body.

Parameter	Type	Default	Description
returns	tuple[str \| None, bool]		`left`, `right` or None for the table beside the text; whether one is in the body too

Layout.toc_expand

source

Layout.toc_expand() -> int | None

Read toc-expand: true shows every level, false the top level, a number that many levels.

Parameter	Type	Default	Description
returns	int \| None		How many levels show before the reader scrolls to a section; None shows every level

Layout.toc

source

Layout.toc(body: bool = False, ids: bool = True, extra: list | None = None) -> list

Make the table of contents from the page’s headings, to toc-depth (3).

Parameter	Type	Default	Description
`body`	bool	`False`	The table in the text, `toc-location: body`, with plain links
`ids`	bool	`True`	Give the links their `toc-` ids; a second table on the page has none
`extra`	list \| None	`None`	More elements at its end, such as `other-links`
returns	list		The table of contents’ elements, or nothing

Layout.extra_links

source

Layout.extra_links() -> list

Make other-links and code-links: lists of links under the table of contents, as Quarto writes them.

Parameter	Type	Default	Description
returns	list		The lists of `other-links` and `code-links`, or nothing

Layout.repo_actions

source

Layout.repo_actions() -> list

Make the repository links under the table of contents: edit, source, issue.

Parameter	Type	Default	Description
returns	list		The links’ elements, or nothing

Layout.page_navigation

source

Layout.page_navigation() -> list

Make the links to the previous and next pages of the sidebar, when page-navigation is on.

Parameter	Type	Default	Description
returns	list		The links’ elements, or nothing

Layout.back_to_top

source

Layout.back_to_top() -> list

Make Quarto’s Back to top link, when back-to-top-navigation is on; smalldocs.js shows it as the reader scrolls up.

Parameter	Type	Default	Description
returns	list		The link, or nothing

Layout.license_html

source

Layout.license_html(lic: object) -> str

Write the licence: a Creative Commons name links to its deed, as Quarto does.

Parameter	Type	Default	Description
`lic`	object	required	`license`: a Creative Commons name such as `CC BY`, a URL, text, or `{text, url}`
returns	str		HTML for the Reuse section

Layout.appendix

source

Layout.appendix() -> list

Make Quarto’s appendix at the end of the page: Reuse, from license, and Copyright, from copyright.

Parameter	Type	Default	Description
returns	list		The appendix’s elements, or nothing

Layout.footer

source

Layout.footer() -> list

Make the footer from website.page-footer: one text, or left, center and right, with its background, foreground and border.

Parameter	Type	Default	Description
returns	list		The footer’s elements, or nothing

Layout.body_classes

source

Layout.body_classes(has_toc: bool) -> str

Name the layout in the body’s classes, as Quarto does.

Parameter	Type	Default	Description
`has_toc`	bool	required	Whether the page shows a table of contents
returns	str		The classes of `<body>`

Layout.pinned

source

Layout.pinned() -> bool

Read navbar.pinned, or with no navbar sidebar.pinned: smalldocs keeps the header on the screen unless one is false.

Parameter	Type	Default	Description
returns	bool		Whether the header stays on the screen as the reader scrolls

Layout.main_attrs

source

Layout.main_attrs() -> dict

Pass link-external-icon and link-external-filter to smalldocs.js, which marks the links to other sites.

Parameter	Type	Default	Description
returns	dict		Data attributes for `smalldocs.js` on `<main>`, or none

Layout.render

source

Layout.render() -> str

Put the page together.

Parameter	Type	Default	Description
returns	str		The whole HTML document

Layout.preview_script

source

Layout.preview_script() -> str

Make the script that smalldocs preview adds: it asks for the build number and reloads when it changes.

Parameter	Type	Default	Description
returns	str		JavaScript that reloads the page when the site is rebuilt

page

source

page(site: Site, nav: SiteNav, p: Page) -> str

Lay out one page.

Parameter	Type	Default	Description
`site`	Site	required	The site
`nav`	SiteNav	required	Its navigation
`p`	Page	required	The page to lay out
returns	str		The whole HTML document

search_options

source

search_options(site: Site) -> str

Write the search options.

Parameter	Type	Default	Description
`site`	Site	required	The site
returns	str		The options for the search script, as JSON