Customization

Table of contents

  1. Color schemes
  2. Custom schemes
    1. Define a custom scheme
    2. Use a custom scheme
  3. Override SCSS
    1. Custom TOC Heading
    2. Custom Footer
    3. Custom Head
    4. Custom Header
    5. Custom Nav Footer
    6. Custom Search Placeholder
  4. Custom layouts

Color schemes

Dokumentaro includes two color schemes: light (default), and dark.

To enable a color scheme, set the site.color_scheme variable in wmk_config.yaml.

Use the color switcher at the top right to switch between them and set your preference. It can be disabled by setting site.color_scheme_switcher to false.

Custom schemes

Define a custom scheme

You can add custom schemes. This involves

  1. Creating a new file containing color-related SCSS variables in the directory assets/scss/color_schemes. The filename should start with an underscore. Let's call it _mycolors.scss.
  2. Creating a new appropriately named filei in assets/scss, e.g. d9o-mycolors.scss. The contents should be similar to that of d9o-light.scss and d9o-dark.scss, except that you @import "color_schemes/mycolors" instead of color_schemes/light or color_schems/dark.

Aside from the variables referenced in the two built-in color schemes you might also want to override some of the variables in assets/scss/support/_variables.scss.

Use a custom scheme

After having created a custom color scheme, you can use it by setting the site.color_scheme variable to your chosen name.

site:
  color_scheme: foo

Override SCSS

You can override or extend Dokumentaro's SCSS rules at three different stages by creating files in assets/scss/custom/:

  • _site_vars.scss: This file is imported at the very start.
  • _setup.scss: This file is imported after variables and mixins have been loaded, but before the color scheme settings, and thus before any CSS classes have been defined.
  • _custom: This file is imported at the end. New CSS classes should be placed here.

Custom TOC Heading

The file templates/base/toc_heading_custom.mc can be overridden to change the heading for the links to child pages shown below the main body of the page. By default, this is More information.

The file templates/base/footer_custom.mc can be overridden to change the content appearing at the bottom of every page's main content. See also Configuration - Footer content.

Custom Head

Any HTML added to the file templates/base/head_custom.mc will be inserted before the closing <head> tag.

Custom Header

Content added to templates/base/header_custom.mc appears at the top of every page's main content between the site search and auxiliary links (if they are enabled) or theme switcher (if they are not). If site.search_enabled and site.color_scheme_switcher were set to false and site.aux_links not set, the content of header_custom.mc would expand to occupy the entire space to the right of the site name/logo.

Any content added to the file templates/base/nav_footer_custom.mc will appear at the bottom left of the page below the site's navigation. By default an attribution to Dokumentaro is displayed here.

Custom Search Placeholder

The search placeholder can be set via the site.search_placeholder configuration variable. By default it is Search this website.

Custom layouts

Advanced

Creating custom layouts allows you to change most aspects of Dokumentaro's functionality. This requires some Python and/or Mako knowledge.

Having created a new layout, you would select it in the frontmatter of the relevant pages, or perhaps in content/index.yaml, in order to make it the default layout for all pages.

Tags