Skip to content

Customizing Mkdocs

I wanna customize my mkdocs theme. So I can have a dark mode. Because it currently looks like this and having a nice looking documentation page is necessary too!

alt text

Issues

Attempt 1

I tried changing it by referencing extra css but when it builded i looked through the job artifacts and I saw that it didn't pick up on the file

site_name: Fab Academy docs page - Sam
site_url: https://pages.gitlab.io/mkdocs
site_dir: public
theme: 
 name: ivory
extra_css: [extra.css]

.footer-note {
    color:rgb(47, 44, 44) !important
}

.home .version {
    color:rgb(47, 44, 44) !important
  }

Attempt 2

After I read the documentation thoroughly i found out that the css file needs to be relative to the docs folder and not the mkdocs.yml. After that it showed the css and I could finally customize the theme.

Customizing Material theme

Palette customization

I decided to switch to material theme because its easier to configure. There are pre made color schemes and a lot of extensions that work out of the box. Example changing colors. 

theme:
  palette:
    primary: indigo
    accent: teal
Of course you could also use the extra.css to style the website even more.

Extensions

You can add lot's of extensions. For example code highlighting or a table of contents on the right side of your website. This adds a table of contents. You can find all the extensions here. 

markdown_extensions:
  - toc:
      permalink: true

With this extension you can add drop down menu's to your page.

How do I install drop down menus?

Drop down menu's are part of the pymdownx.details extension. You need to place that in your mkdocs.yml under markdown_extensions: like his: 

markdown_extensions:
  - pymdownx.details

How do I use it

You can use it like this. Don't forget that you need to use 2 tabs to get the text in the collapsible box. 

??? Notes

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent lacinia rutrum nibh sit amet pharetra. Aenean in metus fringilla, varius nulla eu, malesuada nulla. Praesent placerat tortor lacus, nec sollicitudin felis elementum sit amet. Nam mollis tincidunt arcu ac gravida. Vivamus turpis nisi, lacinia in eleifend sed, interdum ultricies quam.

Result:

Info

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent lacinia rutrum nibh sit amet pharetra. Aenean in metus fringilla, varius nulla eu, malesuada nulla. Praesent placerat tortor lacus, nec sollicitudin felis elementum sit amet. Nam mollis tincidunt arcu ac gravida. Vivamus turpis nisi, lacinia in eleifend sed, interdum ultricies quam.