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.5-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
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.5.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2c0a6f4d70c55948adfc0ae44c7dbbee9907d8f1c868462f6e7db9c8eadf7060 |
|
MD5 | f51028c09144eb5e8692605b961561cd |
|
BLAKE2b-256 | f7781f101f21e4aad35de0e41074db267d49aa2bc9fe56887c79545e1ea36859 |
Hashes for mkdocs_risonia_theme-0.1.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2b24796c8dc9829842d250fbcbf936e9d16fec24dfc3d17046f59e4f00f7aa4d |
|
MD5 | fad09754afd893a46c5882d7a4262a20 |
|
BLAKE2b-256 | 952df0934cab16bbd3c2d2af3f803b30d511b3245d090bfd83466e1c78edfe67 |