Configuration

Your website needs to provide a configuration file named config.toml. It has to be placed in the root of your website project directory.

Following is a simple example configuration file, containing only the keys that are parsed by Rubedo directly.

title = "My website"
language = "en-US"
themes = [
    "my_cool_theme",
]
authors = [
    "Jane Doe",
    "John Doe",
]
codeblock_theme = "themes/Choco.tmTheme"
heading_ids = true
extensionless_pages = true
output_dir = "public"
static_dir = "static"

Custom data

You can add additional keys in your config.toml and make them accessible to your theme inside the data section.

Following is an example.

title = "My website"
language = "en-US"
theme = "my_cool_theme"
authors = [
    "Jane Doe",
    "John Doe",
]

[data]
some_arbitrary_number = 10
subtitle = "This website is very cool"
links = [
    {title="Home", url="/"},
    {title="About", url="/pages/about"},
    {title="Another cool website", url="https://example.com"},
]

[data.some_subkey]
foo = "bar"
lorem = "ipsum"

These values will then be accessible from inside template. For example, to access the subtitle value in the example above, you would use this in your template: {{site.config.data.subtitle}}.

Configuration keys

• base_url: Optional base URL of the website.
• title: The title of the website.
• language: The language code for your website. This is supposed to follow the conventions used for the HTML lang global attribute.
• authors: Array of strings, each representing an author of the website.
• heading_ids: Boolean, set to true to generate unique html id attributes for the headings in your markdown content.
• extensionless_pages: Boolean, set to true to generate ids for markdown headings and add anchor tags before the text. These will be invisible by default and need to be styled by the theme's CSS.
• codeblock_theme: File path relative to your website project directory, pointing to a .tmTheme file. This file will be used for syntax highlighting of code block elements in your markdown content. The provided theme should be compatible with syntect. Leave unset to disable syntax highlighting.
• output_dir: Directory path where the generated website content along with all static assets will be written.
• static_dir: Directory path that contains the static data that will be copied over to output_dir.
• themes: Array of strings, each should correspond to the directory name of a theme.
  • Themes need to be placed inside the themes directory in your website project directory.
  • The first theme listed acts as a base, any subsequent theme specified here overwrites any content provided by the previous theme.
    • Example: if you have your themes set as themes = [ "foo", "bar" ], with foo providing the template file index.html, if bar also provides a file named index.html, the final one used when rendering the website will be the index.html provided by theme bar.
  • It's worth noting that you can also place template files in a templates directory inside your website project directory. These templates will take precedence over any other theme.
• data: Freeform object, can contain whatever key you would like to use for your theme. Make sure to document these, particularly if you plan to release a theme for public consumption.