写给 Steemit #CN 区的 Markdown 指南

in #cn7 years ago (edited)

目前 Steemit #CN 区关于 Markdown 的指南并不少,但是其中大多似乎介绍并不详细。加之 Steemit、Busy 等网站前端本身对于文字排印的处理十分糟糕,导致 #CN 用户中出现了一些十分糟糕的使用习惯,甚至一些介绍 Markdown 的文章本身就有着并不好的排版。

Markdown 的一个轻量级的标记语言,同 HTML 一样传达的是文本的结构信息,而本身并不负责文本渲染。一篇正确遵从 Markdown 语法的文章理应条理清晰,原文本直接通过纯文本编辑器打开也可轻松阅读。Markdown 的语法大多可以对应转换为 HTML,而最终的输出样式应由 CSS 样式表或其他渲染规则控制。

通俗地说,Markdown 和 HTML 一样仅负责文章的整体骨架,具体的外表如何呈现是 Steemit、Busy 这些前端网站的选择。

此外与 HTML 不同的是,Markdown 的设计目的是可读性。基于这些原因,Markdown 提供了相当简单的语法规则和比较有限的文本格式,让创作者在写作时免于被 Word 或者 LaTeX 一类复杂而难以操控的排版系统所干扰。还记得自己面对 Word 等富文本编辑器时对文本样式的各种调节和失控吗?推广 Markdown 正是为了解决这种问题。

如果看到这里还不明白为什么要使用 Markdown 语法而非富文本,我建议你看看不鳥萬先生的文章《为什么作家应该用 Markdown 保存自己的文稿》


本文另有一篇同系列文章,你也可以牵强理解为本文的太长不看版本


块元素

块元素是一片文章的基本构成单位,其中最常见的就是段落。

段落

你在文本框中输入的每一段字都是一个段落,一篇文章理应由多个段落构成。在 Markdown 语法中,段与段间应空出一行以示间隔,就像这样:

注意段落与换行

作者应该注意:段落是段落,换行是换行,这是两种不同的概念。就像在 MS Word 中,Enter 用于建立一个新段落,而 Shift + Enter 则是换行。在 Markdown 源码中,段与段间应空出一行作为段落间隔,而换行应在前一行行末添加两个空格(即使我发现如今很多编辑器不加两个空格直接换行也算有效换行了):

(当然我建议你在严肃写作的时候少用换行。)

标题

标题是最常见的格式,常见的是 HTML 中从 <h1><h6> 六个等级标题。在 Markdown 中,在行首添加对应数量的 # 即可实现 HTML 中对应的六种等级的标题,例如:

此外需要注意

  • 标题等级的选用应依据文章结构,而非标题最后呈现的样式。

    Markdown 仅负责文本结构,一般情况下所有样式问题在技术上都应该而且可以通过 CSS 样式表解决;不过如果你在 Steemit 这样所用渲染规则垃圾且用户不可修改的场景,为了输出效果可以作适当的调整,但这应该以不影响文章结构布局为前提

    (例如 Steemit 网站中的 <h2><h3><h4> 标题显示差别并不明显,所以本文为了突出显示标题之间的层级关系,跳过了 <h3><h5> 标题而仅使用了 <h2><h4><h6> 标题。)

  • 在对应数量的 # 与标题内容之间应添加空格以避免部分网站无法渲染。

代码块

代码块意指本段落内容为代码,一来防止代码内语法被 Markdown 误渲染,二来网站和浏览器可以将该段落代码以更适合代码阅读的样式输出(例如等宽字体、语法高亮等)。

代码块的语法有两种:对于单行代码,可以直接使用段首空四格的方法表示;对于多行代码,在代码块前后分别用 ```包裹。使用方法与效果如下:

从下文开始,除非因 Steemit 显示效果限制等情况下使用截图说明,本文将优先使用这样的代码块来展示 Markdown 源码的语法。

引用

引用语法对应 HTML 中的 <blockquote> 标签,用于引用他人言论。(偶尔也可当作特殊段落作用挪用。)在作为引用的每个段落首添加 > 即可将这些段落作为引用,例如:

> 这里到处是充满生活气息的俗味中年人、长着中年内核的无聊年轻人,还有卖脸的小姐姐。

效果为:

这里到处是充满生活气息的俗味中年人、长着中年内核的无聊年轻人,还有卖脸的小姐姐。

你也可以在引用块中嵌套其他绝大部分的 Markdown 语法:

菜馆的老板报上了各种不同的辣鸡:

  • 大辣鸡
  • 小辣鸡
  • 老辣鸡

这一段根本就是垃圾话嘛。

这一段的源码是:

> 菜馆的老板报上了各种不同的辣鸡:
>
> > - 大辣鸡
> > - 小辣鸡
> > - 老辣鸡
>
> 这一段根本就是[垃圾话](https://zh.moegirl.org/zh-hans/%E5%9E%83%E5%9C%BE%E8%AF%9D)嘛。

列表

列表分为有序列表和无序列表。

有序列表

有序列表按照以下格式编写,注意编号与条目间存在一个空格:

1. 老辣鸡
2. 大辣鸡
3. 小辣鸡

显示为:

  1. 老辣鸡
  2. 大辣鸡
  3. 小辣鸡
无序列表

无序列表与有序列表语法相似,使用 *-+ 等符号代替编号即可,如果有需要你还可以通过空格缩进来实现多个层级的无序列表:

- 老辣鸡
  - 微辣老辣鸡
- 大辣鸡
  - 特辣大辣鸡
    - 特辣大辣鸡鸡心
- 小辣鸡

效果为:

  • 老辣鸡
    • 微辣老辣鸡
  • 大辣鸡
    • 特辣大辣鸡
      • 特辣大辣鸡鸡心
  • 小辣鸡

表格

表格是 Markdown 基础语法中较难的一环,在此直接使用截图意会:

分割线

分割线大概就是 Markdown 语法里最简单的那个了,在 -_*中任选一个,连敲三个:

---

这样就完成了一条简单的分割线:


图片

在 Markdown 中,你可以通过 ![图片说明](图片 URL) 这样的语法来插入图片,例如:

![柱柱姐教你学历史](http://momok.link/3sFZ+)

显示为:

柱柱姐教你学历史

插入图片是每个 Markdown 教程都一定会提及的功能,但我在此想要强调的是:尽管 Markdown 语法并没有不支持在行内插入图片,但我建议你为了文章的排印美观,在一般情况下将图片作为单独一段单列,毕竟除非你的图片与字体行高近似,否则我很难想到有什么插在行内可以好看的可能性。

居中显示

Steemit 并没有在 CSS 中设置将图片居中显示,鉴于 Markdown 中并没有设置对齐的语法。你可以通过插入 HTML 标签 <center> 来让图片等元素居中显示

再重申一遍,这不是 Markdown 的标准做法,而是出于用户无法自行调整 Steemit 网站 CSS 内容的无奈之举。


行内样式

这个表格说明了 Markdown 中常用的几个行内文字样式:

样式语法效果
斜体*斜体文本*_斜体文本_斜体文本
粗体**粗体文本**__粗体文本__粗体文本
删除~~删除文本~~删除文本

不过我建议你慎用斜体,目前在中文中并没有原生的斜体字体,所有的斜体均是将正常字体强制倾斜,除非你有腾讯那样的财力找专人设计一套中文斜体字体

链接

在 Markdown 中,你可以通过 [文字](URL) 的语法来插入链接。例如 [《老娘想死》](https://www.youtube.com/watch?v=QL3T2Nzcqcs) 就是《老娘想死》

行内代码

行内代码是什么?标红的就是了:

它和代码块的作用一样,甚至语法都相似(代码块用 ``` 包裹,而行内代码只需要一个 ` 包裹就可以),你可以用来标记类似于程序变量名、编程语法、文件名一类的内容。


后话

其实 Markdown 这个语言在一些细节上并无统一标准,一来各种渲染实现的规则逻辑未必相同(尤其是在面对语法套语法之类的复杂情况时,这也是我在文章内不少地方使用截图说明的原因),二来 Markdown 存着在各种乱七八糟的方言版本(大多数是对 Markdown 的基本语法进行了功能拓展)。

到这里为止,我已经尽力介绍大多数常用的 Markdown 基本语法。这篇文章的写成离不开《Markdown 语法说明》,相比这篇详细的《语法说明》,我的「二手指南」可能只是无用功。(如果你有更多的 Markdown 疑惑无法被本文解决,我强烈推荐你阅读这一篇说明。)但我希望这篇指南能够改变目前 Steem 中文社区内对 Markdown 介绍贫瘠的现状,但愿这篇无用功可以对这个社区做出一点改变吧。

Sort:  

@momok, steemit上我觉得只需要静静读你的贴就值了~~~ img

写得很详细,值得多看几遍,谢谢分享,收藏了

@momok, 这个不错,赞了!

情人节貌似快到了,@cn-cutie.pie 可可 我们去哪里浪漫一下?

一般用用,你这篇就足够了,更深更复杂的才需要查手册。

你这个文章早该写了!

嗨喽,我是@dapeng《steem指南》校正组的@meixia,我现在已经校正了15章的前言,有空加我微信:zMxI0225,方便我们沟通交流~

收藏了,学会了好多用法

写完了尽快上传github哦,这样大家才可以方便快捷的浏览你的文章,同时更好的了解整个项目的进度哦!

就算还没写完也可以上传哦,这样大家能更好的了解你的进度哦!

如果上传有什么困难,欢迎咨询我或者群里的朋友哦!