搭建 MkDocs 并部署到 Github Pages

Installation

Install python

check if Python and Python package manager, pip is installed.

C:\Users\Kevin>python --version
Python 3.11.6
C:\Users\Kevin>pip --version
pip 24.0 from C:\Program Files\Python\Python312\Lib\site-packages\pip (python 3.12)

Install mkdocs

pip install mkdocs

check if mkdocs is installed

C:\Users\Kevin>mkdocs --version
mkdocs, version 1.6.0 from C:\Program Files\Python\Python312\Lib\site-packages\mkdocs (Python 3.12)

Install git

check if git is installed

C:\Users\Kevin>git --version
git version 2.44.0.windows.1

Create MkDocs

Build

  • mkdocs new [dir-name] - Creat a new project in desired file path.
  • mkdocs serve - Start the live-reloading docs server, visit 127.0.0.1:8000 to see the local site.
  • mkdocs build - Build the documentation site. A new folder "site" will be generated to be deployed.
  • mkdocs -h - Print help message and exit.

File structure

mkdocs.yml        # The configuration file.
site/             # The site 
    ...
docs/
    CNAME         # The self-defined domain file.
    index.md      # The documentation homepage.
    ...           # Other markdown pages, images and other files.
    dir/          # if nacessary, new folder is supported.
        index.md
        ...

Configration

The mkdocs.yml file:

site_name: Liuwk Space

# MkDocs theme
theme: readthedocs

# Latex configration: a html file and python-markdown-math extension is nacessary
extra_javascript:     
  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js?config=TeX-AMS-MML_HTMLorMML
markdown_extensions:
  - mdx_math:
      # inline equation $...$ configration
      enable_dollar_delimiter: true

# To hide navigation of home page 
not_in_nav: |
  /index.md

Deploy Github Pages

Creat a new public repo, repository name should be username.github.io.

In the root path of your mkdocs folder

git init            # initial git
git remote add origin https://github.com/username/username.github.io.git
mkdocs gh-deploy    # This command will creat a gh-pages branch and push content to it.

Once the content changes, run command mkdocs build && mkdocs gh-deploy.

Latex test

Inline equation: .

Block equation: