smalldocs.listing

Listings, as in Quarto: a page that lists other pages as a list, a grid of cards or a table, with categories and a feed.

options

source

options(page: Page) -> list[dict]

Read listing:: true, a glob, a dict, or a list of dicts.

Parameter Type Default Description
page Page required A page with listing: in its front matter
returns list[dict] One dict of options for each listing on the page, each with an id

words

source

words(text: str) -> int

Count the words of a page’s HTML.

Parameter Type Default Description
text str required HTML
returns int How many words the HTML holds

first_paragraph

source

first_paragraph(page: Page, limit: int) -> str

Find the description of a page with none: its first paragraph of text, as Quarto does.

Parameter Type Default Description
page Page required A rendered page
limit int required The longest description, in characters
returns str Its first paragraph as plain text, cut at the limit

item_image

source

item_image(site: Site, item: Page, on: Page) -> str

Find the picture of a listed page: image: in its front matter, else the first picture in it.

Parameter Type Default Description
site Site required The site
item Page required The page being listed
on Page required The listing page
returns str The link to the item’s picture from the listing page, or empty

sort_items

source

sort_items(items: list[dict], spec: object) -> list[dict]

Sort the items as sort: says; the default is newest first, then by title.

Parameter Type Default Description
items list[dict] required The items, each with its fields
spec object required sort:: such as date desc, a list of those, or false
returns list[dict] The items in order

gather

source

gather(site: Site, page: Page, opts: dict) -> list[Page]

Find the pages a listing lists: contents globs relative to the listing page, else every page in its folder and below.

Parameter Type Default Description
site Site required The site
page Page required The listing page
opts dict required The listing’s options
returns list[Page] The pages it lists

item_fields

source

item_fields(site: Site, item: Page, on: Page, opts: dict) -> dict

Read what a listing shows of a page.

Parameter Type Default Description
site Site required The site
item Page required A listed page
on Page required The listing page
opts dict required The listing’s options
returns dict Everything a listing shows of the page, and the values it sorts by

data_attrs

source

data_attrs(it: dict, index: int) -> str

Write the data the listing script reads: categories, sort keys and search text.

Parameter Type Default Description
it dict required A listed item, with its fields
index int required Its place in the listing
returns str The data- attributes that the listing script filters and sorts by

cats_html

source

cats_html(it: dict) -> str

Write an item’s categories; a click filters the listing to one.

Parameter Type Default Description
it dict required A listed item, with its fields
returns str The item’s categories, each one a filter

img_html

source

img_html(it: dict, opts: dict) -> str

Write an item’s picture, at image-height when given.

Parameter Type Default Description
it dict required A listed item, with its fields
opts dict required The listing’s options
returns str The item’s picture, or a placeholder

render_default

source

render_default(items: list[dict], fields: list[str], opts: dict) -> str

Write a default listing: date on the left, text in the middle, picture on the right.

Parameter Type Default Description
items list[dict] required The items, each with its fields
fields list[str] required The fields to show, in order
opts dict required The listing’s options
returns str The HTML of a default listing

render_grid

source

render_grid(items: list[dict], fields: list[str], opts: dict) -> str

Write a grid listing: one card for each page.

Parameter Type Default Description
items list[dict] required The items, each with its fields
fields list[str] required The fields to show, in order
opts dict required The listing’s options
returns str The HTML of a grid of cards

render_table

source

render_table(items: list[dict], fields: list[str], opts: dict) -> str

Write a table listing: one row for each page.

Parameter Type Default Description
items list[dict] required The items, each with its fields
fields list[str] required The fields to show, in order
opts dict required The listing’s options
returns str The HTML of a table listing

categories_html

source

categories_html(items: list[dict], style: object) -> str

Write the categories of a listing for the margin; a click filters the listing.

Parameter Type Default Description
items list[dict] required Every item of the page’s listings
style object required categories:: true, numbered, unnumbered or cloud
returns str The list of categories for the margin

expand

source

expand(site: Site, page: Page) -> None

Put the page’s listings into its HTML: in an empty div with the listing’s id, or at the end.

Parameter Type Default Description
site Site required The site, with every page rendered
page Page required A page with listing:

write_feeds

source

write_feeds(site: Site) -> None

Write an RSS feed for each listing with feed:, beside its page, when website.site-url is set.

Parameter Type Default Description
site Site required The site, with every page rendered