2023/10

Enhance your mkdocks.yml

In the previous post I explained how to create a blog with MkDocs and mkdocs-material theme.

mkdocs.yml is the configuration file for MkDocs. In this file we can configure the theme, the plugins, the pages, etc.

In this post I am going to explain you how to create a blog with MkDocs and mkdocs-material theme, add some plugins and configure it.

Minimal configuration for mkdocs.yml with mkdocs-material

site_name: My Site
theme: 
  name: material
#plugins:

#markdown_extensions:

Theme

I only change the palette for now.

theme: 
  name: material
  palette:
    primary: blue
    accent: white  

Plugins for mkdoc

glightbox

glightbox add image zoom functionality to your documentation.

mkdocs-glightbox

plugins:
  - glightbox

Example:

Imagen de marymarkevich en Freepik

mkdocs-minify-plugin

An MkDocs plugin to minify HTML, JS or CSS files prior to being written to disk.

mkdocs-minify-plugin

Extensions

Material for MkDocs

MkDocs supports a large number of Python Markdown extensions

mermaid

mermaid2 is a plugin for MkDocs that allows you to embed diagrams written in mermaid.js in your Markdown documentation.

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

  ```mermaid
  graph LR
      A[Square Rect] -- Link text --> B((Circle))
      A --> C(Round Rect)
      B --> D{Rhombus}
      C --> D
  ```

graph LR
    A[Square Rect] -- Link text --> B((Circle))
    A --> C(Round Rect)
    B --> D{Rhombus}
    C --> D

You can find more information about mermaid.js in https://mermaid-js.github.io/mermaid/#/

Admonitions

Admonitions is a markdown extension of materials for MkDocs that allows you to add admonition blocks to your Markdown documentation.

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

Example:

!!! Example
    Example
!!! Error
    Error
!!! Warning
    Warning    
!!! Success
    Success
!!! Info
    Info    
!!! Tip
    Tip
!!! Question
    Question
!!! Quote
    Quote

Icons, Emojis

With material you can use more than 10000 icons and thousand of emojis in your documentation.

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

Example:

:smile:
:man_head:
:face_with_monocle:
:jack_o_lantern:

Annotations

One of the flagship features of Material for MkDocs is the ability to inject annotations – little markers that can be added almost anywhere in a document and expand a tooltip containing arbitrary Markdown on click or keyboard focus.

markdown_extensions:
  - attr_list
  - md_in_html
  - pymdownx.superfences

Examples:

This is a paragraph with a annotation(1).
{ .annotate }

1.  :man_raising_hand: I'm an annotation! I can contain `code`, __formatted
    text__, images, ... basically anything that can be expressed in Markdown.

This is a paragraph with a annotation(1).

1. I'm an annotation! I can contain code, formatted text, images, ... basically anything that can be expressed in Markdown.

This is a paragraph with a annotation(1).
{ .annotate }

1.  :man_raising_hand: I'm an annotation! with a nested annotation(1)
    { .annotate }

    1. I'm a nested annotation!

This is a paragraph with a annotation(1).

1. I'm an annotation! with a nested annotation(1)

   1. I'm a nested annotation!

Buttons

markdown_extensions:
  - attr_list  

Examples:

[This is a button](#)
{ .md-button }

This is a button

[This is a button](#)
{ .md-button .md-button--primary }

This is a button

[Send :fontawesome-regular-face-laugh-wink:](#){ .md-button }

Send

Content tabs

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

Example:

=== "azcli"

    ``` azcli    
    az group create --name myResourceGroup --location westeurope
    ```

=== "pwsh"

    ``` pwsh    
    New-AzResourceGroup -Name myResourceGroup -Location westeurope    
    ```

az group create --name myResourceGroup --location westeurope

New-AzResourceGroup -Name myResourceGroup -Location westeurope    

Footnotes

markdown_extensions:
  - footnotes

Example:

This is a paragraph with a footnote[^1].

[^1]: And here is the definition.

This is a paragraph with a footnote¹.

Formatting

markdown_extensions:
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde

Example:

- ~~Mistaken text.~~
- ^^Superscript^^
- ==Marked text.==

• Mistaken text.
• Superscript
• Marked text.

mkdocs.yml complete

site_name: My Site
site_description: A blog about Azure, DevOps and other stuff
site_author: Rafael Fernández
site_url: https://rfernandezdo.github.io

theme: 
  name: material
  palette:
    primary: blue
    accent: white
  features:
    - navigation.tabs
    - navigation.expand
    - navigation.sections
    - toc.integrate
    - toc.nested
    - toc.smoothscroll
    - footer
    - content.code.copy
    - content.code.annotate
    - content.tooltips
extra:
  social:
    - icon: fontawesome/brands/linkedin
      link: https://www.linkedin.com/in/rafaelfernandezd/
      name: LinkedIn
    - icon: fontawesome/brands/github
      link: https://github.com/rfernandezdo
      name: GitHub
    - icon: fontawesome/solid/square-rss
      link: https://rfernandezdo.github.io/feed_rss_created.xml
      name: RSS feed
copyright: Copyright © 2023-now Rafael Fernández

plugins:
  - search  
  - mermaid2
  - blog  
  - tags:
      tags_file: tags.md    
  - rss:
      match_path: blog/posts/.* 
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
          remove_comments: true
      cache_safe: true
  - glightbox:
      zoomable: true
      draggable: true
      skip_classes:
        - skip-lightbox
    #- meta in insiders, review in next release
  - social
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - md_in_html
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - footnotes
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true

urls for reference

• Font Awesome
• Emojis ...

Create a blog with MkDocs,mkdocs-material, mkdocs-rss-plugin and GitHub Pages

A few time ago I maintained a blog with Wordpress. I was happy with it, but I wanted to try something new.

I tried Jekyll but it didn't convince me, I discovered mkdocs so I decided to use MkDocs and mkdocs-material. I was happy with the result, so I decided to write this post to explain how to create a blog with MkDocs, mkdocs-material and some plugins.

These is the first post of a serie of posts to create a blog with MkDocs, mkdocs-material and GitHub Pages and some customization.

Some knowledge:

• MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

• Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation. It is built using Google's Material Design guidelines. Material for MkDocs provides a polished and responsive experience out of the box, and it is as easy to use for the beginner as it is for the seasoned developer.

• GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website. You can see more information about GitHub Pages here.

• This plugin generates an RSS feed for your MkDocs site. You can see more information about mkdocs-rss-plugin here.

Steps to deploy

Create a new repository

Create a new repository on GitHub named username.github.io, where username is your username (or organization name) on GitHub. If the first part of the repository doesn’t exactly match your username, it won’t work, so make sure to get it right.

Enable GitHub Pages on your repository

Go into the repository settings and, if you are not using GitHub Pages already, enable GitHub Pages on the gh-pages branch.

Clone the repository

Go to the folder where you want to store your project, and clone the new repository:

git clone ssh://github.com/username/username.github.io
cd username.github.io

Create requirements.txt in root folder for mkdocs, mkdocs-material and plugins

mkdocs==1.5.3
mkdocs-material==9.4.6
mkdocs-rss-plugin==1.8.0

Create a Python Virtual Environment and install requirements.txt

In username.github.io$ path:

sudo apt update
sudo apt install libcairo2
sudo apt install python3.10-venv
python3 -m venv mysite
source mysite/bin/activate
pip install -r requirements.txt

Initialize your site

mkdocs new .

Add configuration to mkdocs.yml in root folder

For this post I am going to add the following configuration:

• basic configuration
• configuration for theme mkdocs-material
• some native plugins of mkdocs-material and some ones that I like

site_name: My Site 
site_description: A blog about Azure, DevOps and other stuff
site_author: Rafael Fernández

theme: 
  name: material
  features:
    - navigation.tabs
    - navigation.expand
    - navigation.sections
    - toc.integrate
    - toc.nested
    - toc.smoothscroll
    - footer

plugins:
  - search  
  - blog
  - tags:
      tags_file: tags.md      

  - rss:
      match_path: blog/posts/.* 
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags

Add a new post

In blog/post folder create a new folder with the name of the post and create a new file with the name of the post and the extension .md. For example: welcome.md

---
date: 2023-10-18
categories:
  - Hello
  - World
---

# "Hello world!!!" from mkdocs-material

...

Check your site

In username.github.io$ path:

mkdocs serve

You can check your site in http://127.0.0.1:8000/ and make live changes in your site and see the results in your browser.

Publish your site

In username.github.io$ path:

mkdocs gh-deploy

After a seconds, you can check your site in https://username.github.io/

Automate deploy with GitHub Actions

name: ci # (1)!
on:
  push:
    branches:      
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install -r requirements.txt # (4)!
      - run: mkdocs gh-deploy --force

1. You can change the name to your liking.

2. At some point, GitHub renamed master to main. If your default branch is named master, you can safely remove main, vice versa.

3. Store the cache_id environmental variable to access it later during cache key creation. The name is case-sensitive, so be sure to align it with ${{ env.cache_id }}.

   • The --utc option makes sure that each workflow runner uses the same time zone.
   • The %V format assures a cache update once a week.
   • You can change the format to %F to have daily cache updates.

   You can read the [manual page] to learn more about the formatting options of the date command.

4. Add [MkDocs plugins] or Markdown extensions with pip to requirements.txt to be used during the build.

In the next post I will explain how to customize your site with mkdocs-material and some plugins writing mkdocs.yml.

That's it folks

urls for reference

• https://www.mkdocs.org/
• https://pages.github.com/
• https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/
• https://guts.github.io/mkdocs-rss-plugin/ ...

"Hello world!!!" from mkdocs-material

...