About MkDocs themes and their customs

Introduction

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.

Use an existing theme

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.

Custom CSS / Javascript

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.

Overwriting the theme

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.

Overwrite template block

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.

Finally

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.

reference

MkDocs Material for MkDocs Styling your docs Custom themes

Recommended Posts

About MkDocs themes and their customs
About _ and __
About Class and Instance
About cumprod and cummax
About creating and modifying custom themes for Python IDLE
About cross-validation and F-number
Linux (about files and directories)
About LINUX files and processes
About Raid group and LUN
About fork () function and execve () function
About Django's deconstruct and deconstructible
About Python, len () and randint ()
About Python datetime and timezone
About Sharpe Ratio and Sortino Ratio
About Python and regular expressions
About Python and os operations
About http.Handle () and http.NewServeMux (). Handle ()
Python # About reference and copy
About Numpy array and asarray
About Python sort () and reverse ()