Unlock advanced usage of Markdown and improve writing efficiency

background

There are many needs of writing documents in work and life, how can we improve the writing efficiency? Choose the right tool and the right method . Here are some tools and methods to help you with your writing.

writing tool

For me MarkDown + mind mapping is a very efficient way of writing. Mind maps can clearly show my thinking, and then improve the content of the article according to the knowledge context. Article writing uses MarkDown . There are many MarkDown editing tools . After using and comparing, I finally choose Typora + MindNode .

The official version of Typora has begun to pay, with an 89 yuan buyout mechanism, and the free version can download the historical Beta version .

document format conversion

Sometimes, we need to do various conversions of files to meet the display scene, such as Markdown to mind map.

Mind to Markdown

The mind map is converted to Markdown, and the two tools MindNode and XMind can directly export the Markdown format file.

Markdown to Mind

Use markmap to convert Markdown into a visual, interactive HTML formatted mind map.

The effect of this conversion is as follows

Method 1: Online conversion ( https://markmap.js.org/repl ) Paste markdown into the editing area to export Html or SVG.

Method 2: Use in vscode, install the plugin ( https://marketplace.visualstudio.com/items?itemName=gera2ld.markmap-vscode )

Method 3: Install the markmap-cli command tool.

 npm install -g markmap-cli
# 转换
markmap index.md -o index.html

Universal conversion

A powerful command-line tool, Pandoc , for converting files from one markup language to another. Common markup languages include Markdown, ReStructuredText, HTML, LaTex, ePub, and Microsoft Word DOCX.

Convert addresses online ( https://pandoc.org/try ).

Install directly with brew on Mac

 brew install pandoc

The supported formats are as follows:

 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 to Html

 pandoc index.md -o index.html -c Github.css

Markdown to Word

 pandoc index.md -o index.docx -c Github.css

Markdown to PDF , PDF conversion is relatively complicated. The conversion is a two-step process, so you need to install TeX Live or MiKTeX first.

• In the first step, the Markdown file is converted to a LaTeX source file.
• The second step is to call the system pdflatex (used by default), xelatex or other TeX commands to convert the .tex file into the final PDF file.

 brew install texlive
pandoc index.md -o index.pdf

If the content contains Chinese, the following error will appear. This is because Pandoc uses the pdflatex command by default and cannot handle Unicode characters. We need to use xelatex and specify it by CJKmainfont Chinese font. You can query the supported Chinese fonts through the fc-list :lang=zh command.

 Error producing PDF.
! LaTeX Error: Unicode character 大 (U+5927)
               not set up for use with LaTeX.

Macos Below we choose PingFang SC.

 pandoc --pdf-engine=xelatex -V CJKmainfont="PingFang SC" index.md -o index.pdf

If the content requires numbering of diagrams, equations, tables and cross-references, you can install pandoc-crossref . The installation and syntax are as follows:

 brew install pandoc-crossref

• {#fig:label} : Picture ![img](img.png){#fig:key_img} mark the picture reference Key, and then add [@fig: key_img] to the position that needs to be referenced.
• {#eq:label} : formula $$ math $${#eq:math}
• {#sec:label} : Chapter
• {#tbl:label} : table

 # 转换 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 also supports headers in YAML format , through which you can specify the title, author, update time and other information of the article, as follows:

 ---
title: "文章标题"
author: "lixp"
date: 2022-06-11
---

code block highlighting

 # 代码块高亮
pandoc --list-highlight-styles
# 显示支持的语言
pandoc --list-highlight-languages

To use syntax highlighting, the block code in the Markdown file must specify the language and use the --highlight-style option on the command line, for example:

 pandoc -F pandoc-crossref --pdf-engine=xelatex -V CJKmainfont="PingFang SC" index.md --highlight-style espresso -o index.pdf

various drawings

When writing documents, drawing pictures is a pain for most people. We can use Mermaid to help us quickly make all kinds of pictures we want. It is a Javascript-based chart drawing tool, which realizes the creation and dynamic modification of charts by parsing Markdown-like text syntax. Try it online . Let's introduce the various diagrams in Markdown.

The detailed syntax of Mermaid can be viewed: https://mermaid-js.github.io/mermaid

flow chart

Horizontal flow chart

 ```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[拒绝]

Vertical flow chart

 ```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[拒绝]

Standard Horizontal Flowchart

 ```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
```

Standard vertical flow chart

 ```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
```

Timing diagram

 ```sequence
对象A->对象B: 对象B你好吗?（请求）
Note right of 对象B: 对象B的描述
Note left of 对象A: 对象A的描述(提示)
对象B-->对象A: 我很好(响应)
对象A->对象B: 你真的好吗？
```

complex timing diagram

 ```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 standard timing diagram:

 ```mermaid
%% 时序图例子,-> 直线，-->虚线，->>实线箭头
  sequenceDiagram
    participant 张三
    participant 李四
    张三->王五: 王五你好吗？
    loop 健康检查
        王五->王五: 与疾病战斗
    end
    Note right of 王五: 合理 食物 <br/>看医生...
    李四-->>张三: 很好!
    王五->李四: 你怎么样?
    李四-->王五: 很好!
```

 %% 时序图例子,-> 直线，-->虚线，->>实线箭头
  sequenceDiagram
    participant 张三
    participant 李四
    张三->王五: 王五你好吗？
    loop 健康检查
        王五->王五: 与疾病战斗
    end
    Note right of 王五: 合理 食物 <br/>看医生...
    李四-->>张三: 很好!
    王五->李四: 你怎么样?
    李四-->王五: 很好!

Gantt chart

 ```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

Class Diagram

 ```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)

State diagram

 ```mermaid
stateDiagram-v2
    [*] --> First
    state First {
        [*] --> second
        second --> [*]
    }
```

 stateDiagram-v2
    [*] --> First
    state First {
        [*] --> second
        second --> [*]
    }

and map

 ```mermaid
pie
"苹果" : 386
"香蕉" : 85
"菠萝" : 15
```

 pie
"苹果" : 386
"香蕉" : 85
"菠萝" : 15

User Experience Journey Map

 ```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 Diagram

Goat can render ASCII to 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.            ---
 ```

Let Hugo support chart display

My personal blog is created with Hugo, so I need to make it support chart display.

support mermaid

Create layouts/_default/_markup/render-codeblock-mermaid.html file and add the following code:

 <div class="mermaid">
  {{- .Inner | safeHTML }}
</div>
{{ .Page.Store.Set "hasMermaid" true }}

Then add the following code at the bottom of the content template (below .Content):

 {{ if .Page.Store.Get "hasMermaid" }}
  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
  <script>
    mermaid.initialize({ startOnLoad: true });
  </script>
{{ end }}

Customize Goat

Through ( https://arthursonzogni.com/Diagon/ ) this website can quickly generate ASCII values. Then render through hugo, here are a few examples

flow chart

Edit interface

Display the project directory, install tree , just paste the ASCII in it, it is very convenient

 brew install tree

If the above drawing cannot be satisfied, you can also use the drawing description to make an online table, and then export the picture.