Skip to content

2025

  • 2 min read

Configuration management with mkdocs and pymdownx.snippets

I believe this is a better way to manage your config files than uploading them to github. With this approach all you need to do is sync your configs file into the config folder within the root of your mkdocs site. They can easily be embedded as snippets in markdown files with appropriate syntax highlighting and contents of these config files also turn up in site search.

Here's an example:

$ mkdocs new vectorspace.xyz
$ cd vectorspace.xyz
$ nvim mkdocs.yml # (1)
$ mkdir configs
$ cp ~/.zshrc configs/
$ nvim docs/index.md # (2)
  1. look down further for mkdocs.yml
  2. look down further for index.md
mkdocs.yml
1
2
3
site_name: My Docs
markdown_extensions:
  - pymdownx.snippets # (1)
  1. For pydownx extension, you need to install python-pymdown-extensions on archlinux
docs/index.md
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# Welcome to MkDocs

For full documentation visit [mkdocs.org](https://www.mkdocs.org).

## Commands

* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.

## Project layout

    mkdocs.yml    # The configuration file.
    docs/
        index.md  # The documentation homepage.
        ...       # Other markdown pages, images and other files.

```zsh
--8<-- "configs/.zshrc"
```

Here I've just added:

```zsh
--8<-- "configs/.zshrc"
```

... to the end of the autogenerated docs/index.md file when you first create a site. Check the results of this by:

# Inside the directory that contains the mkdocs.yml file
mkdocs serve -a 127.0.0.1:9000

see the results for yourself at 127.0.0.1:9000

pydownx is just one of the many awesome extensions developed by github id facelessuser. Check out more at their site: https://facelessuser.github.io/pymdown-extensions/