【运维】部署MKDocs

部署MKDocs

obsidian 记录笔记，通过 mkdocs 私有化部署。

1 使用MKDocs创建笔记

创建仓库，安装 Material for MkDocs 和 mkdocs-minify-plugin

mkdir tmp
cd tmp
git initpip install mkdocs-material
pip install mkdocs-minify-pluginmkdocs new .

2 搭建写作环境

1. 打开 Obsidian
2. 打开本地仓库，选择 tmp/docs
3. 安装常用插件，搭建写作环境

插件根据个人喜好，我用来做工作笔记，核心插件只保留了 大纲、命令面板、模板。

白板、关系图谱、双链等等我都用不到，组织文件和搜索通过插件实现。

必须安装 MAKE.md 或者 obsidian-bartender 或者其他可以自定义顺序的插件。

• Git 备份数据
• Number Headings 文档标题编号
• Commander 隐藏各种不需要的图标和功能
• Editing ToolBar 增加一些快捷键
• MAKE.md 组织文件、搜索

3 辅助脚本

3.1 配置MKDocs

就是参考 mkdocs-material的官网配置ymal。配置比较长就不贴了放在 gist。

3.2 自定义文章顺序

mkdocs 直接部署文章顺序无法自定义，通过解析 MAKE.md 或者 obsidian-bartender 的数据实现自定义顺序。下边这段是解析 mkdocs 的，如果使用 obsidian-bartender 可以看 gist。

import os
import yaml
import json
import sqlite3db_name = '.space/context.mdb'
base_directory = './docs/'
ignore_directory = ["Todo"]
order_yaml_path = 'script/refactoring_directory.yml'
mkodcs_yml = 'mkdocs.yml'def get_context_bt_db(path):conn = sqlite3.connect(path + db_name)cursor = conn.cursor()cursor.execute("SELECT File FROM files")file_list = [row[0] for row in cursor.fetchall()]conn.close()return file_listdef get_page_tree(relative_path=""):page_tree = []order_tree = []order_tree = get_context_bt_db(base_directory + relative_path)for key in order_tree:if key in ignore_directory:breakif key.endswith('.md'):page_tree.append(key) else:subtree = get_page_tree(key+"/")if subtree:page_tree.append({key.split('/')[-1]: subtree})return page_treepage_tree = {"nav": get_page_tree()}
print(page_tree)with open(order_yaml_path, 'w', encoding='utf-8-sig') as yaml_file:yaml.dump(page_tree, yaml_file, default_flow_style=False, allow_unicode=True)output_lines = []
with open(mkodcs_yml, 'r', encoding='utf-8-sig') as file:delete_mode = Falsefor line in file:if 'nav:' in line:delete_mode = Trueif not delete_mode:output_lines.append(line)if delete_mode and not line.strip():delete_mode = Falsewith open(order_yaml_path, 'r', encoding='utf-8-sig') as file:delete_mode = Falsefor line in file:output_lines.append(line)with open(mkodcs_yml, 'w', encoding='utf-8-sig') as file:file.writelines(output_lines)

3.3 github 自动部署

1. 创建 github 仓库
2. 将本地仓库链接到 github
3. 服务器 pull 仓库，并放置部署脚本 /home/build.sh

#!/bin/sh
cd /home/MyBlog
git pull
mkdocs build

4. 仓库配置 github-actions

name: Deployon:workflow_dispatch:jobs:deploy:runs-on: ubuntu-lateststeps:   - name: executing remote ssh commands to developuses: appleboy/ssh-action@masterwith:host: ${{ secrets.DEPLOY_HOST }}username: ${{ secrets.DEPLOY_USER }}password: ${{ secrets.DEPLOY_PASSWORD }}port: 22script:  sh /home/build.sh

我是手动执行 actions，使用的 workflow_dispatch，自动部署的话绑定到对应分支：

on:push:branches:- dev

5. mkdocs 编译后是静态网站（同级目录的 site），用宝塔或者 nginx 绑定域名。