Download Material for MKDocs

Installing Material for MKDocs requires Python or Docker. This guide uses Python.

For more MKDocs documentation, visit mkdocs.org.

macOSWindowsLinux

1. Run the following command to download and install Homebrew for macOS.

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. Enter your password for sudo access.

3. Press Enter to confirm the installation. The installation can take a few minutes.

4. Run the following commands to add brew to the path. Change <username> to your username.

   (echo; echo 'eval "$(/usr/local/bin/brew shellenv)"') >> /Users/dmyama/.zprofile
   eval "$(/usr/local/bin/brew shellenv)"
   

5. Run the following command to install Python using Brew.

   brew install python
   

6. Run the following command to install Pip.

   curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
   python3 get-pip.py
   

7. Enter pip install mkdocs, then press Enter. MKDocs is installed.

8. Enter pip install mkdocs-material, then press Enter. Material for MKDocs is installed.
9. Navigate to your project folder. Example: cd documents/material-mkdocs.
10. Enter mkdocs new ., then press Enter. This will create an mkdocs.yml file, a docs folder, and an index.md file in the docs folder.

The following works with Windows 10 and later.

1. Download the Python installer version 3.11.5. For Windows, download Windows installer (64-bit).
2. Double-click the Python executable file to start the installation process.
3. Select Add python.exe to PATH.
4. Click Install Now.
5. When installation is complete, click Close.
6. Enter pip install mkdocs-material, then press Enter. Material for MKDocs is installed.
7. Navigate to your project folder. Example: cd /documents/material-mkdocs.
8. Enter mkdocs new ., then press Enter. This will create an mkdocs.yml file, a docs folder, and an index.md file in the docs folder.

1. Run the following command to install pip. Running sudo will require entering your password.

   sudo apt install python3-pip
   

2. When asked if you want to continue installing pip, press Enter to accept.

3. Run the following command to install MKDocs.

   sudo apt install mkdocs
   

4. When asked if you want to continue installing MKDocs, press Enter to accept.

5. Run the following command to install Material for MKDocs.

   pip install mkdocs-material
   

6. When asked if you want to continue installing Material for MKDocs, press Enter to accept.

7. Navigate to your project folder. Example: cd documents/material-mkdocs.
8. Enter mkdocs new ., then press Enter. This will create an mkdocs.yml file, a docs folder, and an index.md file in the docs folder.

Build a Site

After installing Material for MKDocs and creating a project, you can build a site.

1. Open Visual Studio Code.
2. Select Terminal > New Terminal.
3. In the command line, enter mkdocs serve, then press Enter. This runs the website locally.
4. Open a web browser, enter http://127.0.0.1:8000/ as the URL, then press Enter. The Welcome to MKDocs website displays.
5. In Visual Studio Code, open the Material for MKDocs mkdocs.yaml file. Select File > Open Folder, navigate to the project folder, select the mkdocs.yml file, then click Open.

6. Add the following to the mkdocs.yml file. The local website should update with the Material for MKDocs theme.

   theme:
       name: material