Skip to content

MkDocs

Setting up an MkDocs site with Netlify is straightforward and highly effective for deploying technical documentation. MkDocs is a Python-based static site generator that builds documentation from Markdown files.

Here is a detailed, step-by-step guide for installation, customization, and continuous deployment.

1. Local MkDocs Setup and Project Initialization

MkDocs requires Python and its package manager, pip.

1.1. Install Prerequisites and MkDocs

  1. Install Python (3.7+ recommended).
  2. Create a virtual environment (recommended to isolate dependencies): 
    python3 -m venv venv
source venv/bin/activate  # On Windows, use: venv\Scripts\activate
  3. Install MkDocs and the default theme (Material for MkDocs is a popular choice, but we'll stick to the base setup first): 
    pip install mkdocs

1.2. Create a New MkDocs Site

Use the mkdocs new command to scaffold a basic project structure.

  1. Create the site: 
    mkdocs new my-mkdocs-site
  2. Navigate into the new directory: 
    cd my-mkdocs-site

1.3. Local Test

Run the development server to verify the default site.

mkdocs serve

Your site will be running at http://127.0.0.1:8000/. Press Ctrl+C to stop the server.

2. Custom Layouts, Partials, and Static Assets

MkDocs uses Jinja2 templates for customization. To apply custom HTML and styles, you must override files from the base theme.

2.1. Project File/Folder Structure Tree

Your project structure, after customization, will look like this:

my-mkdocs-site/
├── venv/                    # ⚠️ Python Virtual Environment (ignored by Git)
├── site/                    # ⚠️ Generated static site (Publish Directory for Netlify)
├── docs/                    # Source files for site content
│   ├── index.md             # Site homepage content
│   ├── about.md             # An example content page
│   └── css/                 # Static assets used by Markdown content (e.g., images)
│       └── custom.css       # Linked via markdown/theme
├── overrides/               # Custom theme overrides for Jinja2 templates and assets
│   ├── main.html            # Custom Layout (overrides base template)
│   ├── partials/            # Custom Partials (e.g., header, footer includes)
│   │   └── footer.html
│   └── main.css             # Custom CSS linked via main.html
├── mkdocs.yml               # Main site configuration (theme, navigation, extensions)
└── requirements.txt         # Lists Python dependencies for Netlify

2.2. Configure Custom Theme Overrides

To customize the default theme's structure, you must tell MkDocs where your custom templates are located.

  1. Create the Overrides directory: 
    mkdir overrides
mkdir overrides/partials
  2. Update mkdocs.yml:
    • File: mkdocs.yml 
      site_name: My MkDocs Documentation

# Configure the theme and point to your overrides folder
theme:
  name: readthedocs # or 'material', 'mkdocs' etc.
  custom_dir: overrides

2.3. Create the Custom Layout (main.html)

To customize the main page layout, you typically override the theme's core template file (often named main.html or base.html).

  1. Create the Main Layout Override:
    • File: overrides/main.html
    • Note: You must copy the existing theme's main.html content and modify it, or extend it using Jinja2. For simplicity, we'll assume a basic override and include a custom partial. 
      {% extends "base.html" %} 

{# This extends the base layout of the chosen theme (e.g., readthedocs) #}

{% block content %}
  {# Existing theme content goes here, e.g., {% include "content.html" %} #}
  {{ super() }} 

  {# Include your custom footer partial here #}
  {% include "partials/footer.html" %}
{% endblock %}

{% block extra_head %}
  {{ super() }}
  <link rel="stylesheet" href="{{ config.theme.custom_dir }}/main.css"> 
{% endblock %}

2.4. Create Partials (Includes)

  1. Create the Footer Partial:
    • File: overrides/partials/footer.html 
      <footer class="custom-footer">
    <p>&copy; {{ config.site_name }} {{ today.year }}</p>
</footer>

2.5. Manage Static Assets (Custom CSS)

  1. Add Custom CSS: Place styling directly in the overrides folder and link it in the main.html file (as done in Step 2.3).
    • File: overrides/main.css 
      /* Custom styles for the site */
.custom-footer {
    text-align: center;
    margin-top: 30px;
    padding-top: 15px;
    border-top: 1px solid #eee;
}

2.6. Final Local Check

  1. Run the server again: 
    mkdocs serve
    Verify that your custom layout and footer partial are visible and the CSS is applied.

3. GitHub Setup

3.1. Create Dependencies File

Since Netlify will run the build remotely, you need a list of Python dependencies.

  1. Create the dependency file: 
    pip freeze > requirements.txt
    This file should contain mkdocs (and any other themes or plugins you installed).

3.2. Verify .gitignore

Ensure the build output, environment, and caches are ignored.

touch .gitignore
echo "/venv/" >> .gitignore
echo "/site/" >> .gitignore  # The output folder

3.3. Commit and Push to GitHub

  1. Initialize Git: 
    git init
  2. Add files and commit: 
    git add .
git commit -m "Initial MkDocs setup with custom theme overrides"
  3. Create a new repository on GitHub (e.g., named my-mkdocs-netlify).
  4. Link your local repo and push: (Replace placeholders) 
    git remote add origin https://github.com/<your_username>/<repo_name>.git
git branch -M main
git push -u origin main

4. Netlify Setup for Continuous Deployment

4.1. Sign Up and Import Project

  1. Go to the Netlify website and log in.
  2. In the Netlify dashboard, click "Add new site" then "Import an existing project".
  3. Select "GitHub" and choose your repository (my-mkdocs-netlify).

4.2. Configure Build Settings

Netlify automatically detects the requirements.txt file and sets up a Python environment, but you must explicitly specify the build command and output directory.

Setting Value Note
Branch to deploy main The branch Netlify monitors.
Build command mkdocs build The command to generate the static site.
Publish directory site The folder MkDocs outputs the static files to.

4.3. Deploy the Site

Click the "Deploy site" button. Netlify will:

  1. Detect and install Python and the packages listed in requirements.txt.
  2. Run the build command: mkdocs build.
  3. Publish the contents of the site directory.

Your documentation site is now live with continuous deployment.

5. Ongoing Workflow

Your Continuous Deployment (CD) pipeline is now fully automated:

  1. Make changes locally (update Markdown files in docs/, edit templates in overrides/).
  2. Commit your changes: 
    git commit -am "Updated installation steps and fixed custom footer."
  3. Push to GitHub: 
    git push origin main
  4. Netlify automatically detects the push, runs the MkDocs build process, and deploys the new documentation live.