Configuration

Dokumentaro supports several configuration parameters that can be defined in your site's wmk_config.yaml file. The default values for these settings are set by the theme.

Table of contents

  1. Site logo
  2. Site favicon
  3. Search
  4. Mermaid Diagrams
  5. Aux links
  6. Navigation sidebar
  7. Heading anchor links
  8. External navigation links
  9. Footer content
    1. Last edited
    2. Edit on GitHub
    3. Tags
  10. Color scheme
  11. Callouts
  12. Google Analytics

Set a url to a logo that will be displayed instead of the title.

site:
  logo: "/images/dokumentaro.png"

Site favicon

Set a url to a favicon that will be displayed by the browser.

site:
  favicon_ico: "/images/favicon.ico"

The default location for a favicon is the site root. Hence, you can leave this configuration variable unset if you place your favicon.ico file there.

Dokumentaro uses Pagefind for site search. It is enabled by default:

site:
  search_enabled: true
  search_placeholder: Search Dokumentaro

Warning

For site indexing by Pagefind to work, you must have npx installed on the computer where you build the site.

Mermaid Diagrams

The minimum configuration requires the key for version (from jsDelivr):

site:
  mermaid:
    # Version of mermaid library
    version: "11.4.1"

Provide a path instead of a version key to load the mermaid library from a local file.

site:
  # Aux links for the upper right navigation
  aux_links:
    - title: wmk on GitHub
      url: https://github.com/bk/wmk
  # Makes Aux links open in a new tab. Default is false
  aux_links_new_tab: false

Enable or disable the side/mobile menu globally using this option. The nav menu can also be selectively enabled or disabled using page variables or the minimal layout.

site:
  nav_enabled: true

Heading anchor links appear on hover over heading (h1-h6) tags in page content, allowing users to deep link to a particular heading on a page.

site:
  heading_anchors: true

External links can be added to the navigation through the nav_external_links option. See Navigation Structure for more details.

Footer content

The footer content is configured by addinng a file named base/footer_custom.mc to the templates/ directory. However, you can also affect it by specifying a few configuration settings:

Last edited

site:
  last_edit_timestamp: true
  last_edit_time_format: "%Y-%m-%d %H:%M"

The effect of these settings is to display a last edited time below the main body of the page.

Edit on GitHub

site:
  gh_edit_link: 'https://github.com/bk/dokumentaro/edit/main/docs/content'
  gh_edit_link_text: Edit this file on Github

Both options must be set in order for a link to be displayed.

The effect of these settings is to display a link below the main body that allows editing the source of the page. Despite the name, the link does not necessarily have to be on GitHub. It might e.g. point to GitLab or a private Gitea installation instead. Or you might use this for linking to a page for merely viewing the source (rather than editing it).

What is appended to the URL in gh_edit_link is the SELF_SHORT_PATH value, which is the path to the current content source, taking the content/ directory as root. To take an example, for the present file that value is /configuration.md.

Tags

In order to use tags in your documentation pages, two things must first be present:

In the first place, site.tags_enabled must be true (which it is by default):

site:
  tags_enabled: true

Secondly, you need a page defining the place where the list of tags will appear in the page hierarchy. For instance, here is a sample content/tags.md page:

---
title: Tags
layout: taxonomy
nav_order: 20
TAXONOMY:
  taxon: ['tags', 'tag']
  order: name
  name: tags
  name_singular: tag
  name_plural: tags
  detail_settings:
    relationship_description: are tagged with the tag
---

# Tags

All active tags on this site are listed below in alphabetical order.
Click on a tag to show a list of the pages tagged with it.

Without the tag page, Dokumentaro will not be able to link to the subpage for each tag, so the list of tags will not appear in the footer. The tag page must use the taxonomy layout (i.e. templates/base/taxonomoy.mhtml).

Currently, tags are not supported by Just the Docs because the design of Jekyll makes this difficult for documentation sites. The tags support by Dokumentaro is thus an extra feature relative to Just the Docs.

Color scheme

The color scheme setting supports "light" (or "default") and "dark". User-defined colorschemes are possible by adding SCSS files in assets/scss – see here for details.

site:
  color_scheme: dark

There is a related option for showing a color scheme switcher widget:

site:
  color_scheme_switcher: true

The option is true by default.

The switcher is located at the right edge of header if the screen is wide enough; otherwise it is at the bottom of the mobile menu. It consists of a sun or a moon symbol, depending on which color scheme is active. If you use a custom color scheme you should either alter or turn off this widget.

Callouts

Just the Docs has the concept of Callouts which are alerts or admonition blocks. You had to define the types you wanted in the configuration file for the site and specify the color and default title for each.

Dokumentaro, however, instead uses the adminition blocks markdown extension for python-markdown. The types of admonitions are defined in wmk_config.yaml in the following manner:

markdown_extensions_configs:
  pymdownx.blocks.admonition:
    types:
      # Defaults: note, attention, caution, danger, error, tip, hint, warning.
      # Adding abstract, bug, example, failure, important, info, new,
      # question, quote, success.
      - note
      - attention
      - caution
      - danger
      - error
      - tip
      - hint
      - warning
      - abstract
      - bug
      - example
      - failure
      - important
      - name: info
        title: "Information"
      - new
      - question
      - quote
      - success

The appearance for each of these types is defined in assets/scss/_admonitions.scss. The colors for each type can, however, be changed by setting CSS variables (--adminition-bg, --admonition-title) without having to override that file.

/// example
Here is an example of an admonition.
///

Example

Here is an example of an admonition.

Google Analytics

site:
  # Google Analytics Tracking (optional)
  ga_tracking: G-1AB234CDE5
  ga_tracking_anonymize_ip: true

It is possible to specify more than one tracking ID as a commma-separated string (without spaces). This may facilitate transition bwtween different versions of Google Analytics or migration to a different site.

ga_tracking: "UA-1234567-89,G-1AB234CDE5"

Tags