/mdtool

Primary LanguageJavaScriptMIT LicenseMIT

简介

mdtool 是个人使用的一套 hugo 环境 (docker 封装),用于将内容 (markdown) 转换为不同平台的页面:

  • 个人博客
  • 微信公众号
  • ...

这里使用 pandoc 作为处理引擎而非 hugo 默认使用的 Goldmark, 这是因为 pandoc 有更丰富的 markdown 扩展, 以及其可定制的 filter 机制. 不过代价就是生成页面的速度慢了许多.

快速使用

安装:安装好 docker, 将 mdtool (bash script) 放置在 PATH 即可. 用法基本跟 hugo 一致

新建内容

$ mdtool new posts/third.md
$ tree
.
├── config
│   └── _default
│       └── config.toml
└── content
    └── posts
        ├── third.md
        ├── second.md
        └── first.md

写作

$ mdtool serve -D
Start building sites …
hugo v0.86.0-41C6C52E+extended linux/amd64 BuildDate=2021-07-21T09:53:14Z VendorInfo=gohugoio

                   | EN
-------------------+-----
  Pages            | 15
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  0
  Processed images |  0
  Aliases          |  0
  Sitemaps         |  1
  Cleaned          |  0

...

生成最终页面

$ mdtool

工作原理

mdtool 运行时会检查当前目录是否有 content 子目录,如果没有则会提示初始化当前目录: 新建 config/content/public/resources 目录;

然后会 docker run 启动 hugo,并将上述目录 bind mount 到容器 site 相对应的目录下.

tool (工具目录)

site (hugo 站点目录)

默认不使用 theme, 用于输出博客页面, 可以通过命令行参数 -t 修改:

  • -t theme-with-weixin-mp: 添加拷贝到微信公众号的功能

内容处理

  • 表格:会包裹在 .table-container 中以供超长时滑动
  • 代码:inline code 和 code block 会经由 highlightjs 进行语法高亮,如:
    `x=lambda:None`{.python}
    
    ```python
    x=lambda:None
    ```  
  • 数学:inline math 和 display math 会经由 mathjax 进行排版,如:
    质能方程 $E=mc^2$
    
    $$
    E=mc^2
    $$
  • 图片:如果图片是 svg 且后缀为 .embed.svg,则会将 svg 直接注入到 html 中以便 css 起效,如:
    ![XXX](xxx.embed.svg)
    
  • div.proof:对带有 proof class 的 div 添加一个 label,按之能 collapse/expand 证明
  • 微信公众号输出会做如下处理
    • mathjax 的 fontCache 会设为 none,否则 svg 中会有 id 属性,而 id 属性是会被过滤掉的
    • <div class="table-container"> 元素会转换为 <table-container> 元素,因为貌似会过滤 <div>
    • <a> 元素会转换为 <a-link> 元素,因为貌似会过滤 <a>
    • 所有 img 会转换为 Data URL
    • css 会全部 inline 到元素中

Theme

[params]
  # 目前唯一一个 theme
  siteTheme = 'gruvbox-soft'

Giscus

前提

由于 giscus 是在第三方域名的 iframe 里呈现的,而 custom theme css 是由 host 提供的, 故 host server 需要返回 Access-Control-Allow-Origin: * 以允许第三方域名的页面获取 host 的 css

例如本地跑的 hugo server 有以下配置

[server]
[[server.headers]]
  for = '/**'
  [server.headers.values]
    Access-Control-Allow-Origin = '*'

而幸运的是 Github Pages 的 server 也会返回这个 Response 头部

配置

# giscus 评论系统设置
[params.giscus]
  enable = false
  # 用 https://giscus.app/ 获得以下参数
  repo = ''
  repoId = ''
  category = ''
  categoryId = ''
  mapping = 'pathname'
  strict = '0'
  reactionsEnabled = '1'
  inputPosition = 'top'

https://giscus.app/ 提供评论功能,如需要开启,则设置 enable = true 并填入 repo/repoId/category/categoryId 等参数

如果一个单独页面不想要开启评论,可添加

disableGiscus: true

参考