实用但小众的 MarkDown 技巧

2018-03-23 发布
2055 字 • 6 分钟

汇总偏门但实用的 MarkDown 技巧:

注意:在 GitHub 网页查看可能看不出效果,建议把这个仓库 clone 到本地使用。且我会随手更新这个仓库的资源,建议 star 以便查找调取最新版。

内容编辑

MarkDown 编辑器有很多,推荐选择带目录栏、支持加载本地文件夹、可自行设定 CSS 渲染样式的。比如:

或者选择一些不错的全能编辑器,比如 Atom / TextMate 。总之挑 1-2 个你用得顺手的就好。

在线协同编辑

推荐 StackEdit – In-browser Markdown editor。其实你若不嫌弃,也可以直接在 Google docs 等支持在线协同编辑的平台,以 MarkDown 源码格式协同创作……

快速创建表格

表格建议直接在 Google sheet / Numbers 等表格工具中先建好,再用 Markdown Tables generator - TablesGenerator.com 一键转化为 MarkDown 格式 ,而非自己手动创建。

如果你的表格会持续更新,更建议你直接给出在线表格链接,这样你不必每次都更新 MarkDown 的表格,大伙儿也都能实时看到最新版。

如果你的表格是发布在支持 HTML 的页面,更优雅的方式是直接 embed :https://github.com/sunnylife42/docs/blob/v1/CONTENT/HbWorkingEfficiently.md#embed-something

优雅又省心地插入图片

技巧太多,另起一篇,详见 这样用七牛,插图优雅又省心 · MarkDown 码字发文最佳实践 | ishanshan's blog

换行


<br>

设置组块折叠

效果:

Why aren't routes I have for my static export accessible in the development server?

This is a known issue with the architecture of Next.js. Until a solution is built into the framework, take a look at this example solution to centralize your routing.

实现方式:

<details>
<summary> 这里是不想被折叠的文字</summary>

这里是被折叠的文字。

看不同平台,不一定能正常换行、使用 MarkDown 语法。
</details>

显示红绿对比的 diff

代码效果:

---
+++
@@ -7,7 +7,7 @@
 c = conn.cursor()

 for row in c.execute('SELECT * FROM weather_result'):
-     print(row)
+    print(row)

 # delete all records in the table
 c.execute('DELETE FROM weather_result')
@@ -19,8 +19,6 @@
 # search_weather.weather_query(city)
 # in_database = [(user_input, weather_condition, temperature)]
 # c.executemany('INSERT INTO weather_result VALUES(?,?,?)', in_database)
-
-

 # c.execute("INSERT INTO demo VALUES('2017-9-9', 198)")
 #

文字效果:


- 作品和作品的差别,源于卡片。人和人的差异,来自习惯。
+ 作品和作品的差别,源于卡片。人和人的差异,垒于习惯。一切皆时间的函数,时间最可怕的是复利效应。

- 怎么做?你看着办吧。
+ 怎么做?小女子我先干为敬,你看着办。

实现方法

```diff

- 减号后是原来的字符。
+ 加号后是改后的字符。

```

设置脚注

Example:

This is a footnote:[^sample_footnote]

Result:

This is a footnote:1

This is a footnote:2

(GitHub 渲染不支持,不过 Jekyll blog 支持,多数 MarkDown 编辑器也支持)

设置文内锚点

方法一:使用 bookmark 标记

效果:点击标记字段便可直接跳转到文中指定位置。

设置方法:

  1. 建立一个跳转的链接,标记方式为 [说明文字](#jump)

    说明文字(你点击一下看效果?)

  2. 标记要跳转到什么位置即可,标记方式为 <span id = "jump">跳转到这里:</span>

    跳转到这里:

方法二:借助 HTML 标记

HTML 中的 <a> 标签最重要的属性是 href ,它指示的链接目标,既可以是外部站点,也可以是页内锚点。页内锚点可以实现类似书签跳转的功能,最典型的就是点击 TOC 中的目录书签跳转到指定章节阅读。

构建页内锚点的语法,类似参考式链接:

  1. 先定义锚点id:<a href="#auchor_id">bookmark_text</a>
  2. 再定义一个id为auchor_id的对象(这里以<p>为例):<p id="auchor_id">auchor_text</p>

例如,在文末定义了id为end的 EOF(End Of File):<p id="end">The end!</p>,然后通过<a href="#end">Goto the End!</a>指定书签“Goto the End!”跳转到文末“The End!”处。

方法三:生成 TOC

若想建当前文档目录,对于只在本地使用的 MarkDown 文档,可直接另起一行插入 [TOC] ,多数编辑器都可以如此渲染出当前文档目录,如:

[TOC]

但多数网页的 CSS (比如 GitHub 、GitBook 、gist 等)并不支持此 MarkDown 标记。无妨,此时可借助这个小脚本 thlorenz/doctoc: Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites. 生成支持网页浏览的 MarkDown 目录;不过这种方式生成的目录在 MarkDown 编辑器里又不起作用了……你根据使用场景自行取用吧。

我一般都直接用后者,便于他人网页浏览。本地自己查看的话,就借助 MarkDown 编辑器 MWeb 自带的大纲视图,直接显示文档目录:

sampleissueassignmenthandup.png

把 HTML 样式的文本转译为 MarkDown 格式

复制你想转译的内容,粘贴到这个 MarkDown 编辑器 Typora — a minimal markdown reading & writing app 中。然后全选、右键选择 copy as MarkDown ,再粘贴到其它编辑器,bingo!

在网页上遇到想进一步编辑使用的内容,这招特省事儿。

展示

以幻灯的形式播放 MarkDown 文档

本地展示的话,可直接用 Marp - Markdown Presentation Writer ;在线展示可试试 Remark

更多相关平台,见 List of markdown presentation tools

把 MarkDown 文档发布到其它平台

MarkDown 格式的文章如何发布到只支持 HTML 样式的平台,比如邮箱、公众号、知乎专栏等?

两种方案:

  1. 直接粘贴 MarkDown 编辑器里渲染后的文本。
  2. 浏览器里安装 Markdown Here 插件,把 MarkDown 未渲染的内容粘贴过去后,一键渲染成指定样式。具体如何操作?可看 利用 Markdown here 排版微信公众号

注意:

这样用 MarkDown Here 发布到公众号的文章,图片需要 5-10 分钟才能正常在后台显示,因为微信后台还要将你的这些图片重新上传到微信的服务器,先压缩,再打水印,需要一些时间。等 10 分钟再回来预览看看吧~

把系列 MarkDown 文档发布为电子书

可直接用 GitBook 来处理,常用以下操作:

在正文中引入别处内容、获取该内容的实时更新(embed)

如果你想在正文中引入别处内容、获取该内容的实时更新,并展示得更丰富些,可以用 embed 的方式。

详见 https://github.com/sunnylife42/docs/blob/v1/CONTENT/HbWorkingEfficiently.md#embed-something

其它

更多技巧,比如如何用 MarkDown 写论文,可见 Markdown生态链整理 - 阳志平的网志

Footnotes

  1. footnote text detail...

  2. footnote text detail...

CHANGELOG

  • 200130 闪闪更新换行标记
  • 181216 闪闪更新 MarkDown 编辑器推荐
  • 180724 闪闪修改插图技巧链接
  • 180715 闪闪增补如何显示红绿对比的 diff
  • 180324 闪闪整理发布到外部仓库