部署MKDocs¶

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



## 1 使用MKDocs创建笔记

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

mkdir tmp
cd tmp
git init

pip install mkdocs-material
pip install mkdocs-minify-plugin

mkdocs new .

2 搭建写作环境¶

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

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

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

必须安装 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 sqlite3

db_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_list

def 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:
            break
        if key.endswith('.md'):
            page_tree.append(key) 
        else:
            subtree = get_page_tree(key+"/")
            if subtree:
                page_tree.append({key.split('/')[-1]: subtree})
    return page_tree

page_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 = False
    for line in file:
        if 'nav:' in line:
            delete_mode = True
        if not delete_mode:
            output_lines.append(line)
        if delete_mode and not line.strip():
            delete_mode = False

with open(order_yaml_path, 'r', encoding='utf-8-sig') as file:
    delete_mode = False
    for 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 自动部署¶

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

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

仓库配置 github-actions

name: Deploy

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:   
    - name: executing remote ssh commands to develop
      uses: appleboy/ssh-action@master
      with:
        host: ${{ secrets.DEPLOY_HOST }}
        username: ${{ secrets.DEPLOY_USER }}
        password: ${{ secrets.DEPLOY_PASSWORD }}
        port: 22
        script:  sh /home/build.sh

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

on:
  push:
    branches:
      - dev

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