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.
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
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!
Top comments (0)