DEV Community

loading...

Mkdocs: Setting up mkdocs.yml

cosckoya profile image cosckoya ・2 min read

Setting up mkdocs.yml file is needed in the way to deploy a Mkdocs project, in this file we can set a lot of different values related to the theme, add custom CSS, navigation index, social network and more other things.

Let start with basic parameters:

site_name: '<Site Name>'
site_description: '<Site Description>'
site_author: '<user>'
site_url: 'https://<user>.github.io/<git_repo>'
copyright: "copyright &copy; 202X <user>"

repo_url: 'https://github.com/<user>/<git_repo>'
edit_uri: ""
Enter fullscreen mode Exit fullscreen mode

Next we could add some social networks that will be show in the Mkdocs project:

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/cosckoya
    - icon: fontawesome/brands/dev
      link: https://dev.to/cosckoya
Enter fullscreen mode Exit fullscreen mode

These last two parameter blocks enable some basic functionalities and behaviors. But also we could manage some advanced things about the theme.

Themes can be built-in or custom. Im using a built-in one, Material.

To add this theme, I followed the Material docs and set up the following parameters:

theme:
  name: material
  logo: img/logo.png
  favicon: img/favicon.png
  language: en
  palette:
    scheme: slate
    primary: deep purple
    accent: deep purple
  icon:
    repo: fontawesome/brands/github
Enter fullscreen mode Exit fullscreen mode

Last step is to set Navigation, where I added a plugin (mkdocs-literate-nav). With this plugin I could remove "nav" settings from mkdocs.yml file, add some "SUMMARY.md" files on each directory adding this block:

plugins:
  - literate-nav:
      nav_file: SUMMARY.md
Enter fullscreen mode Exit fullscreen mode

A SUMMARY.md file must exist in each folder, will be automatically detected and should have the following format:

* [Klaatu Barada Nitko!](index.md)
* [Code](code/)
* [Linux](linux/)
* [Databases](databases/)
* [Cloud](cloud/)
* [Containers](container/)
* [Security](security/)
* [DevOps](devops/)
* [Monitoring](monitoring/)
* [Bookmarks](bookmarks.md)
* [About](about.md)
Enter fullscreen mode Exit fullscreen mode

That's it. Enjoy!

Discussion (0)

pic
Editor guide