Skip to content

快速搭建技术博客 read the docs + stackedit

2026.02.23

现在发现，stackedit(中文版) + github(私有仓库) + mkdocs + cloudFlare 是更好的选择

与 readthedocs 相比，cloudFlare 允许绑定github的私有仓库，而这在 readthedocs 是付费功能

2024.07.18

搭建技术博客的方式有很多，目前我认为最便捷的一种是使用 read the docs + stackedit，优点有:

  • 一切操作都在浏览器中进行，不用在本地管理文档、编译项目
  • 网页自动更新，可以专注于写 markdown
  • 配置简单, 可以快速上手
  • 免费

操作步骤

  • 注册 stackedit (这里我使用的是 stackedit 中文版；stackedit 的 初始项目 已经不维护了, 并且原项目编辑 markdown 时不支持直接复制粘贴图片，而需要用到图床)，这是一个在线编辑 markdown 的平台，并且可以将 markdown 文件自动同步到 github 仓库中，选择同步到别的地方，比如 google drive、gitlab 等，也是可以的
  • 注册 read the docs, 将 github 仓库导入其中后，可以自动构建网页；当 github 仓库更新时，也会自动更新网页
  • 新建一个 github public repo (免费版 read the docs 不支持自动部署 private repo)，命名为 xxx, 然后新建 xxx/mkdocs.yml, xxx/docs/index.md, xxx/.readthedocs.yaml
    • 为什么新建这两个文件，是因为 read the docs 主要支持两种自动渲染网页的方式: mkdocs 与 sphinx. 我只用过 mkdocs。mkdocs 与 sphinx 都是用来构建静态网页的。这里只用知道 mkdocs.yml 用来设置网页渲染的参数，比如文档的结构，网站的标题等，index.md 就是网站首页上显示的内容。所有的内容都是 markdown 文件，并且都放在 xxx/docs/ 里面
    • 最简单的例子 (mkdocs.yml):

site_name: garnet技术笔记
nav:
  - Home: index.md
  - 文件归档:
      - 次级归档:
          - 文章标题: abc.md
theme:
  name: readthedocs
顾名思义， nav 是配置文档结构的，site_name 是网站标题。 以及 .readthedocs.yaml: 
# Read the Docs configuration file for MkDocs projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

mkdocs:
  configuration: mkdocs.yml
  • 打开 stackedit, 点击右上角打开菜单选项，将刚刚新建的 repo 绑定为一个文档空间。这样，你在 stackedit 里就可以直接编辑 docs/ 文件夹中的文件，并且所有的更改，都可以自动同步到 github 仓库中。但是 stackedit 只能编辑和创建后缀为 *.md 的文件，编辑 mkdocs.yml 需要在 github 中搞定
  • 打开 read the docs, 点击导入项目，将 xxx 这个 repo 导入进来，给项目取个名字 XXX (XXX 不能和已有的其他人的项目名重复)，之后 read the docs 就会根据 .readthedocs.yaml 中的设置，读取 mkdocs.yml, 然后渲染网页，并告诉你生成的网站的地址，一般是 XXX.readthedocs.io

经过以上配置，以后再想更新博客，只用在 stackedit 中更新文档，并在 github/xxx/mkdocs.yml 中更新网页中文档的排布结构即可，其余的操作，比如同步文档、渲染网页等，均为自动完成。以上所有操作均在浏览器中解决，非常方便

补充

美化网页

  • 主要靠修改 mkdocs.yml, 主要是 markdown_extensions, theme 和 extra_javascript 这几个参数。具体的参数说明，参考这里。 
    markdown_extensions:
  - attr_list
  - md_in_html  # https://squidfunk.github.io/mkdocs-material/reference/images/
  - markdown.extensions.codehilite
  - markdown.extensions.extra
  - pymdownx.superfences
  - pymdownx.arithmatex:
      generic: true
  - markdown.extensions.tables
  - toc:
      permalink: true       # 在每个标题旁添加链接
      toc_depth: 1-6


theme:
  # name: readthedocs
  name: material
  custom_dir: overrides
  palette:
    primary: 'indigo'       # 主颜色
    accent: 'pink'          # 强调颜色
  font:
    text: 'Roboto'          # 主文字字体
    code: 'Roboto Mono'     # 代码块字体
  features:
    - navigation.indexes    # 对于包含子页面的节，提供更好的索引页面
    - navigation.instant
    - navigation.path       # 在文档顶部也显示当前文档的 
    - navigation.top
    - palette.switcher      # 主题色切换
    - search.suggest        # 搜索建议
    - search.highlight      # 搜索关键词高亮
    - instant.loading       # 启用页面的即时加载
    - navigation.footer

extra_javascript:
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML-AM_CHTML

注意 .readthedocs.yaml 也要同时修改，加上以下内容可以使 read the docs 构建项目时提前安装必要的 package

python:
  install:
    - requirements: requirements.txt

并在项目中添加 requirements.txt

mkdocs>=1.6
mkdocs-material
pymdown-extensions

显示网站访问人数

  • 注册 histats
  • 在 histats 上面绑定自己的网页
  • 在 histats -> counter codes 中选择一个显示条的样式，选好后会自动生成一段 html 代码
  • 参考这里，在 mkdocs 项目中，新建 docs/overrides/partials/footer.html，然后把刚才 histats 生成的代码粘贴进来。这样本应该显示 mkdocs 的 footer 样式的地方，就会被 histats 的显示条替代
  • 修改 mkdocs.yml，主要是下面的几个地方 
    theme:
  name: material
  custom_dir: overrides
  features:
    - navigation.footer

如果想要 google statics 统计网站信息的话，参考这里，注册 google statics, 然后在 mkdocs.yml 添加如下代码就可以: 

extra:
  analytics:
    provider: google
    property: G-XXXXXXXX  # your G-code