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

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)

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

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 = '') -> 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
returns	Item		An entry for a page

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

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_html

source

Layout.sidebar_html() -> list

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

Parameter	Type	Default	Description
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 and date.

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

source

Layout.toc() -> list

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

Parameter	Type	Default	Description
returns	list		The table of contents’ elements, 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.footer

source

Layout.footer() -> list

Make the footer from website.page-footer: one text, or left, center and right.

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