A simple theme for MkDocs using using the w3.css framework and configurable color schemes
Project description
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.10-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
#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'
- 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"></></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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs-risonia-theme-0.1.10.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 48896e92993cf67a23f239aa7962de11a39321b2b8878232cc8cd3e83a635c15 |
|
MD5 | 9e2887534c0230c8638ec78fac996b84 |
|
BLAKE2b-256 | 8fc771b88a55ba6a4fc938461001971fd6024438125870952c25ab4a25b84b30 |
Hashes for mkdocs_risonia_theme-0.1.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0d6beb6eaa21806ed56da5e1bc6d16d63de17a469893fb19daf3619c99d6172a |
|
MD5 | f5fea27e5bbc17cf06c26fa3814e58e0 |
|
BLAKE2b-256 | 394157ccb55d25a38cd07bf306b9a5f8618bdb408b21a5832fadfc87be84b128 |