How to Use Markdown and Mkdocs to Write and Organize Technical Notes

2 min readFeb 3, 2021

· Part 1: Introduction
· Part 2: Package Installation
· Part 3: Docs Structure
· Part 4: Documentation Website Generation
· Part 4: Mkdocs Enhancement
· Reference

Part 1: Introduction

In the past few years, I have been using Markdown to write technical notes and then I use Mkdocs to organize them. Here is a summary of my experience.

Part 2: Package Installation

Software Installation

python with Mkdocs (pip install mkdocs)
visual studio code with Markdown (Markdown All in One)

Additional Plugins

pip install mkdocs-jupyter makes mkdocs supports jupyter-notebook
pip install mkdocs-material and pip install mkdocstrings make mkdocs support Python code documentation

Part 3: Docs Structure

File/Folder Structure

├── docs
│   ├── 1.docker_command.md
│   ├── 2.docker_scripts.md
│   ├── 3.development_setup.md
│   ├── index.md
└── mkdocs.yml

It is composed of three parts:

mkdocs.yml
docs/index.md
docs/1.docker_command.md

mkdocs.yml

site_name: Docker
nav:
  - Home: index.md
  - Knowledge:
      - 1.docker_command.md
      - 2.docker_scripts.md
      - 3.development_setup.md
theme: readthedocs

site_name: name of the site
nav: how to organize Markdown files
theme: the template

docs/index.md

# My Docker JourneyI use this website to keep trace of my Docker learning experience.

This file is the introduction page.

docs/1.docker_command.md

# Docker Commands## 1. Image- list all images `docker images`- work on an individual image- `docker build --no-cache -t image_name .` build the image without using cache| normally when building a image we use cache- `docker image rm image_id` remove image cache

This is a technical note.

Part 4: Documentation Website Generation

mkdocs serve to check the website at http://127.0.0.1:8000/

Part 4: Mkdocs Enhancement

Enable Python Codes Documentation

(1) mkdocs.yml

site_name: My Docs
pages:
  - Home: 'index.md'
  - About: 'about.md'
  - Python Code Documentation:
      - src: 'enhanced_str.md'
      
theme:
  name: "material"plugins:
        - search
        - mkdocstrings

(2) ‘enhanced_str.md’

# enhanced_str
::: my_lib.data.directory
::: my_lib.data.file

Enable Jupter Notebook

mkdocs.yml

  - sample:
    - sample/classification/classification_simple.ipynbplugins:
  - mkdocs-jupyter

Enable Rich Formatting Feature via pymark

theme: material #readthedocs
markdown_extensions:
    - pymdownx.superfences
    - pymdownx.tasklist
    - pymdownx.tabbed

Reference

Blogs

Plugins