Skip to content

Installation Guide

This document explains the complete setup process followed to create the MkDocs Material documentation environment on a Windows system using Python and Visual Studio Code.

Prerequisites

Before setting up the project, the following tools were installed on the system:

  • Python 3.x
  • Visual Studio Code
  • PowerShell
  • Internet connection for downloading Python packages

Verifying Python Installation

Before creating the documentation project, Python installation was verified from PowerShell.

python --version

Successful installation returns the installed Python version.

Example:

Python 3.14.0

Creating the Project Directory

A dedicated project folder was created to keep all documentation-related files organized.

mkdir knowledge-base
cd knowledge-base

This directory later contains:

  • Documentation files
  • Python virtual environment
  • MkDocs configuration
  • Theme dependencies

Creating a Python Virtual Environment

A virtual environment was created to isolate project dependencies from the global Python installation.

python -m venv venv

This command creates a local environment named venv inside the project directory.

Activating the Virtual Environment

The virtual environment was activated using PowerShell.

.\venv\Scripts\Activate.ps1

After successful activation, the terminal displays the virtual environment name.

Example:

(venv) PS D:\Sam\MkDocs\knowledge-base>

Resolving PowerShell Execution Policy Issues

During the initial setup, PowerShell blocked the execution of the activation script because script execution was disabled on the system.

The issue was resolved by updating the PowerShell execution policy for the current user.

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

This allows locally created PowerShell scripts to execute safely.

Installing MkDocs Material

After activating the virtual environment, MkDocs Material was installed using pip.

pip install mkdocs-material

This installs:

  • MkDocs
  • Material theme
  • Required dependencies

Creating the MkDocs Project

A new MkDocs project was initialized inside the project directory.

python -m mkdocs new .

This generated the initial project structure and default configuration files.

Starting the Local Development Server

The local development server was started using the following command:

python -m mkdocs serve --livereload

The server generates a temporary local documentation website accessible from the browser.

Default local URL:

http://127.0.0.1:8000

Verifying Live Reload Functionality

After the server was started, modifications to Markdown files were automatically reflected in the browser.

The terminal displayed messages similar to:

INFO    -  Building documentation...
INFO    -  Reloading browsers

This confirmed that live reload functionality was working correctly.

Final Project Structure

After completing the installation and setup process, the project structure appeared as follows:

knowledge-base/
│
├── docs/
│   └── index.md
│
├── mkdocs.yml
│
└── venv/

Outcome

At the end of the installation process:

  • MkDocs Material was successfully configured
  • Python virtual environment was established
  • Live documentation preview was operational
  • Automatic browser reload functionality was enabled
  • The foundation for a structured documentation website was completed