README.md

mkdocs-risonia-theme

A simple theme for MkDocs. Based on this demo using the w3.css framework and configurable color schemes (inspiration here).

Demo

See a demo and documentation here

Design goals

• Be a simple starting point for modifications.
• Be colorful and readable.
• Implement all features of the standard MkDocs theme (in progress).
• Integrate some useful plugins.
• Don't require translations.
• Don't be obfuscated.
• Add as little nonsense as possible.

Ugly compromises

• To use w3css we need to add additional classes to the markdown output.
  • The good part is, while we're at it, we are also able to mark externals links.
• The SVG icons need to be included in every page, because otherwise they can't be set to the text color.

Features

• Light and dark mode.
• Integration of mkdocs-static-i18n plugin.
• Integration of mkdocs-encryptcontent-plugin.
• Web app support.
• Rather lightweight
• Short (nav) and long (top panel) page titles

Installation

Install the package with pip:

pip install mkdocs-risonia-theme

Install the package from source with pip:

cd mkdocs-risonia-theme/
python setup.py sdist bdist_wheel
pip install dist/mkdocs_risonia_theme-0.1.12-py3-none-any.whl

Configuration

Enable the theme and plugins in your mkdocs.yml:

theme:
    name: risonia
    #custom_dir: theme_override/ # add static files or overrides
    #logo: img/logo.svg # if undefined a burger symbol is displayed on mobile devices
    #favicon: img/logo.ico # if undefined img/favicon.ico is used
    #manifest: manifest.json # manifest for installable webapp
    #serviceworker: service-worker.js # for webapp an empty file is sufficient
    #extlink: true # mark external links with symbol
    #extblank: true # send external links to new browser tab
    #toc_sidebar: true # If display is wide enough, then display TOC on the right side
    #zoom_img: true # click on images to view them bigger
    
plugins:
    - search: {}

    #- i18n: {...} # mkdocs-static-i18n

    - color-theme: # optional
        theme_color: '#ff6600' # primary color
        secondary_color: 'complementary' # can be a color or scheme
        light_text_color: '#000' # black
        dark_text_color: '#fff' # white
        extra_css_light: # list of extra CSS for light mode
            - 'css/additional-light.css'
        extra_css_dark:  # list of extra CSS for dark mode
            - 'css/additional-dark.css'
        additional: # build these themes also
          - theme_color: '#44bb4f'
            secondary_color: 'complementary'

    - w3css-classes: {} # mandatory

    #- encryptcontent: {...} # mkdocs-encryptcontent-plugin

Overrides

The file main.html in custom_dir can be used to further customize the template:

{% extends "base.html" %}

{% block exec_script %}
<script>
  var DOMContentLoaded_fired = false;
</script>
<script id="theme">
function runWhenDOMContentLoaded() {
  document.querySelectorAll('pre code').forEach((el) => {
    hljs.highlightElement(el);
  });
  document.querySelectorAll('table').forEach(function(table) {
    if (!table.hasAttribute('Tablesort')) {
      new Tablesort(table);
      table.setAttribute('Tablesort', '');
    }
  });
}
if (DOMContentLoaded_fired) {
  runWhenDOMContentLoaded();
}
</script>
<script>
document.addEventListener('DOMContentLoaded',function(){
  DOMContentLoaded_fired=true;
  runWhenDOMContentLoaded();
});
</script>
{% endblock %}

{%- block footer_ext %}
  <p class="w3-right w3-tiny">
  {%- if i18n_config and i18n_page_file_locale %}
    <a href="{{ (i18n_page_locale + '/imprint/') | url }}">Imprint</a>
  {%- else %}
    <a href="{{ 'imprint/' | url }}">Impressum</a>
  {%- endif %}
  </p>
{%- endblock %}

{%- block top_buttons %}
    <a class="w3-button w3-theme-d1 w3-hover-theme w3-padding-small w3-right no-print" href="{{ config.repo_url }}" target="_blank">&lt;/&gt;</a> 
{%- endblock %}

Page titles

Normally nav page titles would override # heading or title meta tag. But in this theme the title meta tag will always be used for the top panel if defined.

For example define the navigation:

nav:
    - Short title: 'index.md'

And within index.md you define the long title like this:

title: Long long long title