I was doing Django personally, but since the server fee is not stupid, I started to investigate static site generators. Gatsby seems to be popular in the streets, but I want to make it as easy as possible with Python, so I will write about MkDocs. Please note that this article does not deal with self-made themes, but is limited to existing themes and their customizations.
It is described in Official Documents, but when using the theme installed by default, it is called `theme: theme name` All you have to do is write a sentence in mkdocs.yml.
As an example, if you want to set the theme `read thedocs`, you just need to add the sentence `theme: readthedocs`. It's easy!
MkDocs has many themes created by the community. The most famous of these is `` `mkdocs-material```, which incorporates material design. Incorporating external themes is also fairly easy
pip install mkdocs-material
From
mkdocs.yml
theme:
name: material
Just do. See the official github page (URLhttps://github.com/squidfunk/mkdocs-material) for more information on this subject. There are many other interesting and practical themes on [this page](URL https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes). Please check it out.
If you just want to add CSS or Javascript, it's very easy. Just put the CSS or Javascript files you want to add to the Documentation directory. It is described in more detail in [here](URL https://www.mkdocs.org/user-guide/configuration/#extra_css), for example under the documentation directory.
extra_css:
- css/extra.css
- css/second_extra.css
A structure like this adds extra_css with a subdirectory called css. You can add Javascript in the same way.
According to the Official Documentation (URLhttps://www.mkdocs.org/user-guide/styling-your-docs/), customizing the theme requires creating a new directory at the same level as the documentation directory. ..
mkdocs custom_theme
Once you've done that, let's tell you where your custom theme is in mkdocs.yml.
mkdocs.yml
theme:
name: mkdocs
custom_dir: custom_theme/
If you create a file with the same file name as the file included in the theme used in custom_dir, the file of the theme you are currently using will be automatically replaced with the newly created file. Also, if you create a file with a name that is not included in the theme you are using, it will be automatically added to the existing theme.
It's easier to inherit base.html when overwriting an html file (unless of course you want to overwrite `` `base.html``` itself).
{% extends "base.html" %}
{% block htmltitle %}
<title>Custom title goes here</title>
{% endblock %}
You can easily inherit by writing a template block in this way. This is also detailed in the official documentation mentioned above.
I may write an article about my own work on the theme soon. If you find any mistakes, we would appreciate it if you could actively send us edit requests.
MkDocs Material for MkDocs Styling your docs Custom themes
Recommended Posts