Configuration

Doxyte expects the config file to be in TOML format and to have the following fields:

• Required fields
  • rootdir
  • pages
• Optional fields
  • site-prefix
  • favicon
  • footer
  • custom-css
  • highlight-style

Required fields

The following fields must be present in the config file:

Root directory

This is the path to the directory containing the site content (markdown sources, images, etc.). For example:

rootdir = "src"

• The path is relative to the config file.
• If the config file is in the same directory as index.md etc., set rootdir = ".".

Pages

Each page is represented as a hash with keys path, title, and optionally icon (see Navbar icons below). For example:

pages = [
  { path = "index.md", title = "The Project" },
  { path = "usage/config.md", title = "Configuration" },
]

• The path must be relative to rootdir.

• The title doesn’t have to match the first heading on the page. You can use a shorter version to save some space in the navigation bar, for example.

  The titles get used in the page metadata (browser tab and bookmark name), in the navbar, and in the link to the next page at the bottom of the page.

• Be sure to include an index.md file in your list of pages, since that is what your readers will see when they first land on your site.

Optional fields

These fields are optional, as far as Doxyte is concerned. But site-prefix may be required for your links to work.

Site prefix

If your site is not hosted at the root of the domain, e.g. if the URL is www.example.com/project/ rather than project.example.com/, you have to set the site-prefix field to the path between the domain and the top-level index.html. For example:

site-prefix = "project"

This will change the link to the CSS file in the HTML output from /main.css to /project/main.css etc.

It does not affect any links in the page body content. So please use relative paths for internal links in your markdown sources.

Favicon

You can supply an image file to use as the site favicon (the icon next to the title in the browser tab). For example:

favicon = "static/logo.svg"

• The icon has to be in SVG format.
• Its file path must be relative to the config file.

Navbar icons

For top-level pages, you can display an icon instead of the title in the navigation bar¹, by setting the icon field in the relevant item in the pages list. For example:

pages = [
  { path = "index.md", title = "The Project", icon = "static/logo.svg" },
  ...
]

• The icon can be in any image format.
• Its file path must be relative to the config file.

Footer

The footer field is the place to define any text you want included in the footer of every page, e.g. copyright information, project links, etc. For example:

footer = "[Subscribe](https://example.com/rss/) for updates!"

• This text can be plain text or markdown.
• Tip: TOML supports multi-line strings.

Custom CSS

You can provide extra CSS rules to customise the styling of the site by specifying a path to a CSS file in the custom-css field. For example:

custom-css = "static/custom.css"

• The path must be relative to the config file.

• The rules in this file are applied on top of the default rules. E.g. to change just the accent colour and keep everything else the same:

  :root {
    --accent-hue: 350;
  }
  

Code highlighting style

If you want syntax highlighting for your code blocks, set the highlight-style field to one of the Chroma styles. For example:

highlight-style = "tango"

If you leave it out, your code blocks will remain untouched.