Themes

Your website's layout and style is defined by the themes you chose.

You can create your own theme, or use an existing one.

Use existing themes

Your themes need to be stored in the themes directory, inside your website project directory.

Typically themes would be hosted in their own git repo, as well as your website. If that's the case, you can use git submodules to install a theme, like so:

mkdir themes
git submodule add \
    https://example.com/THEME_AUTHOR/THEME_REPO_NAME.git \
    themes/THEME_NAME

Alternatively, you can copy the theme directly inside your themes directory. Just check that the file structure respects what Rubedo expects to find.

Here is an example of a typical file hierarchy:

• config.toml
• content
  • some_page.md
  • some_other_page.md
• themes
  • my_theme
    • templates
      • index.html
      • __page__.html
      • __some_other_template__.html

Overriding a theme's template

To ensure ultimate freedom in creating a website, it is entirely possible to override a theme's template, without having to edit it directly.

To some extent, themes can support this directly, by providing supported options to facilitate this, but it is not necessary.

You can simply override an existing template by either cascading a second or third (or n-th) theme after your main one, or by adding your template overrides in a templates directory inside your website's project directory. This is explained in the configuration keys documentation, under the themes key description.

If a theme supports this, they might provide "injectable" templates, that is templates that are typically empty by default, and that you can just easily override, thus adding content or customizations in a specific place inside an existing template.

Creating your own theme

A theme's structure is fairly simple, the theme's project directory should contain a templates folder, inside of which you can add your templates.

Templates of which the filename begins with __ (double underscore) are not rendered as their own pages, meaning they will instead be used as meta-templates that can be imported from other templates.

The one exception is a template called __page__.html. This will be used by default to render markdown content.

To start out, you can use Rubedo's very simple default theme as a base, or Magnum Opus, the theme used for this very website.

You can refer to the templating documentation for further information on how to do templating.