Giters

huangjunwen / mdtool

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

简介

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

参考

About

License:MIT License

Languages

Language:JavaScript 82.9%Language:SCSS 11.7%Language:HTML 4.3%Language:Lua 0.4%Language:Shell 0.4%Language:Dockerfile 0.3%