文档生成工具

Markdown生成网页流程

修订记录

时间	内容	修订人
2026-03-07	创建	胡英万

一、环境准备

1.安装 mkdocs

# 使用 pip 安装
pip install mkdocs
pip install mkdocs-material
pip install mkdocs-git-revision-date-localized-plugin
pip install pillow cairosvg
## uv管理
uv add mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin pillow cairosvg

# 生成项目
mkdocs new {项目名称}

2. 目录结构

my-docs/ ├── docs/ # 存放所有 Markdown 文件 │ ├── index.md # 首页 │ ├── guide.md # 使用指南 │ └── ... # 其他文档 ├── mkdocs.yml # 配置文件 └── requirements.txt # Python 依赖（可选）

3.启动项目命令

# 启动服务
mkdocs serve
# 构建
mkdocs build
#部署
mkdocs gh-deploy

#中文分词
pip install jieba

4.配置文件

site_name: 我的技术博客
site_author: h.yw

# 主题：使用 Material 主题
theme:
  name: material
  language: zh
  features:
    - navigation.top #返回顶部按钮
    - search.suggest # 搜素建议
    - content.code.copy #代码复制按钮
  #    - navigation.expand
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换暗色模式
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换亮色模式


# 导航栏
nav:
  - 首页: index.md
  - 笔记:
      - 文档生成工具: "文档生成工具.md"
      - 更换系统软件源: "更换系统软件源.md"



# 插件
plugins:
  - search:
      lang: zh                       # 语言设置，中文用 zh
      #      separator: '[\s\-]+'            # 分词规则（支持空格和连字符）
      min_search_length: 3            # 最小搜索字符数
      indexing: 'full'                # 索引模式：full(全文)/sections(标题)/titles(仅页面标题)
      prebuild_index: false           # 是否预建索引（可设为 true 或 "node"）
      separator: '[\s\u200b\-]'  # 特殊的Unicode字符辅助分词
#  - frontmatter   # 添加这个

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      # 其他扩展也保持相同缩进，例如：
  - admonition
  - toc:
      permalink: true

5.分词修改源码py文件

import jieba  # 在文件开头添加

class SearchIndex:
    # ... 其他代码

    def _add_entry(self, title, text, loc):
        # 原代码：清理空格等
        text = text.replace('\u3000', ' ')
        text = text.replace('\u00a0', ' ')
        text = re.sub(r'[ \t\n\r\f\v]+', ' ', text.strip())

        # 新增：中文分词（正文）
        seg_list = jieba.cut_for_search(text)  # 搜索引擎模式
        text = " ".join(seg_list)

        # 新增：标题分词
        seg_title = jieba.cut(title, cut_all=False)  # 精确模式
        title = " ".join(seg_title)

        self._entries.append({
            'title': title,
            'text': text,
            'location': loc
        })

6.使用vitepress构建文档