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 © 202X <user>" repo_url: 'https://github.com/<user>/<git_repo>' edit_uri: ""
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
These last two parameter blocks enable some basic functionalities and behaviors. But also we could manage some advanced things about the theme.
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
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
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)
That's it. Enjoy!