Create a Website Using Material for MkDocs: A Step-by-Step Guide

Introduction to Material for MkDocs,

Material for MkDocs, a static site generator written in Python, simplifies the process of creating project documentation. it helps for IT professionals, developers, and writers for creating a website. Static websites are fast, secure, and easy to maintain, making them an ideal choice for documentation, blogs, and personal websites.

In this article, I will guide you through the steps by step instructions on how to create a static website or documentation site using Material for MkDocs, an extension of the MKDocs project that brings a modern look and additional features to your site.

Prerequisites

Basic knowledge of Python and Markdown.
Access to a command-line interface.

Step 1: Installation

Install Homebrew (macOS users):

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

Install Python 3:

MkDocs requires a recent version of Python and the Python package manager, pip, to be installed on your system.

brew install python3

# verify the installation
python3 --version

(or use the respective command for your operating system).

Upgrade PIP:

pip3 install --upgrade pip

This ensures you have the latest version of PIP.

Install MKDocs and Related Packages:

pip3 install mkdocs
pip3 install mkdocs-material
pip3 install mkdocs-material-extensions

These commands install MKDocs, the Material theme, and additional extensions.

Step 2: Creating Your Project

Initialize Your MKDocs Project:

mkdocs new my-project

output

INFO    -  Creating project directory: my-project
INFO    -  Writing config file: my-project/mkdocs.yml
INFO    -  Writing initial docs: my-project/docs/index.md

Replace 'my-project' with your project name. This command creates a new directory with essential configuration files.

Navigate to Your Project Directory:

cd my-project

Open the project in VS code

code .

Step 3: Run the Project Locally

MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the mkdocs.yml configuration file, and then start the server by running the mkdocs serve command:

mkdocs serve

This command starts a local server. Access your site at http://127.0.0.1:8000 and see changes in real-time as you edit your documents.

The server automatically rebuilds your site when you save changes, allowing you to see updates in real-time.

Step 4: Add Content & Configure the Website

MKDocs organizes content using Markdown files in the docs directory. The index.md file is the homepage of your website.

Create Markdown Files:

Write your content in Markdown format. You can create multiple files and organize them into directories as needed.

Customization and Extensions

Material for MkDocs supports extensive customization. Edit your mkdocs.yml to include features like a search bar, social media links, or Google Analytics. MkDocs also supports plugins, which can add functionalities like search engine optimization, PDF export, and more.

Configure the Website

Editing mkdocs.yml customizes your website’s structure. Define your site name, theme (Material), and navigation structure.

Here’s a basic example:

site_name: My Awesome Project
theme: 
  name: material
nav:
  - Home: index.md
  - About: about.md

Explore the Material for MkDocs documentation for customization options and add them to your mkdocs.yml.

Step 5: Building and Deploying Your Site

Build Your Site:

When you're ready to publish, build a static site with:

mkdocs build

This command compiles your Markdown files into a static HTML website in the site directory.

This creates a site directory with your website’s static HTML files. For deployment, you can upload these files to a web server or use services like GitHub Pages for hosting. MkDocs provides a simple command for deploying to GitHub Pages:

mkdocs gh-deploy

Deploy Your Site:

Choose a hosting solution (e.g., GitHub Pages, GitLab Pages or any other hosting solution) and follow their instructions to deploy your MKDocs site.

Step 6: Customization Home Page

Your home page is the first thing visitors see. Make it informative and engaging. Edit the index.md file in the docs folder to add content.

This is the file you are looking for: overrides/home.html. You'll want to copy it over to your own overrides directory. Make sure you've set your custom_dir in mkdocs.yml:

theme:
  custom_dir: docs/overrides
...

In the front matter of your index.md, you need to specify the template to use:

---
title: Title
template: home.html
---

Note

One important thing that took me a while to realize: you need a newline at the end of your md file. If you don't have one, the content will not display. I guess it's processed as having null content if you don't include the newline.

Conclusion

Material for MkDocs is an excellent tool for IT professionals and tech writers to create and maintain documentation websites. With its easy-to-use features and extensive customization options, it's an ideal choice for documenting software project documentation, writing online e-Book, and more.