Getting Started with Material for MkDocs 2024 Edition

Script for the getting started with Material for MkDocs tutorial - 2024 edition.

Video Status

1. Intro

• Welcome back to the channel! In today’s video we’re diving into Material for MkDocs, the ultimate framework for creating stunning, interactive documentation sites.
• In this tutorial, we’ll be creating a new documentation portal completely from scratch, and then hosting that on the web for free using GitHub pages.

• Along the way, I’ll show you just a handful of the awesome features that Material for MkDocs comes bundled with, such as:

  • Setting a dynamic colour scheme
  • Adding a splash of personality with emojis, icons and logos to make your content visually appealing
  • How to create custom code blocks that adjust based on the programming language specified
  • How to better organise your content using Tabs
  • How to empathize parts of your content using admonitions - also known as callouts
  • And how to bring your ideas to life with statically rendered diagrams directly in your docs

• Now you can follow along with me directly in this video, or if you prefer I have a written version of this tutorial available on my website

• I'll leave a link to the written tutorial in the description of this video.
• This is going to be a pretty in-depth tutorial. If this is your first time using Material for MkDocs then you're probably best to just follow it all through from the beginning.
• But if you've used Material for MkDocs before and just want to know about a certain feature, I've left all the timecodes below so you can jump around the video at your leisure.
• So if this sounds like something you'd be interested in, then breathe in, breathe out, and let’s explore this together 🙂

2. 'MkDocs' vs 'Material for MkDocs'

• Before we dive into the demo, let's quickly go over the differences between MkDocs and Material for MkDocs, as there is often some confusion.

• Plain MkDocs is a static site generator specifically designed for creating documentation websites. So by using MkDocs alone, you get a relatively vanilla and straightforward site for your documentation.

• On the other hand, Material for MkDocs is a theme built on top of MkDocs. It transforms your documentation site with a modern, responsive design inspired by Material Design principles. Now, what's important to note is that this theme doesn't just change the look; it enhances functionality with built-in plugins that support features like blog posts, social cards, advanced search capabilities and loads more.

• So basically, MkDocs provides the core functionality of building a static site, while Material for MkDocs signficantly elevates the visual and interactive experience of your documentation.

• Ok, now that's out of the way, let's get to work on setting up our new Material for MkDocs site.

3. Prereqs

• Before we jump in, let’s go over the prerequistes you’ll need to have installed if you want to follow along with this tutorial.

• Firstly, do be aware that i’ll be conducting this tutorial on a Mac. If you’re following on Windows then some of the commands we type into the terminal will be ever so slightly different… but I’ll try to call those out.

• So we’re going to be using the PYTHON version of MkDocs in this tutorial, and you’ll need to have PYTHON 3 installed. I’ll be using version 3.12.4 in this video, so either that or a later version should work fine.
• We’ll be using the Python package manager called PIP to install the required dependencies… but if you're running Python 3.4 or later then PIP is included anyway by default… otherwise if you’re using an earlier version of Python then you might need to install PIP.
• Now, to follow along with the coding, it’s helpful if you have an IDE installed, and I’ll be using Visual Studio Code in this video.
• And finally, we’ll be publishing our documentation portal on GITHUB PAGES… so you’ll need to have an account on GitHub and ideally have git installed and setup to work from the command line as well.

And that’s all you should need. So let’s jump over to a terminal and get started!

4. Initial Installation

• Open a terminal in the folder that you want to create the project in
• Do which python to show my Python is aliased to python3
• Do which python3 to show my Python is installed with Homebrew
  • Mention if you are running on Windows you can do where python instead
• Virtual environment setup with python -m venv venv
• source venv/bin/activate to activate virtual environment
  • (on Windows: .\venv\Scripts\activate)
• Check pip version pip --version
• Install mkdocs material - pip install mkdocs-material
• Open Visual studio code in this folder with code .
• Open a terminal within VS code and create the new site mkdocs new .
• Add basic mkdocs.yml configuration:

site_name: My MkDocs Material Documentation
site_url: https://sitename.example
theme:
  name: material

• Do mkdocs serve to launch the site
• Check the site at http://localhost:8000

5. Add Yaml Schema Validation

• Explain that to activate most of the useful features in MkDocs Material, we need to make a few changes to the mkdocs.yml file… making these changes is much easier with the help of YAML schema validation.
• Install the Yaml plugin within Extensions
  • Plugin can also be found on Visual Studio Marketplace
• In VsCode open settings.json. You can open this by clicking on settings in the bottom left gear icon, then clicking the document icon in the top right.
• Add the following at the bottom:

  "yaml.schemas": {
    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
  },
  "yaml.customTags": [
    "!ENV scalar",
    "!ENV sequence",
    "!relative scalar",
    "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
    "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
  ]

• Show the mkdocs.yml file and how we now get popups when we mouse over elements

6. Adjust Color Scheme

• Let's start making some changes to the style of our documentation, starting with the color scheme.
• I'll start by changing the color scheme to black. Add this to the mkdocs.yml file:

theme:
  name: material
  palette: 
    scheme: slate

• Change the primary colour to green by adding primary: green under the palette:

theme:
  name: material
  palette: 
    scheme: slate
    primary: green

• We can see that this makes the banner green, and also the hyperlinks green.
• Let's also change the accent colour to deep purple:

theme:
  name: material
  palette: 
    scheme: slate
    primary: green
    accent: deep purple

• Now when we hover over the links with the mouse, they turn purple.

• Another cool thing we can easily do in Material for MkDocs is add a toggle to our site that allows the user to switch between light and dark modes. Add this to palette in the mkdocs.yml file to enable this:

theme:
  name: material
  palette:
    # Dark Mode
    - scheme: slate
      toggle:
        icon: material/weather-sunny
        name: Dark mode
      primary: green
      accent: deep purple

    # Light Mode
    - scheme: default
      toggle:
        icon: material/weather-night
        name: Light mode
      primary: blue
      accent: deep orange

• There are lots of other configuration options available to you in Material for MkDocs if you want to adjust the colour, for example adding custom colours or automatically switching between light and dark mode based on the time of day

• For more information, check the colors documentation page

7. Adjust Font

• Let's see how we can change the font in our documentation.

• Material for MkDocs supports any Google font directly out of the box.

• Let's change the default font to Merriweather Sans :

theme:
  font:
    text: Merriweather Sans

• We can also change the font of the code in our docs:

theme:
  font:
    text: Merriweather Sans
    code: Red Hat Mono

• Now if you want to add additional fonts beyond Google fonts, or change other font configuration, do check the Material font documentation

8. Reminder to Like and Subscribe

• Before we go on, if you’re finding this video helpful, please hit the like button down below, and subscribe to the channel for more videos just like this.
• And if you're looking for more guides and tutorials around Material for MkDocs and technical documentation in general, then do checkout my website. I'll leave a link in the description.
• OK. Let’s carry on setting up our MkDocs Material site!

9. Using Emojs

• Another cool thing about Material for MkDocs is the possibility of using over 10,000 emojis and icons in your documentation, pretty much out of the box

• If you head over to the Material Emoji Documentation, you can easily search through everything that is available.
• To add the ability to use these to your documentation portal, add this config to your mkdocs.yml:

markdown_extensions:
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

• Then add a sentence to the index.md file with a couple of emojis

10. Logos and Icons

• Now that we have emojis and icons setup in our documentation, let's see how we can change the logo of our site.

Icon for Logo

• Search for solid-w and find the fontawesome icon we want to use for the logo.
• Change the icon by making this change to the mkdocs.yml

theme:
  icon:
    logo: fontawesome/solid/w

Image for Logo

• Mention how we could also change the logo to an image if we prefer.
• Inside the docs folder create an assets folder.
• Add the logo.png, which is our site logo that I generated earlier.
• Now change mkdocs.yml to:

theme:
  logo: assets/logo.png

Change Favicon

• Let's change the favicon as well.
• First i'll add the favicon.ico file to the assets folder we just created.
• Then adjust mkdocs.yml to:

theme:
  favicon: assets/favicon.ico

• You can change other icons on your MkDocs Material site in a similar way, but if you want to know more check the Material Logo and Icons Documentation

11. Code Blocks

• One of the best features of Material for MkDocs is it's ability to display code in a clear, crisp and distinctive manner.
• Let's create a new page in our documentation called code-examples.md
• And add in the following example Python code:

# Function to add two numbers
def add_two_numbers(num1, num2):
    return num1 + num2

# Example usage
result = add_two_numbers(5, 3)
print('The sum is:', result)

• Show the viewer the code in the browser - it looks OK but not colouring, let's change that next
• We need to add some extra configuration to our mkdocs.yml:

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

• Now go back and show the code is nicely highlighted
• Mention that if you want to use another language find the lexers (short names for the language) on this pygments page
  • e.g. typescript

Add Title

• Add a title to the codeblock by doing py title="add_numbers.py"

Add Line Numbers

• Add line numbers by doing py linenums="1"
• Also show the line numbers can start from a different number

Highlight Lines

• To highlight lines do py hl_lines="2-4"
• Use another codeblock to show this:

1
2
3
4
5
6
7
8

// Function to concatenate two strings
function concatenateStrings(str1, str2) {
  return str1 + str2;
}

// Example usage
const result = concatenateStrings("Hello, ", "World!");
console.log("The concatenated string is:", result);

12. Content Tabs

• Talk briefly about when content tabs would be useful, e.g. for different code examples
• To enable them, add this configuration to mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

• Create a new page called content-tabs.md
• Add the following to show generic content tabs:

## Content Tabs

This is some examples of content tabs.

### Generic Content

=== "Plain text"

    This is some plain text

=== "Unordered list"

    * First item
    * Second item
    * Third item

=== "Ordered list"

    1. First item
    2. Second item
    3. Third item

• Then show how we can use content tabs with code blocks, with this:

### Code Blocks in Content Tabs

=== "Python"

    ```py
    def main():
        print("Hello world!")

    if __name__ == "__main__":
        main()
    ```

=== "JavaScript"

    ```js
    function main() {
        console.log("Hello world!");
    }

    main();
    ```

13. Admonitions (aka Callouts)

• Admonitions - also known as callouts - are great for highlighting parts of the documentation.
• Add this configuration to mkdocs.yml:

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

!!! note "Title of the callout"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

• Show a collapisble admonition:

Collapsible callout:

??? info "Collapsible callout"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

• Briefly talk through the other examples shown on the Admonitions documentation

14. Diagrams

• Talk about use cases for diagrams such as flow charts, sequence diagrams, state diagrams

• Add configuration to mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

• Create a new page called diagram-examples.md
• Add a flowchart example:

# Diagram Examples

## Flowcharts

```mermaid
graph LR
  A[Start] --> B{Failure?};
  B -->|Yes| C[Investigate...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Success!];

• Add a sequence diagram:

## Sequence Diagrams

```mermaid
sequenceDiagram
  autonumber
  Server->>Terminal: Send request
  loop Health
      Terminal->>Terminal: Check for health
  end
  Note right of Terminal: System online
  Terminal-->>Server: Everything is OK
  Terminal->>Database: Request customer data
  Database-->>Terminal: Customer data

• Mention other examples of diagrams and show the diagrams documentation

15. Footer

• Enable the navigation footer in mkdocs.yml:

theme:
  features:
    - navigation.footer

• Add the social icons to the footer:

extra:
  social:
    - icon: simple/youtube
      link: https://youtube.com/@james-willett
    - icon: simple/linkedin
      link: https://linkedin.com/in/willettjames

• Add the copyright notice:

copyright: Copyright © 2024 James Willett

16. Publish site to GitHub Pages

• Create the .github/workflows/ci.yml file and paste in the example code:

name: ci 
on:
  push:
    branches:
      - master 
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force

• Create a brand new GitHub repository
• Hook up that GitHub repository remote with the project code (i.e. do git init then follow instructions to add the remote)
• Push branch to main on the GitHub repository
• Go to GitHub and into settings and change PAGES to deploy from branch and choose the gh-pages branch.
• Show GitHub Action running that deploys the site
• Show documentation is deployed and accessible

17. Outro

• In this video we've seen how to create and deploy an entire Material for MkDocs documentation website completely from scratch. We've then taken a look at just a few of the awesome features that Material for MkDocs ships with.

• We've only really scratched the surface of what Material offers in this video... so to learn more about the many other features that are on offer, do check out the official documentation

• But what about you? Are you using Material for MkDocs? What other features would you like to see covered? Let me know in the comments down below, I'd love to hear from you.

• But that's all for this video, I'll see you in the next one.