DEV Community

cosckoya
cosckoya

Posted on

4 2

Mkdocs: Setting up mkdocs.yml

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!

Heroku

Build apps, not infrastructure.

Dealing with servers, hardware, and infrastructure can take up your valuable time. Discover the benefits of Heroku, the PaaS of choice for developers since 2007.

Visit Site

Top comments (0)

Billboard image

Create up to 10 Postgres Databases on Neon's free plan.

If you're starting a new project, Neon has got your databases covered. No credit cards. No trials. No getting in your way.

Try Neon for Free →

👋 Kindness is contagious

Please leave a ❤️ or a friendly comment on this post if you found it helpful!

Okay