“This is the 24th day of my participation in the First Challenge 2022. For details: First Challenge 2022.”

preface

Earlier we introduced the basic usage of MKDocs (MKDocs introduction). Many students say it smells very good, but the default theme is not beautiful enough. Although we can improve it by using the built-in readThedocs theme, it is not beautiful enough. Today, we will try a modern MKDocs theme material together.

About the material

Material theme is a theme based on MKDocs for modern technical documentation site, very beautiful.

For the cat

First we initialize a mkdocs project with mkdocs init.

Then we PIP install mkdocs-material to download the Material theme.

Finally, we specify a material theme when we start the project.

How about, compared to ReadThedocs, the material effect is still fresh and modern.

Material configuration

Normally we configure the theme in mkdocs. Yaml instead of specifying it on the command line.

So we need to write the highlighting of the theme and markdown into the configuration file.

site_name: My Docs
theme:
  name: material
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
Copy the code

After configuring the theme to mkdocs. Yaml, you do not need to specify the theme to start the service. Simply mkdocs serve

Code highlighting and headings

Material supports not only code highlighting but also code titles.

```python title='demo.py'
def sayhi() :
    return "Hi,Python full stack development"` ` `Copy the code

Not only that, Material also supports free-commenting code and good interaction.

```python title='demo.py'
def sayhi() :
    return "Hi,Python full stack development" # (1)` ` `1.This is my free annotation content, welcome to pay attention to my public number.Copy the code

Beautiful prompt box

Prompt box configuration:

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
theme:
  icon:
    admonition:
      note: octicons/tag-16
      abstract: octicons/checklist-16
      info: octicons/info-16
      tip: octicons/squirrel-16
      success: octicons/check-16
      question: octicons/question-16
      warning: octicons/alert-16
      failure: octicons/x-circle-16
      danger: octicons/zap-16
      bug: octicons/bug-16
      example: octicons/beaker-16
      quote: octicons/quote-16
Copy the code

Md content:

!!!!!!!!! Note "this is note type prompt box" prompt: more wonderful content remember to pay attention to me ah!! Success "This is a success type prompt box" success! !!!!!!!!! Failure "This is a failure type prompt box" Failure! !!!!!!!!! Bug "This is a bug type prompt box" found a bug, please fix as soon as possible!Copy the code

What about scenarios where there is a lot of content in the prompt box? Material Supports folding of prompt boxes.

!!!!!!!!! – >??? Can.

Md content:

????? Note "This is the note type prompt box" hint: for more exciting content, please keep an eye on meThe second line
The third line
In the fourth row
Line 5...Copy the code

More: Material official documentation

The last

The above material only shows some functions. Material also supports acronyms, buttons, data tables, Avi, anchors, character formatting, Emoji, Icon, images, mathematical formulas, etc. In short, very powerful.

Finally, I hope my share can be helpful to you!