Templating

Rubedo uses the Tera template engine. You can refer to its documentation for how to actually use it to create your own theme.

Context

Inside your templates you can use the site and page variables, provided by the context. Here's a rundown of what they contain.

• site: Represents the entire website, and is always available in the context.
  • config: Represents the config.toml file of the website. The description for the various sub-keys can be found in the configuration docs
  • pages: List of pages available in your website, each corresponding to a markdown file (indified by the .md file extension) inside the content directory. Each page contains the same data detailed in the page definition below.
• page: Represents the current page being rendered. For obvious reasons, this is only available when rendering a page inside the content directory.
  • title: Title of the page, as specified in the frontmatter. This defaults to the file name.
  • content: String containing the raw content of the markdown file.
  • html: Rendered HTML generated from the markdown file. When displaying it inside a Tera template, it might be a good idea to use the safe filter like so: {{ page.html | safe }}. Rubedo uses Comrak for rendering markdown.
  • url: Absolute URL of the page, prefixed with site.config.base_url if provided in the config.
  • template: Template file path (relative to the theme directory) to use for the page. Defaults to __page__.html.
  • weight: Weight of the page, for sorting purposes. Lower weight pages come before higher weight ones. Pages without a weight are always sorted after pages with a weight. Pages without a weight are sorted on their own by their url value.
  • datetime: Publish date of the page, parsed from the frontmatter.
  • relative_path: The path to the page, relative to the content directory, with the file extension from the template file used.
  • relative_path_no_ext: The path to the markdown file, relative to the content directory, minus the file extension.
  • extension: Generated page file extension, with leading dot.
  • skip: Boolean, if true, rendering of this page will be skipped. It will still be available in the context as an item inside site.pages.
  • data: Contains the values parsed from the frontmatter.
  • metadata: Contains the values parsed from the frontmatter.
    • This has been deprecated in 1.0.0 and will be removed in future versions; use the data object instead.

Filters, functions and tests

Provided by tera-contrib

You can find out more about tera-contrib on their docs.rs page

• b64_decode filter: Decodes a base64 string.
• b64_encode filter: Encodes a string to base64. Takes an optional url_safe bool parameter (false by default) if you want to use the URL SAFE b64 characters and a padded bool parameter on whether you want padding (true by default).
• date filter: Formats the given value using the given format if it can be parsed as a date/datetime. Takes:
  1. optional format argument, defaulting to %Y-%m-%d
  2. optional timezone argument, defaulting to not set
• is_after test: Tests whether a date is after another date. Errors if one of the values cannot be parsed as a date. Takes an optional inclusive argument defaulting to false to make this test be >= instead of >.
• is_before test: Tests whether a date is before another date. Errors if one of the values cannot be parsed as a date. Takes an optional inclusive argument defaulting to false to make this test be <= instead of <.
• now function: Returns the current datetime. You can pass an optional timezone name. Defaults to UTC if not provided.
• format filter: Formats a value using Rust's std::fmt format specifiers. Supports width, alignment, precision, sign, and zero-padding. Does NOT support radix specifiers (x, X, b, o) - only Display formatting.
• json_encode filter: Encodes a value as JSON. Takes an optional pretty boolean argument defaulting to false.
• get_random function: Get a random integer between the start (inclusive) and end (exclusive) parameters. Optionally takes a seed.
• shuffle filter: Shuffles a list, optionally taking a seed for reproducible shuffling.
• slug filter: Slugify the given value.
• urlencode filter: Percent-encodes reserved URI characters. Matches Python’s urllib.parse.quote behavior with / not escaped.
• urlencode_strict filter: Percent-encodes all non-alphanumeric characters. Stricter than urlencode - also encodes / and other typically safe characters.

Provided by Rubedo

• markdownify filter: Renders the given string as markdown
• thumbnail filter: Creates a thumbnail for the given local image; the value should be a path, relative to your website's static directory. Takes:
  • path: Path to where the thumbnails will be saved in the public directory
  • format: The image format for the generated thumbnail. Supports:
    • "preserve": Keep the input image's format
    • "jpg": JPEG format
    • "png": PNG format
• paginate function: Paginates the given list of pages into indices of a given size. Takes:
  • pages: List of pages to paginate
  • page_size: Up to how many pages per index should be shown
  • template: Which template should be used for rendering
  • dir: The output directory for the generated pages
  • empty_out: If the first rendered index page should not be returned (defaults to false)