Skip to content

Mkdocs Initial Setup

  • Official site: https://squidfunk.github.io/mkdocs-material/
  • Developer's GitHub: https://github.com/squidfunk/mkdocs-material

Setup Instructions

Pre-Requisites

  1. Download and install GitHub Desktop
  2. Download and install Python for Windows
  3. Download and install VS Code (if you don't already have it)
  4. Set up a virtual environment for Python
python -m venv venv

Install Mkdocs

  1. Install mkdocs-material
pip install mkdocs-material
  1. Run the script to activate the virtual environment. This script will need to be run every time you edit/make changes to the website.
venv\Scripts\Activate.ps1
  1. If you encounter an error about running scripts being disabled, you can run the following command and then run the Activate.ps1 script again
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
  1. Open the website in VS Code by typing the following command:
code .

Scaffold New Site

  1. Open a new terminal if one is not already open and run the following commands:
mkdocs new .

mkdocs serve
  1. Add the material theme to the mkdocs.yml file
theme:
    name: material
  1. Add the following to the mkdocs.yml file to add the light mode/dark mode toggle:
  palette: 
    # Palette toggle for light mode
    - scheme: default
      primary: green
      accent: purple
      toggle:
        icon: material/brightness-7 
        name: Switch to dark mode

    # Palette toggle for dark mode
    - scheme: slate
      primary: indigo
      accent: yellow
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  1. Add the following to the mkdocs.yml file to add necessary features and plugins:
theme:
  name: material
  font:
    text: Roboto

  features:
    - content.code.annotate
    - content.code.copy
    - content.tabs.link
    - header.autohide
    - announce.dismiss
    - navigation.footer
  #  - navigation.expand
    - navigation.indexes
    - navigation.instant
    - navigation.instant.progress
    - navigation.path
    - navigation.sections
  #  - navigation.tabs
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest
  #  - toc.integrate

  plugins:
    - typeset
    - search
    - blog

  palette:

    # Palette toggle for light mode
    - scheme: default
      primary: red
      accent: red
      toggle:
        icon: material/brightness-7 
        name: Switch to dark mode

    # Palette toggle for dark mode
    - scheme: slate
      primary: red
      accent: red
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences