How To Build A Personal Blog With MkDocs

How This Blog Was Built

The first post is about the blog itself — a write-up of every decision and step that went into putting this site together.

If you are setting up a similar lightweight developer blog with is first-class, not an afterthought.

Step-by-step Setup

1. Scaffold

uv manages dependencies with a lockfile (uv.lock) so builds are reproducible.

uv init

uv add mkdocs-material pillow cairosvg \

  mkdocs-git-revision-date-localized-plugin \

  mkdocs-rss-plugin

After that, mkdocs.yml and docs/index.md are the only files you touch. Replace index.md with your landing page.

Local dev server:

uv run mkdocs serve    # → http://127.0.0.1:8000

2. Core Configuration

mkdocs.yml is the single source of truth. Here is what goes in:

# Blog plugin — posts, archive, categories, pagination

plugins:

  - blog:

      blog_dir: blog

      post_dir: "{blog}/posts"

      archive: true

      categories: true

      pagination: true

      pagination_per_page: 10

      authors_file: "{blog}/.authors.yml"



  # Tags — auto-generates tag index pages

  - tags



  # Search with Chinese tokenization

  - search:

      lang: [en, zh]



  # RSS

  - rss:

      match_path: blog/posts/.*

3. Bilingual Strategy

No separate site builds, no mkdocs-static-i18n plugin. Just a directory convention:

docs/blog/posts/

├── en/    ← English posts go here, tagged `english`

└── zh/    ← 中文文章放这里，tag `chinese`

It may be time-consuming for writing articles in two different languages. However, I prefer a full control of the content I wrote.

Search indexes both languages — the lang: [en, zh] line above tells the built-in segmenter to handle CJK characters. Readers filter by language via the tag system.

4. GitHub Actions CI

A single workflow file (.github/workflows/ci.yml) does three things on every push to Master:

1. Checkout the repo (full depth, needed for git-revision-date-localized)


2. 
   pip install dependencies + mkdocs build
   


3. 
   actions/deploy-pages to publish

Set Settings → Pages → Source → GitHub Actions in the repo and you are done.

5. Analytics & Comments

Google Analytics 4 — one block in mkdocs.yml:

extra:

  analytics:

    provider: google

    property: G-XXXXXXXXXX

giscus — free, no-ads comment system powered by GitHub Discussions. Enable Discussions in the repo settings, install the .

Go write something~