# mkdocs-risonia-theme
[](https://pypi.org/project/mkdocs-risonia-theme/)
[](https://pypi.org/project/mkdocs-risonia-theme)
[](https://opensource.org/licenses/MIT)
A simple theme for [MkDocs](https://www.mkdocs.org/). Based on [this demo](https://www.w3schools.com/w3css/tryw3css_examples_material.htm)
using the [w3.css](https://www.w3schools.com/w3css/) framework and configurable color schemes
(inspiration [here](https://www.w3schools.com/colors/colors_schemes.asp)).
## Demo
See a demo and documentation [here](https://unverbuggt.xn--rthlein-n2a.de/risonia/en/)
## 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](https://unverbuggt.xn--rthlein-n2a.de/risonia/en/mkdocs/#size-comparison)
* Short (nav) and long (top panel) [page titles](#page-titles)
## Installation
Install the package with pip:
```bash
pip install mkdocs-risonia-theme
```
Install the package from source with pip:
```bash
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`:
```yaml
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:
```html
{% 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:
```yaml
nav:
- Short title: 'index.md'
```
And within `index.md` you define the long title like this:
```markdown
title: Long long long title
```
Raw data
{
"_id": null,
"home_page": "https://unverbuggt.github.io/mkdocs-risonia-theme/",
"name": "mkdocs-risonia-theme",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "mkdocs theme python markdown",
"author": "Ren\u00e9 R\u00fcthlein",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/92/53/42215647f31c859262988736d23ba6948eb75deb11a02fef3754d879fedd/mkdocs-risonia-theme-0.1.12.tar.gz",
"platform": null,
"description": "# mkdocs-risonia-theme\r\n\r\n[](https://pypi.org/project/mkdocs-risonia-theme/)\r\n[](https://pypi.org/project/mkdocs-risonia-theme)\r\n[](https://opensource.org/licenses/MIT) \r\n\r\nA simple theme for [MkDocs](https://www.mkdocs.org/). Based on [this demo](https://www.w3schools.com/w3css/tryw3css_examples_material.htm) \r\nusing the [w3.css](https://www.w3schools.com/w3css/) framework and configurable color schemes\r\n(inspiration [here](https://www.w3schools.com/colors/colors_schemes.asp)).\r\n\r\n## Demo\r\n\r\nSee a demo and documentation [here](https://unverbuggt.xn--rthlein-n2a.de/risonia/en/)\r\n\r\n\r\n\r\n\r\n## Design goals\r\n\r\n* Be a simple starting point for modifications.\r\n* Be colorful and readable.\r\n* Implement all features of the standard MkDocs theme (in progress).\r\n* Integrate some useful plugins.\r\n* Don't require translations.\r\n* Don't be obfuscated.\r\n* Add as little nonsense as possible.\r\n\r\n## Ugly compromises\r\n\r\n* To use w3css we need to add additional classes to the markdown output.\r\n * The good part is, while we're at it, we are also able to mark externals links.\r\n* The SVG icons need to be included in every page, because otherwise they can't be set to the text color.\r\n\r\n## Features\r\n\r\n* Light and dark mode.\r\n* Integration of `mkdocs-static-i18n` plugin.\r\n* Integration of `mkdocs-encryptcontent-plugin`.\r\n* Web app support.\r\n* Rather [lightweight](https://unverbuggt.xn--rthlein-n2a.de/risonia/en/mkdocs/#size-comparison)\r\n* Short (nav) and long (top panel) [page titles](#page-titles)\r\n\r\n## Installation\r\n\r\nInstall the package with pip:\r\n\r\n```bash\r\npip install mkdocs-risonia-theme\r\n```\r\n\r\nInstall the package from source with pip:\r\n\r\n```bash\r\ncd mkdocs-risonia-theme/\r\npython setup.py sdist bdist_wheel\r\npip install dist/mkdocs_risonia_theme-0.1.12-py3-none-any.whl\r\n```\r\n\r\n## Configuration\r\n\r\nEnable the theme and plugins in your `mkdocs.yml`:\r\n\r\n```yaml\r\ntheme:\r\n name: risonia\r\n #custom_dir: theme_override/ # add static files or overrides\r\n #logo: img/logo.svg # if undefined a burger symbol is displayed on mobile devices\r\n #favicon: img/logo.ico # if undefined img/favicon.ico is used\r\n #manifest: manifest.json # manifest for installable webapp\r\n #serviceworker: service-worker.js # for webapp an empty file is sufficient\r\n #extlink: true # mark external links with symbol\r\n #extblank: true # send external links to new browser tab\r\n #toc_sidebar: true # If display is wide enough, then display TOC on the right side\r\n #zoom_img: true # click on images to view them bigger\r\n \r\nplugins:\r\n - search: {}\r\n\r\n #- i18n: {...} # mkdocs-static-i18n\r\n\r\n - color-theme: # optional\r\n theme_color: '#ff6600' # primary color\r\n secondary_color: 'complementary' # can be a color or scheme\r\n light_text_color: '#000' # black\r\n dark_text_color: '#fff' # white\r\n extra_css_light: # list of extra CSS for light mode\r\n - 'css/additional-light.css'\r\n extra_css_dark: # list of extra CSS for dark mode\r\n - 'css/additional-dark.css'\r\n additional: # build these themes also\r\n - theme_color: '#44bb4f'\r\n secondary_color: 'complementary'\r\n\r\n - w3css-classes: {} # mandatory\r\n\r\n #- encryptcontent: {...} # mkdocs-encryptcontent-plugin\r\n```\r\n\r\n## Overrides\r\n\r\nThe file `main.html` in `custom_dir` can be used to further customize the template:\r\n\r\n```html\r\n{% extends \"base.html\" %}\r\n\r\n{% block exec_script %}\r\n<script>\r\n var DOMContentLoaded_fired = false;\r\n</script>\r\n<script id=\"theme\">\r\nfunction runWhenDOMContentLoaded() {\r\n document.querySelectorAll('pre code').forEach((el) => {\r\n hljs.highlightElement(el);\r\n });\r\n document.querySelectorAll('table').forEach(function(table) {\r\n if (!table.hasAttribute('Tablesort')) {\r\n new Tablesort(table);\r\n table.setAttribute('Tablesort', '');\r\n }\r\n });\r\n}\r\nif (DOMContentLoaded_fired) {\r\n runWhenDOMContentLoaded();\r\n}\r\n</script>\r\n<script>\r\ndocument.addEventListener('DOMContentLoaded',function(){\r\n DOMContentLoaded_fired=true;\r\n runWhenDOMContentLoaded();\r\n});\r\n</script>\r\n{% endblock %}\r\n\r\n{%- block footer_ext %}\r\n <p class=\"w3-right w3-tiny\">\r\n {%- if i18n_config and i18n_page_file_locale %}\r\n <a href=\"{{ (i18n_page_locale + '/imprint/') | url }}\">Imprint</a>\r\n {%- else %}\r\n <a href=\"{{ 'imprint/' | url }}\">Impressum</a>\r\n {%- endif %}\r\n </p>\r\n{%- endblock %}\r\n\r\n{%- block top_buttons %}\r\n <a class=\"w3-button w3-theme-d1 w3-hover-theme w3-padding-small w3-right no-print\" href=\"{{ config.repo_url }}\" target=\"_blank\"></></a> \r\n{%- endblock %}\r\n```\r\n\r\n## Page titles\r\n\r\nNormally `nav` page titles would override `#` heading or `title` meta tag.\r\nBut in this theme the `title` meta tag will always be used for the top panel if defined.\r\n\r\nFor example define the navigation:\r\n\r\n```yaml\r\nnav:\r\n - Short title: 'index.md'\r\n```\r\n\r\nAnd within `index.md` you define the long title like this:\r\n\r\n```markdown\r\ntitle: Long long long title\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple theme for MkDocs using using the w3.css framework and configurable color schemes",
"version": "0.1.12",
"project_urls": {
"Homepage": "https://unverbuggt.github.io/mkdocs-risonia-theme/"
},
"split_keywords": [
"mkdocs",
"theme",
"python",
"markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "854b19274714e50180221e20b99e8bd20954129ffdc957a2a3430423f701cb8e",
"md5": "c25d0454d70e326ea20009ec099c70c5",
"sha256": "4c86d0d168f1bb468fc8a32df12c2b5bf83abec49c47850bd925a6e8d504df90"
},
"downloads": -1,
"filename": "mkdocs_risonia_theme-0.1.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c25d0454d70e326ea20009ec099c70c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 27246,
"upload_time": "2023-09-08T07:49:29",
"upload_time_iso_8601": "2023-09-08T07:49:29.279735Z",
"url": "https://files.pythonhosted.org/packages/85/4b/19274714e50180221e20b99e8bd20954129ffdc957a2a3430423f701cb8e/mkdocs_risonia_theme-0.1.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "925342215647f31c859262988736d23ba6948eb75deb11a02fef3754d879fedd",
"md5": "7543c3ae0b40ac5d9c9d91bcd5a08c6a",
"sha256": "5f890ddf86129ac2ffaec1ecd3321328bf2945558ff0b3f222123a3a2f62ae71"
},
"downloads": -1,
"filename": "mkdocs-risonia-theme-0.1.12.tar.gz",
"has_sig": false,
"md5_digest": "7543c3ae0b40ac5d9c9d91bcd5a08c6a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 24857,
"upload_time": "2023-09-08T07:49:55",
"upload_time_iso_8601": "2023-09-08T07:49:55.551355Z",
"url": "https://files.pythonhosted.org/packages/92/53/42215647f31c859262988736d23ba6948eb75deb11a02fef3754d879fedd/mkdocs-risonia-theme-0.1.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-08 07:49:55",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mkdocs-risonia-theme"
}
JSON