良好的文档是项目成功的关键。它不仅帮助开发者理解项目结构和代码逻辑，还是新团队成员快速上手的桥梁。MkDocs可以帮助我们构建出既美观又功能丰富的技术文档。

1、mkdocs简介

MkDocs 是一个快速、简单且功能丰富的静态站点生成器，专为项目文档设计。它允许你用 Markdown 编写文档，然后通过一个简洁的命令生成一个静态网站。MkDocs 的核心优势在于它的简洁性、速度和易于使用。

主要特点：

  • 纯 Python 编写：不需要复杂的依赖关系。
  • Markdown 支持：使用 Markdown 编写文档，易于阅读和编写。
  • 静态站点生成：生成静态 HTML 页面，可以轻松部署到任何静态文件服务器或 CDN 上。
  • 实时预览：开发时提供实时预览功能，所见即所得。
  • 自定义主题：支持自定义主题，可以轻松定制文档的外观。

2、MkDocs-Material

MkDocs-Material 是 MkDocs 的一个非常受欢迎的主题，它基于 Google 的 Material Design。它不仅提供了一个现代、响应式的设计，还包含了许多增强功能，如搜索、版本切换和脚注等。

特点：

  • 响应式设计：适配各种屏幕尺寸，无论是桌面还是移动设备。
  • 内置搜索：提供快速、高效的搜索功能，方便用户查找文档内容。
  • 版本切换：支持多版本文档，方便用户查看不同版本的信息。
  • 丰富的组件：包括代码块、图表、表格等，丰富文档的表现力。
  • 易于定制：通过 CSS 和 JavaScript 定制主题，满足个性化需求。

3、简单使用

在python环境中安装：

1
2
pip install mkdocs
pip install mkdocs-material

创建一个新的 MkDocs 项目目录，并初始化：

1
2
3
mkdir my-project
cd my-project
mkdocs new .

运行以下命令生成文档：

1
mkdocs build

这将在 site 目录下生成静态 HTML 文件。

要查看实时预览，运行：

1
mkdocs serve

现在，你可以在浏览器中访问 http://127.0.0.1:8000 查看你的文档。

4、配置文件

可以在mkdocs.yml中进行系统的配置。如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
site_name: 个人知识库
site_url: https://blog.agiexplained.com
site_author: Eryx Lee
docs_dir: .

# 配置主题
theme:
  name: material
  palette:
    # primary: blue grey
    - scheme: default # 日间模式
      primary: grey # 上方的
      accent: cyan # 链接等可交互元件的高亮色
      toggle:
        icon: material/weather-night # 图标
        name: 切换至夜间模式 # 鼠标悬浮提示
    - scheme: slate # 夜间模式
      primary: black 
      accent: cyan
      toggle:
        icon: material/weather-sunny
        name: 切换至日间模式
  features: 
    - navigation.instant #- header.autohide  #自动隐藏
    #- announce.dismiss #呈现可标记为由用户读取的临时公告，可以包含一个用于取消当前公告的按钮
    - navigation.tracking #地址栏中的 URL 将自动更新为在目录中突出显示的活动锚点
    - navigation.tabs #顶级部分将呈现在上面视口标题下方的菜单层中，但在移动设备上保持原样
    #- navigation.tabs.sticky  #启用粘性选项卡后，导航选项卡将锁定在标题下方，并在向下滚动时始终保持可见
    #- navigation.sections #启用部分后，顶级部分在边栏中呈现为1220px以上视口的组，但在移动设备上保持原样
    - navigation.top # 返回顶部的按钮 在上滑时出现
    - search.suggest # 搜索输入一些字母时推荐补全整个单词
    - search.highlight # 搜索出的文章关键词加入高亮
    - navigation.expand # 打开Tab时左侧目录全部展开
    #- navigation.indexes #启用节索引页后，可以将文档直接附加到节
    - search.share #搜索分享按钮
  language: zh

# copyright: Copyright © 2024 Eryx Lee # 左下角的版权声明

extra:
  generator: false  #删除页脚显示“使用 MkDocs material制造”
  social:
    - icon: fontawesome/brands/twitter 
      link: https://twitter.com/
    - icon: fontawesome/brands/github
      link: https://github.com/eryxlee
    - icon: fontawesome/brands/bilibili
      link: https://
    - icon: fontawesome/solid/paper-plane
      link: mailto:<eryxlee@163.com> #联系方式

plugins:
  - search
  - same-dir
  - awesome-pages
  - autorefs
  - exclude:
      glob:
        - .obsidian/*
        - "index*.html"
        - ".*"
        - "_*.md"
        - "*.tmp"
        - "*.pdf"
        - "*.gz"
      regex:
        - '.*\.(tmp|bin|tar)$'

markdown_extensions:
  - abbr
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
  - md_in_html
  - pymdownx.arithmatex:  # latex支持
      generic: true
  - toc:
      permalink: true # 固定标题位置为当前位置
  - pymdownx.highlight: # 代码块高亮
      anchor_linenums: true
      linenums: true # 显示行号
      auto_title: true # 显示编程语言名称
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.superfences # 代码块高亮插件
  - meta # 支持Markdown文件上方自定义标题标签等

5、在Docker中使用

为了在Docker中运行MkDocs，需要从MkDocs-Material的Github上下载代码，使用其中已经准备好的Dockerfile。这个Dockerfile将会安装MkDocs、MkDocs-Material所需要的所有依赖包，并且预留了一个user-requirements.txt文件，其中可以填入自己所需要的第三方插件，如：

1
2
3
4
mkdocs-same-dir~=0.1.3
mkdocs-autorefs~=1.2.0
mkdocs-exclude~=1.0.2
mkdocs-awesome-pages-plugin~=2.9.3

之后就可以使用Docker build命令编译适合自己的镜像了。

6、在k8s上运行

构建deployment、service文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
apiVersion: apps/v1
kind: Deployment 
metadata: 
  name: mkdocs
spec: 
  selector: 
    matchLabels: 
      app: mkdocs 
  replicas: 1 # tells deployment to run 2 pods matching the template 
  template: 
    metadata: 
      labels: 
        app: mkdocs 
    spec: 
      containers: 
      - name: mkdocs 
        image: eryxlee0901/mkdocs:latest
        volumeMounts:
        - name: mkdocs-data
          mountPath: /docs  # 这是Pod内部的目录路径
        ports: 
        - containerPort: 8000
      volumes:
      - name: mkdocs-data
        hostPath:
          path: /root/kb  # 这是主机上的目录路径
          type: DirectoryOrCreate

1
2
3
4
5
6
7
8
9
10
11
12
13
kind: Service 
apiVersion: v1 
metadata: 
  name: mkdocs-service 
spec: 
  selector: 
    app: mkdocs 
  ports: 
  - protocol: TCP 
    port: 8000
    targetPort: 8000
    nodePort: 30000
  type: NodePort

然后就可以用http://(IP):30000进行站点访问了