背景
工作、生活中有很多写文档的需求,如何才能提高写作效率?选择合适的工具加恰当的方法。下面分享一些工具和方法,为你的写作助力。
写作工具
对于我来说MarkDown+思维导图是一种效率极佳的写作方式。思维导图可以将我的思考清晰的展示,然后按照知识脉络完善文章内容。文章写作使用MarkDown ,MarkDown 编辑工具很多,经过使用比较我最终选择 Typora + MindNode 。
Typora 正式版本已经开始付费,89元买断机制,免费版可以下载历史Beta版本。
文档格式互转
有的时候,我们需要做文件的各种转换以满足展示场景,比如 Markdown转思维导图。
Mind to Markdown
思维导图转换为 Markdown ,MindNode 和 XMind 这两个工具直接导出 Markdown格式文件即可。
Markdown to Mind
使用 markmap 可以将 Markdown 转换为可视化、可交互的 HTML 格式的思维导图。
本文转换出来的效果如下
方式一:在线转换(https://markmap.js.org/repl)粘贴 markdown 到编辑区就可以导出Html或SVG。
方式二:在 vscode 中使用,安装插件(https://marketplace.visualstu...)
方式三:安装 markmap-cli 命令工具。
npm install -g markmap-cli
# 转换
markmap index.md -o index.html
万能转换
一个强大的命令行工具 Pandoc,用于将文件从一种标记语言转换为另一种标记语言。常用的标记语言包括 Markdown、ReStructuredText、HTML、LaTex、ePub 和 Microsoft Word DOCX。
在线转换地址(https://pandoc.org/try)。
Mac上直接使用 brew 安装
brew install pandoc
支持格式如下:
Input formats: native, json, markdown, markdown+lhs, rst, rst+lhs, docbook,
textile, html, latex, latex+lhs
Output formats: native, json, html, html5, html+lhs, html5+lhs, s5, slidy,
slideous, dzslides, docbook, opendocument, latex, latex+lhs,
beamer, beamer+lhs, context, texinfo, man, markdown,
markdown+lhs, plain, rst, rst+lhs, mediawiki, textile, rtf, org,
asciidoc, odt, docx, epub
Markdown 转 Html
pandoc index.md -o index.html -c Github.css
Markdown 转 Word
pandoc index.md -o index.docx -c Github.css
Markdown 转 PDF,PDF 转换相对复杂一些。转换分两步骤,所以需要先安装TeX Live 或者 MiKTeX 。
- 第一步, Markdown 文件被转为 LaTeX 源文件。
- 第二步,调用系统的
pdflatex
(默认使用),xelatex
或者其他 TeX 命令,将.tex
文件转换为最终的 PDF 文件。
brew install texlive
pandoc index.md -o index.pdf
如果内容包含中文会出现如下报错,这是因为 Pandoc 默认使用的 pdflatex
命令无法处理 Unicode 字符,我们需要使用 xelatex
,并通过 CJKmainfont
指定中文字体。可以通过 fc-list :lang=zh
命令查询支持的中文字体。
Error producing PDF.
! LaTeX Error: Unicode character 大 (U+5927)
not set up for use with LaTeX.
Macos 下面我们选择 PingFang SC。
pandoc --pdf-engine=xelatex -V CJKmainfont="PingFang SC" index.md -o index.pdf
如果内容需要对图表,方程式,表格和交叉引用进行编号,可以安装 pandoc-crossref。安装和语法如下:
brew install pandoc-crossref
{#fig:label}
: 图片![img](img.png){#fig:key_img}
标记图片引用Key,然后在需要引用的位置加上[@fig: key_img]
。{#eq:label}
: 公式$$ math $${#eq:math}
{#sec:label}
: 章节{#tbl:label}
: 表格
# 转换 PDF
pandoc -F pandoc-crossref --pdf-engine=xelatex -V CJKmainfont="PingFang SC" index.md -o index.pdf
# 转换 Html
pandoc -F pandoc-crossref index.md -o index.html
Pandoc 还支持 YAML 格式的 header,通过 header 可以指定文章的标题,作者,更新时间等信息,如下:
---
title: "文章标题"
author: "lixp"
date: 2022-06-11
---
代码块高亮
# 代码块高亮
pandoc --list-highlight-styles
# 显示支持的语言
pandoc --list-highlight-languages
要使用语法高亮,Markdown 文件中的 block code 必须指定语言,同时在命令行使用--highlight-style
选项,例如:
pandoc -F pandoc-crossref --pdf-engine=xelatex -V CJKmainfont="PingFang SC" index.md --highlight-style espresso -o index.pdf
各种画图
写文档时,画图对于大多数人来说都比较痛苦吧。我们可以利用Mermaid 帮我们快速制作出想要的各种图等。它是一个基于 Javascript 的图表绘制工具,通过解析类 Markdown 的文本语法来实现图表的创建和动态修改。在线尝试一下。下面介绍一下 Markdown 里面画各种图。
Mermaid详细语法可查看:https://mermaid-js.github.io/...
流程图
横向流程图
```mermaid
graph LR
A[开始] -->B(审批)
B --> C{年龄?}
C -->|年龄>=18| D[通过]
C -->|年龄<18| E[拒绝]
```
graph LR
A[开始] -->B(审批)
B --> C{年龄?}
C -->|年龄>=18| D[通过]
C -->|年龄<18| E[拒绝]
竖向流程图
```mermaid
graph TD
A[开始] -->B(审批)
B --> C{年龄?}
C -->|年龄>=18| D[通过]
C -->|年龄<18| E[拒绝]
```
graph TD
A[开始] -->B(审批)
B --> C{年龄?}
C -->|年龄>=18| D[通过]
C -->|年龄<18| E[拒绝]
标准横向流程图
```flow
st=>start: 开始
op=>operation: 审批
cond=>condition: 年龄是否大于18
sub1=>subroutine: 返回审批
io=>inputoutput: 通过
e=>end: 结束
st(right)->op(right)->cond
cond(yes)->io(bottom)->e
cond(no)->sub1(right)->op
```
标准竖向流程图
```flow
st=>start: 开始框
op=>operation: 处理框
cond=>condition: 判断框(是或否?)
sub1=>subroutine: 子流程
io=>inputoutput: 输入输出框
e=>end: 通过
st->op->cond
cond(yes)->io->e
cond(no)->sub1(right)->op
```
时序图
```sequence
对象A->对象B: 对象B你好吗?(请求)
Note right of 对象B: 对象B的描述
Note left of 对象A: 对象A的描述(提示)
对象B-->对象A: 我很好(响应)
对象A->对象B: 你真的好吗?
```
复杂时序图
```sequence
Title: 标题:复杂使用
对象A->对象B: 对象B你好吗?(请求)
Note right of 对象B: 对象B的描述
Note left of 对象A: 对象A的描述(提示)
对象B-->对象A: 我很好(响应)
对象B->小三: 你好吗
小三-->>对象A: 对象B找我了
对象A->对象B: 你真的好吗?
Note over 小三,对象B: 我们是朋友
participant C
Note right of C: 没人陪我玩
```
UML标准时序图:
```mermaid
%% 时序图例子,-> 直线,-->虚线,->>实线箭头
sequenceDiagram
participant 张三
participant 李四
张三->王五: 王五你好吗?
loop 健康检查
王五->王五: 与疾病战斗
end
Note right of 王五: 合理 食物
看医生...
李四-->>张三: 很好!
王五->李四: 你怎么样?
李四-->王五: 很好!
```
%% 时序图例子,-> 直线,-->虚线,->>实线箭头
sequenceDiagram
participant 张三
participant 李四
张三->王五: 王五你好吗?
loop 健康检查
王五->王五: 与疾病战斗
end
Note right of 王五: 合理 食物
看医生...
李四-->>张三: 很好!
王五->李四: 你怎么样?
李四-->王五: 很好!
甘特图
```mermaid
%% 语法示例
gantt
dateFormat YYYY-MM-DD
title 软件开发甘特图
section 设计
需求 :done, des1, 2022-01-06,2014-01-08
原型 :active, des2, 2022-01-09, 3d
UI设计 : des3, after des2, 5d
未来任务 : des4, after des3, 5d
section 开发
学习准备理解需求 :crit, done, 2022-01-06,24h
设计框架 :crit, done, after des2, 2d
开发 :crit, active, 3d
未来任务 :crit, 5d
耍 :2d
section 测试
功能测试 :active, a1, after des3, 3d
压力测试 :after a1 , 20h
测试报告 : 48h
```
gantt
dateFormat YYYY-MM-DD
title 软件开发甘特图
section 设计
需求 :done, des1, 2022-01-06,2014-01-08
原型 :active, des2, 2022-01-09, 3d
UI设计 : des3, after des2, 5d
未来任务 : des4, after des3, 5d
section 开发
学习准备理解需求 :crit, done, 2022-01-06,24h
设计框架 :crit, done, after des2, 2d
开发 :crit, active, 3d
未来任务 :crit, 5d
耍 :2d
section 测试
功能测试 :active, a1, after des3, 3d
压力测试 :after a1 , 20h
测试报告 : 48h
类图
```mermaid
classDiagram
class Account
Account : +String owner
Account <|-- BankAccount
class BankAccount
BankAccount : +String owner
BankAccount : +Bigdecimal balance
BankAccount : +deposit(amount)
BankAccount : +withdrawl(amount)
```
classDiagram
class Account
Account : +String owner
Account <|-- BankAccount
class BankAccount
BankAccount : +String owner
BankAccount : +Bigdecimal balance
BankAccount : +deposit(amount)
BankAccount : +withdrawl(amount)
状态图
```mermaid
stateDiagram-v2
[*] --> First
state First {
[*] --> second
second --> [*]
}
```
stateDiagram-v2
[*] --> First
state First {
[*] --> second
second --> [*]
}
并图
```mermaid
pie
"苹果" : 386
"香蕉" : 85
"菠萝" : 15
```
pie
"苹果" : 386
"香蕉" : 85
"菠萝" : 15
用户体验旅程图
```mermaid
journey
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 3: Me
```
journey
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 3: Me
Goat Ascii 图
Goat 可以将 ASCII 渲染成 SVG
```goat
+-------------------+ ^ .---.
| A Box |__.--.__ __.--> | .-. | |
| | '--' v | * |<--- | |
+-------------------+ '-' | |
Round *---(-. |
.-----------------. .-------. .----------. .-------. | | |
| Mixed Rounded | | | / Diagonals \ | | | | | |
| & Square Corners | '--. .--' / \ |---+---| '-)-' .--------.
'--+------------+-' .--. | '-------+--------' | | | | / Search /
| | | | '---. | '-------' | '-+------'
|<---------->| | | | v Interior | ^
' <---' '----' .-----------. ---. .--- v |
.------------------. Diag line | .-------. +---. \ / . |
| if (a > b) +---. .--->| | | | | Curved line \ / / \ |
| obj->fcn() | \ / | '-------' |<--' + / \ |
'------------------' '--' '--+--------' .--. .--. | .-. +Done?+-'
.---+-----. | ^ |\ | | /| .--+ | | \ /
| | | Join \|/ | | Curved | \| |/ | | \ | \ /
| | +----> o --o-- '-' Vertical '--' '--' '-- '--' + .---.
<--+---+-----' | /|\ | | 3 |
v not:line 'quotes' .-' '---'
.-. .---+--------. / A || B *bold* | ^
| | | Not a dot | <---+---<-- A dash--is not a line v |
'-' '---------+--' / Nor/is this. ---
```
让Hugo支持图表显示
我个人博客是使用 Hugo 创建,所以需要让它支持图表显示。
支持 mermaid
创建 layouts/_default/_markup/render-codeblock-mermaid.html
文件并添加下面代码:
{{- .Inner | safeHTML }}
{{ .Page.Store.Set "hasMermaid" true }}
然后在内容模板的底部(在 .Content 下方)添加下面代码:
{{ if .Page.Store.Get "hasMermaid" }}
{{ end }}
自定义Goat
通过(https://arthursonzogni.com/Di...)这个网站可以快速生成ASCII值。然后通过hugo渲染,下面是几个例子
展示项目目录,安装 tree
,将ASCII粘贴进来即可,非常方便
brew install tree
如果上述画图不能满足,也可以使用图说在线制表,然后导出图片。