Markdown进阶使用与mermaid画图(Typora)

2015-08-29

tips

这篇文章写于几年前, 那时候md的编辑器其实寥寥无几, 而且绝大多数都是双侧渲染 . 或者在线也没, 本地化的支持和各种定制化需求以及图片/表格 . 各种高级用法的问题都没有解决方案. 随着我个人认为的markdown编辑器之王typora 的出现. 写作变得如此优雅, 这里主要记载着关于md & typora相关的技巧心得.

更新: 补充大量mermaid画简易图表的示例, 推荐大家使用. (基本成为md画图标准)

0x00.前言

文章几乎被完全重写了, 新的版本不会涉及md的最基础语法.(需要自查). 只会写一些typora 或者 hexo 中使用markdown的有价值的心得. (鲜有人提及的). 关于LaTex 和 word对比可能后续加入. (关于如何让你的blog支持mermaid, 可以参考我写的这篇0x03章节)

0x01.小众语法

进阶用法md其实也有不少, 这里列举的都是真正有意义, 比较常用的. 用的比较少的会简单带过.

A. 数学公式^[上角标]^

1
2
3

测试一下数学公式支持x^{y^z}=(1+{\rm e}^x)^{-2xy^w}  前后加上$显示为
$ x^{y^z}=(1+{\rm e}^x)^{-2xy^w} $   //现在里面为什么不支持呢
//下方为正常支持

$ x^{y^z}=(1+{\rm e}^x)^{-2xy^w} $
$E=mc^2 $

B.TODO List语法

这个比较特别, 是在列表语法基础上进行的添加而来. - [] 即可触发, 但是这有个问题, typora中输入- 后空格直接就解析为列表了, 只能再源码编辑模式下才能这样 (所以我下面先不加-了)

[ ] 支持word,pdf 导出
[ ] 新增 Todo 列表功能
[x] 修复 LaTex 公式渲染问题

0x02.图表绘制

首先要知道图表(diagram) 绘制并非原本md所支持的功能, typora也是通过flowchat.js或svg 或mermaid.js (非常强大的多种图形转换)提供的渲染转换. 导出建议优先选择PDF, 选word类格式也许会有些小问题.

注意: 支持高级图形是md的高级用法, 前端渲染的时候是否支持完全取决于是否实现了这个功能.

A. 绘制流程图

流程图(flow)是可能最常用的表达关系图之一. 因为最简单直观. code block备注flow即可有提示 (基于flowchat.js的流程图已过时, 内容已删)

现在只考虑使用mermaid 作为流程图语法, 并注意更新版本为最新, 避免有些语法不支持, 详细参考官方文档: (以后推荐使用mermaid统一画图)

开头声明graph XX 即代表开始流程图 (为了区分其他图形)
1. TD 代表自顶向下 ,纵向图(最常用)
2. LR 代表自左向右, 横向图
规则灵活,语法易读易懂. 最常用的A --msg--> B --> C (多层迭代需要高版本mermaid才支持)
subgraph xxx end 格式声明黄色框的子图表示, 也很好用.
需要注意的是, 尽量不要一个流程图过长, 展示的时候并不方便, 也不易于理解, 内容多尽量精简或者拆分

graph TD
 hack[CTF] ==> pwn
 hack -.whoami.-> web --> reflect_function
 hack --> reverse --> Android
 reverse --> C/ASM
 web --> sandbox_escape

 
 

 b[another] --无向边--- chart
 b .-> pwn
 
 subgraph 子图
 chart --> 自旋锁
 end

B.时序图

同样,也有两种写法. 一种是标准的code block 选择sequence (已弃用) .另一个是mermaid . 更新后只讲后者用法.

核心框基于A ->> B: msg 的语法 , 如果需要虚线就是 A -->> B:msg ,还是很好上手的
备注语法Note right/left of A: msg , 也挺简单. (<br/> 可以换行)
备注如果在中间, 可用note over A:msg, 如果需要在多个中间note over A,B.
单独的节点用participant A ,别名as, 比如你要写中文标注的时候, 就建议用个别名

mermaid 的语法基于传统的时序语法, 进行了改良和功能完善(支持的功能非常强大), 详细API可参考官方文档,写的很好. 支持:

启动停止标记 activate A , 或者合并为A->>+B : msg ,通过+/ 符号来启动
支持循环标识. loop msg + end . 效果挺不错

sequenceDiagram
    participant Alice as Jin
    participant Bob as Tom
    Alice->>Peter: Hi Peter, how are you?
    loop 循环标记loop
        Peter->Peter: 定时器检查
    end
    Note right of Peter: 提示语句: <br/> 然后br换行
    Peter-->>Alice: Great!
    Peter->>Bob: How about you?
    Bob-->>Peter: Pretty good!

C.甘特图(低频)

甘特图是用时间为X轴

这个目前typora只支持mermaid (美人鱼)转换下的渲染, 效果也很好.

gantt
        dateFormat  YYYY-MM-DD
        title 甘特图示例标题
        section 第一部分
        完成の任务            :done,    des1, 2018-08-06,2018-08-08
        正在进行               :active,  des2, 2018-08-09, 3d
        TODO 列表               :         des3, after des2, 5d
        展望列表               :         des4, after des3, 5d
        section 紧急任务
        在警戒线前 :crit, done, 2018-08-06,24h
        实现parser          :crit, done, after des1, 2d
        测试 parser             :crit, active, 3d
        紧急待定        :crit, 5d
        测试           :2d
        最终                      :1d

D. 状态图 (易用)

stateDiagram
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]

E. 饼图

pie title 宠物喜好
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15

X.思维导图(TODO)

后续``mermaid考虑实现的, 其实它现在还实验性的支持UML图 ,git flow图` ,不过我觉得用处很少, 且语法繁琐, 暂时不考虑使用.

更新: 由于mermaid 已经差不多一统六国. 所以之后也只考虑用mermaid的语法画图表, 不再推荐/介绍其他单独的语法. (通用性太差)

0x03.插入元素

因为md本身的局限性和设计原则, 一般是考虑尽量少的引入不必要的标记和元素,我觉得这没问题, 但是对于其他功能的需求, 也希望能够手动选择. 比如插入文档pdf, 音视频, iframe/gits等,参考

Typora现在可以支持常见的html/css混合的写法. 并且实时渲染. (赞~)

Raw Markdown Source	Output in Live Preview
`<span style='color:red'>This is red</span>`	This is red
`<ruby> 漢 <rt> ㄏㄢˋ </rt> </ruby>`	漢ㄏㄢˋ 漢ㄏㄢˋ
`<kbd>Ctrl</kbd>+<kbd>F9</kbd>`	Ctrl+F9
`<span style="font-size:2rem; background:yellow;">Bigger</span>`	Bigger
`HTML entities like ® ¶`	HTML entities like ® ¶

Ctrl+F9 是<kbd>的效果, 还算不错, 虽然平常无需特意使用.

注意:PDF插入支持截止18.8.20仅支持macOS

0x0n.待研究

除了mathjax通过mathjax.js可以实现支持, 其他md的高级用法如何**快速**在hexo主题中支持 ,其实也是非常关键的地方, 毕竟我们不可能都只在本地预览, 几个比较关键的兼容:

nodeppt (md做展示)
echarts (待定)

参考资料:

typora官方文档(强烈推荐)
mermaid官方文档
hexo主题支持高级md特性