How To Make An MkDocs Material Website

A great choice for a documentation style website.

Dec 03, 2023

I figured there might be some interest in how a documentation website was made, so I'll be walking you through the steps involved in this. I went with MkDocs Material for the new site I made and I've been pretty pleased with how well it turned out.

These types of websites have been picking up popularity in recent years. Mostly because it's way easier to find and navigate through a lot of information. This can be useful for both home users on info websites and businesses that have internal sites for their specific documentation on their processes. There's a lot of stuff to cover, so lets get started.

First, you'll need a few things to get going. You'll need an account at GitHub, download the latest version of Python, and download an editor. There's multiple options available - I chose to go with Visual Studio Code. You'll also want to download the GitHub desktop app. Make sure to get all three apps from the official websites for each and not from a third party source.

When you install Python, be sure to select "Add Python to PATH" option. You'll also see a similar option in the VS Code installer to select. When you install GitHub, it'll open up a web browser window to log the app in. Once it's logged in, you'll see a few different options you can select. Choose the "create a new repository on your hard drive." The name you give the repo will also name the folder it creates. Select the path that you want the folder to be in. You'll also see options for "Git ignore" and "license." You can skip both of these options and can change them later if you choose.

For now, you can minimize GitHub. Go to the folder it created. Right click anywhere in the folder window and select the option to open a terminal window. For example, if your folder is named "newwebsite" and it's in D:\, the terminal should show this:

D:\newwebsite

You'll need to run some commands here. These are extremely important and the order they are ran matters as well.

python -m venv venv

This is the first command you'll need to run that enables a virtual environment. Every time you start the terminal back up to edit the site, you need to run this command.

pip install mkdocs-material

This is the next command to run. This installs MkDocs and the dependencies. You only need to run this once.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

You'll need to run this to activate the PowerShell script to let you start making changes to the website. Windows has a security setting that keeps any PS script from just being able to run. This command is set so that once the terminal is closed, the execution policy goes back to the previous setting. This is better for security to have it that way.

venv\Scripts\Activate.ps1

This is the command that activates the PS script for you to start making changes tot he website. You'll know it's working as you'll see (venv) in front of the drive letter (i.e. D:\) If you're on Linux, you'll need to run this command instead: source venv/bin/activate

code .

This will start us VS Code where you can start making changes to files. Once VS Code is started up, go to the top left of the window to the "Terminal" tab and select new terminal. In the VS Code terminal run the following code:

mkdocs new .

This will create an mkdocs.yml file and an index.md (markdown) file that you can edit. The last command to run is:

mkdocs serve

This will allow you to see the website and also see the updates as you save them in VS Code. Hold down "Ctrl" and click on the link it gives you to open up the website.

Editing the files

Here's where the real work begins. The mkdocs.yml file is going to be a crucial file that is going to massively influence how your website looks. One thing to note - the file is extremely sensitive to any spaces, tabs, misspellings, etc. One thing being slightly off can make your website look weird or it will cause an error when trying to save the changes made. If you see any errors come up, you'll need to read them closely to find out what needs to be changed.

I made a video covering making this website as well as the yml file specifically. You can follow along with it here if you want.

I also strongly suggest you have the MkDocs Material documentation open as well. You'll need to reference it quite a lot as you build the site.

When you start filling in the different sections for the yml file, such as features, plugins, markdown_extensions, nav, etc, you'll have to make sure they are placed very specifically. As I mentioned before, having an extra space or tab somewhere will completely break everything. I show my yml file and explain the different option I used in detail. You don't have to choose everything I did. Feel free to change it to whatever you want. The documentation for the theme is very extensive. I also strongly suggest you use the search function it comes with, as it will save a lot of time.

When you make changes to the yml file, I suggest changing one or two things at a time and saving it to make sure everything it as it should be. If you make a lot of changes and errors start appearing, it'll make life more difficult to track down the issues.

One of the most important parts of the yml file is going to be setting up your navigation. This is something I covered in great detail in the video. I marked the two areas I talked about it with timestamps, so you can go straight to those areas to find out the necessary info.

Icons

I'll also cover emojis and icons since they have a pretty big role in my site. On the MkDocs Material website, you'll see a section of the website called "reference." If you click on that and go to the icons section, it'll tell you what you need to do to configure them. You can also see the search function here where you can find the names of icons and see what they'll look like. This will be an excellent resource to have if you choose to use icons on your site.

There'll be times that you need to change how the icons are placed. For example, you'll usually see these two formats:

:fontawesome-brands-youtube:

fontawesome/brands/youtube

The other options are Google Material, Octicons, and Simple icons. Font Awesome in the only one that has subdirectories, so you'll need to keep that in mind.

material/upload-network-outline

fontawesome/solid/network-wired

For Font Awesome, there is outline, solid, and brands sub directories.

The other thing you'll see is that you might need to use a long string with a w3 URL to change an icon. An example of this is if you want to use a custom admonition. You can't use either of the above methods to make a custom admonition icon. What you'll see is the following:

To find the code for the icon you want to use, you'll need to go to the GitHub page for MkDocs Material. When you find the icon you want, click on it. You'll see the icon shown. Look above and to the left and you'll see a "code" tab. Click on that and you'll get the code that you need to change an icon for something like a custom admonition.

Creating the content

Now that you've gone through and got the settings of the site configured how you want, you can start making the content. Something to note - you probably won't be able to do much with setting up navigation until you start getting your docs created. One option you have is if you've got a plan of what pages you want to make ahead of time, you can just make the files and keep them empty. Then you can set up the nav section in the mkdocs.yml file before you start adding the content to the .md files.

As for the .md files themselves, I haven't harnessed anywhere near the power that these are capable of. If you look at my site, it's mostly basic with just a lot of text, some admonitions, and some video pasted here and there. Markdown files can do a lot more though. You can do things like have code blocks, footnotes, tables, and so on. I haven't used some of those other features yet, so I can't tell you a lot about them. There's plenty of good YouTube videos that could show you this though.

When you're adding docs, make sure everything you add is inside the "docs" folder. When you're in VS Code, you'll have the option to create a new file when you right click on docs. You can also create folders within the docs folder, which is really good to do if you have a lot of stuff to add. It'll go a long way to keeping everything looking clean and organized. When you are making new .md files, make sure you are adding the .md to the end (i.e. networksecurity.md).

Wrapping up

That covers the major points that can be an issue to work through. If you need any further detail, I covered quite a few of the minor issues I had in the video and how to fix them. If you have any issues or questions, feel free to drop a comment and let me know. See you next Saturday! 🍻

Letters From The Nordic Stallion

Discussion about this post