博客园Markdown部署方案: md2blog

目录

仓库地址： gitee.com/brt2/md2blog

1. 设计目标

  • 文档存储
    • 可下载link图像，进行本地化存储
    • 压缩内嵌图像，最小化上传
  • 支持随时浏览 & 快速查找
    • 同步到cnblog!
    • 支持mkdocs的发布
    • 支持hugo编译成静态文件

2. 各平台的对比

  • cnblog
    • 支持查找
    • 无需搭建个人服务器
    • 不支持文档排序
  • mkdocs
    • 支持动态修改md和实时渲染
    • 支持主题切换
    • 需要个人服务器（内网限制）
  • gitbook（hugo/hexo）
    • 支持hugo多皮肤更换
    • 使用git快速部署，无需个人服务器
    • 尚不支持查找功能（待确认）
    • 不支持动态更新，编译的过程较复杂

3. 流程设计

  1. 编写md文档，或使用“简阅”下载markdown
  2. 修改文档内容，可以正常在本地浏览器渲染即可
  3. 通过封装好的git_push.sh执行上传
    • 利用fmt_md.py格式化文档
      • head元数据
      • 去除H1标题
      • 检测权重，通过权重配置mkdocs的目录结构
    • 选择是否下载link图像（download_img_link.py）
    • 图片压缩（png2jpg_md_img.py）
    • 使用db_mgr.py对文档树进行管理
    • upload_cnblog.py上传到“博客园”
    • git commit & push 当前仓库

4. 规范要求

  • 目录

    应该按照一定的分类标准，对所有的文档进行放置。

  • 文件命名

    关于blog的title采用如下策略：

    • 优先使用"description": 一句吸引人眼球的标题，例如：“他写微信软文赚了1173万元，愿意手把手教你文案秘籍——只在这周六”（博客也需要标题党）
    • "title": 如果"description"为空（默认），则使用title作为标题，这个可以“程序化”，简洁明了——“git rebase 使用技巧”
    • 文件名仅用于本地文件记录，与blog的title并不对应。
    • 文件名影响mkdocs的排序：
      • 文件名是mkdocs的默认排序规则
      • mkdocs通过程序，索引文章的weight，并记录于_index.md中

  • 标签

    通过hugo_info记录标签，并跟踪至数据库json中（由于db不支持git跟踪，改为json）。

  • git管理

    可以直接使用git来指示upload_cnblog.py对文档的上传管理：

    1. 对于需要上传或更新的文档，使用 git add 添加到repo中
    2. 执行 python3 upload_cnblog.py -a 自动查询当前repo的变化
    3. upload_cnblog格式化Markdown文件，上传至cnblog，并改写本地数据库表
    4. 自动更新当前repo——由于added文档格式化，需要重新add。同理图像目录也需要重新添加仓库，以及 .database.json 数据库
    5. 实现对 git commit 的提交

  • 简化操作

    • 创建新文件时使用格式模板
    • 上传时自动格式化Markdown文件
    • 自动对Headings排序，生成层级索引——“1.2.4”
    • 图像不会进行重复上传
    • 自动压缩图像，减小空间占用
    • 自动png转jpg
    • 支持过高分辨率的resize压缩
    • 自动实现category的管理
    • 支持label管理
    • 支持文档目录自动生成

5. 使用

# 创建Git-Repo
cd REPO_DIR
git init
...

# 创建配置文件，初始化仓库路径
git clone git@gitee.com:brt2/md2blog.git
cd md2blog
python3 upload_cnblog.py -r REPO_DIR

cp demo/cnblog.json .cnblog.json
# 修改 .cnblog.json 文件，具体配置内容见："配置文件 .cnblog.json 的说明"
vi .cnblog.json

# 编辑markdown
cd REPO_DIR
vi test.md

# 方式1: 手动上传
python3 upload_cnblog
在此拖入md文档，回车上传~

# 方式2: 使用自动上传功能
git add test.md
python3 upload_cnblog.py -a
根据需要，手动push你的Git仓库

上传方式推荐2，可以将内容commit提交到git。另，这个方式会自动将文件记录到数据库（json）中，便于修改、移动、删除文档时追踪文件。

5.1. 配置文件 .cnblog.json 的说明

  • blog_url: "https://rpc.cnblogs.com/metaweblog/brt2"
  • blog_id: "anything" # cnblog并不验证此项目，尽管你能够获得你的ID
  • app_key: "brt2",
  • user_id: "2039866", # 此项用于下载图像链接时，忽略自己博客的图像地址
  • username: "brt2",
  • password: "this is a secret",
  • repo_dir: "D:\Home\workspace\note" # 指向你的Git-Repo

关于 user_id ，特别说明下：并没有明确的接口可以获取到该ID，它不同于blog_id。本人获取这个的方法是，上传一张图像后，查询其生成的URL地址，从中提取，例如： https://img2020.cnblogs.com/blog/2039866/202006/2039866-20200602142016960-1926272797.jpg 中可以提取到我的user_id: 2039866

6. Markdown编辑工具推荐

基于vscode

  • Markdown Shortcuts: 支持各种md格式化，最牛的就是自动生成表格的功能
  • Markdown TOC
  • Markdown AutoTOC
  • markdown-helper
  • Paste Image
  • Markdown Preview Enhanced（其实vscode默认md预览就很棒了）
  • Open In Default Browser（这个就很鸡肋了，还不如vscode自带预览功能）

基于sublime

  • Markdown Editing
  • Markdown Preview: 只能在浏览器中预览
  • imagepaste: 这个强烈推荐，可以直接粘贴剪切板图片，并存储在同名目录下。
    • 标准的插件，有个瑕疵： 只能存储为png图像，图像体积较大
    • 不支持Linux系统（个人测试未实现功能）
    • 推荐个人修改版本，默认存储jpg格式，且支持Linux: https://gitee.com/brt2/subl_imgpaste2
  • SublimeTmpl: 用于生成各类文件的模板，包括Markdown
  • 还有sublime自定义快捷键的功能，可以快速实现对H2/H3...等常见结构的格式化

基于Simpread（简阅）

  • 安利一下这款国人开源工具，工具后台已经对上百个常见网站做了适配，可以直接将html页面转码Markdown下载。
  • 当然，下载的格式毕竟还是有必要人工修整一下的，但已经节约了90%的时间了，知足吧
  • 本工具会自动再上传时标记【转载】字样，同时建议用户保留 本文由 简悦 SimpRead 转码， 原文地址... 的内容。

7. 关于Markdown的格式（模板）

<!--
+++
title       = "This is title to show!"
description = ""
date        = "2020-06-01"
weight      = 5
tags        = ["我的标签"]
categories  = ["我的分类", "我的另一个分类"]
keywords    = []
+++ -->

[TOC]

## 8. This is a heading

Body text...

* item_0
* item_1
    - item_1_1
    - item_1_2
* item_3

## 9. This is another heading

Body text...

10. 功能列表

  • 压缩图像（依赖pngquant，python3-pngquant）

    python3 main.py -s

    然后拖拽需要压缩的图像到命令行窗口即可（支持多选）。

  • 下载html，并自动转换为Markdown

    python3 main.py -d

  • 下载博客中链接的http图像为本地图片，并更新markdown图像引用地址

    python3 main.py -p

11. Todo List

12. Buglist

  • 通过上传md时，在post_struct["categories"]增加"[文章分类]"，无法解决上传作为“文章”类型的问题。暂时没有方式可以实现该需求。
  • 目前cnblog不支持webp的动图格式，但测试webp比gif压缩率更高；所以建议手动转换webp -> gif，上传cnblog后，源文档 <!-- 注释 xxx.webp --> 保留并git存储webp原图和gif转换图。
  • html2text使用空格缩进来处理 <code> ，容易实现但无法体现代码语言类型，需要改成反引号的格式。

13. 寻求帮助

欢迎各界高手施以援手，答疑解惑~

posted @ 2021-02-06 17:02  brt2  阅读(445)  评论(0)  编辑  收藏  举报