GitHub（十）：掌握 Markdown

心已赠人 2022-03-26 10:43 347阅读 0赞

*大家可以将这一个文章的内容和CSDN 的 Markdown 编辑器 进行比较，说不定可以让你学得更好哦。*

# Mastering Markdown #

原文链接 -> [传送门][Link 1]

Markdown 是一种轻量级和便于使用的语法，GitHub 平台上所有写作的格式均采用 Markdown 语法。

**这一篇文章你将学到：**

*  Markdown 格式如何使得书写风格更容易协调
 *  Markdown 格式与传统格式化方法有何不同
 *  如何使用 Markdown 格式化文本
 *  如何利用 GitHub 的自动 Markdown 渲染
 *  如何应用 GitHub 独特的 Markdown 扩展

--------------------

## **什么是 Markdown？** ##

[Markdown][] 是一种在网页上设置文本样式的方法。你控制文档的显示；格式化单词为粗体或斜体，添加图像和创建列表，这些只是 Markdown 可以胜任的其中一部分工作而已。在通常情况下，Markdown 只是引入了一些非字母字符（例如 \# 或 \*）的常规文本而已。

在 GitHub 上的大多数地方，你都可以使用 Markdown：

*  [Gists][]
 *  Issues 的评论和 Pull Reqeusts
 *  带有 .md 或 .markdown 扩展名的文件

--------------------

## **例子** ##

### **一、文本** ###

**Markdown 语法：**

使用 Markdown 可以非常容易地为一些单词设置 **加粗** 而为另外一些单词设置 *倾斜*。你甚至可以 [超连接至谷歌！] (http://google.com)

**对应的显示格式：**

使用 Markdown 可以非常容易地为一些单词设置 **加粗** 而为另一些单词设置 *倾斜*。你甚至可以 [超链接至谷歌！][Link 2]

## **二、列表** ##

**Markdown 语法：**

有时候你可能需要带数字的列表：
    
    1. One
    2. Two
    3. Three
    
    有时候你可能需要带小圆点的列表：
    
    * Start a line with a star
    * Profit!
    
    或者：
    
    - Dashes work just as well
    - And if you have sub points, put two spaces before the dash or star:
      - Like this
      - And this

**对应的显示格式：**

有时候你可能需要带数字的列表：

*  One
 *  Two
 *  Three

有时候你可能需要带小圆点的列表：

*  Start a line with a star
 *  Profit!

或者：

*  Dashes work just as well
 *  And if you have sub points, put two spaces before the dash or star:
    
     *  Like this
     *  And this

### **三、图片** ###

**Markdown 语法：**

如果你希望嵌入一张图片，可以这么做：
    
    ![Yaktocat 的图片](https://octodex.github.com/images/yaktocat.png)

**对应的显示格式：**

如果你希望嵌入一张图片，可以这么做：

![013239bhcp5ddwphph4h6x.png][]

### **四、标题和引用** ###

**Markdown 语法：**

# 结构化文件
    
    有时，使用不同级别的标题来构造文档很有用。 用 `#` 开始创建标题。 行中的多个 `##` 表示较小的标题。
    
    ### 这是一个三级标题
    
    你可以使用 1个 `＃` 到 6 个 `######` 表示不同尺寸的标题。
    
    如果你想对某段文本进行引用，请在每行之前使用 > 字符：
    
    > Coffee. The finest organic suspension ever devised... I beat the Borg with it.
    > - Captain Janeway

对应的显示格式：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTU2MzE4_size_16_color_FFFFFF_t_70][]

### **五、代码** ###

**Markdown 语法：**

有很多不同的方式来使用 GitHub 的 markdown 来编写代码。如果你有内联代码块，用反引号包裹起来：`var example = true`。如果你有一个更长的代码块，你可以缩进四个空格：
    
        if (isAwesome){
          return true
        }
    
    GitHub 还支持称为代码篱笆的功能，它允许多行没有缩进：
    
    ```
    if (isAwesome){
      return true
    }
    ```
    
    如果你想使用对应语言的语法高亮：
    
    ```javascript
    if (isAwesome){
      return true
    }
    ```

**对应的显示格式：**

有很多不同的方式来使用 GitHub 的 markdown 来编写代码。如果你有内联代码块，用反引号包裹起来：var example = true。如果你有一个更长的代码块，你可以缩进四个空格：

if (isAwesome){
      return true
    }

GitHub 还支持称为代码篱笆的功能，它允许多行没有缩进：

if (isAwesome){
      return true
    }

如果你想使用对应语言的语法高亮：  
  
![160935vshzz47u4ffl4lh7.jpg][]

### **六、更多** ###

**Markdown 语法：**

GitHub 支持 Markdown 中的许多附加功能，它们可以帮助你引用和链接到别人。如果你想对某人发表评论，你可以在他们的名字前加上 @ 符号：Hey @kneath - 爱你的毛衣！

但我不得不承认，任务列表是我最喜欢的：  
  
\- \[x\] This is a complete item  
\- \[ \] This is an incomplete item  
  
当你在 Issue 的第一条评论中包含任务列表时，你会在 issues 列表中看到一条非常有用的进度条。它也工作在 Pull Requests 上！

还有，当然还可以使用 emoji 表情！:sparkles: :camel: :boom:

**对应的显示格式：**

GitHub 支持 Markdown 中的许多附加功能，它们可以帮助你引用和链接到别人。如果你想对某人发表评论，你可以在他们的名字前加上 @ 符号：Hey [@kneath][kneath] - 爱你的毛衣！

但我不得不承认，任务列表是我最喜欢的：

![162735sobdo3s44roxb3h5.jpg][]

当你在 Issue 的第一条评论中包含任务列表时，你会在 issues 列表中看到一条非常有用的进度条。它也适用于 Pull Requests！

还有，当然还可以使用 emoji 表情！ ![162446sa87rf0a7zzw4kor.png][] ![162446b3jgxjqr3x7zt8pj.png][] ![162445f8ztdka7zfmxxijk.png][]

--------------------

## **语法指南** ##

下面是 Markdown 语法的概述，您可以在 GitHub.com 上的任何地方或在自己的文本文件中使用它。

**标题**

# 这是一个 <h1> 标签
    ## 这是一个 <h2> 标签
    ###### 这是一个 <h6> 标签

**强调**

*这句话将会倾斜*
    _这句话也会倾斜_
    
    **这句话将会加粗**
    __这句话也会加粗__
    
    _你 **可以** 将它们联合起来使用_

### **列表** ###

**无序**

* Item 1
    * Item 2
      * Item 2a
      * Item 2b

**有序**

1. Item 1
    2. Item 2
    3. Item 3
       * Item 3a
       * Item 3b

**图片**

![GitHub Logo](/images/logo.png)
    Format: ![Alt Text](url)

**超链接**

http://github.com - automatic!
    [GitHub](http://github.com)

**块引用**

正如 Kanye West 所说：
    
    > We're living the future so
    > the present is our past.

**内联代码**

我觉你应该使用一个
    `<addr>` 元素代替。

--------------------

## **GitHub Flavored Markdown** ##

GitHub.com 使用自己的 Markdown 语法版本，提供了一组附加的有用功能，其中许多功帮助你更容易地在 GitHub.com 上面工作。

请注意，GitHub Flavored Markdown 的一些功能仅在 Issues 的描述和评论中，以及 Pull Requests 中可用。这些既包括 @mentions 也包括对 SHA-1 哈希，Issues 和 Pull Requests 的引用。任务列表也可以在 Gist 评论和 Gist Markdown 文件中。

**语法高亮**

下面是一个如何使用 [GitHub Flavored Markdown][] 语法高亮的示例：

```javascript
    function fancyAlert(arg) {
      if(arg) {
        $.facebox({div:'#foo'})
      }
    }
    ```

你也可以简单地将你的所有代码都缩进四个空格：

function fancyAlert(arg) {
          if(arg) {
            $.facebox({div:'#foo'})
          }
        }

这里有一个没有语法高亮的 Python 代码示例：

def foo():
        if not bar:
            return True

**Task Lists（任务列表）**

- [x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> supported
    - [x] list syntax required (any unordered or ordered list supported)
    - [x] this is a complete item
    - [ ] this is an incomplete item

如果在 Issue 的第一个评论中包含任务列表，则会在 issue 列表中获得一个便捷的进度指示器。它也适用于 Pull Requests！

**Tables（表格）**

你可以通过连字符（-）和竖线（|）来创建一个表格，其中连字符用于分割行，竖线用于分割列：

First Header | Second Header
    ------------ | -------------
    Content from cell 1 | Content from cell 2
    Content in the first column | Content in the second column

将会显示如下：

<table style="width:643.2px;"> 
 <tbody> 
  <tr> 
   <td style="border-color:#e3edf5;"> <p><strong>First Header</strong></p> </td> 
   <td style="border-color:#e3edf5;"> <p><strong>Second Header</strong></p> </td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">Content from cell 1</td> 
   <td style="border-color:#e3edf5;">Content from cell 2</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">Content in the first column</td> 
   <td style="border-color:#e3edf5;">Content in the second column</td> 
  </tr> 
 </tbody> 
</table>

**SHA 引用**

对提交的 [SHA-1 哈希][SHA-1]的任何引用将自动转换为 GitHub 上该提交的链接。

16c999e8c71134401a78d4d46435517b2271d6ac
    mojombo@16c999e8c71134401a78d4d46435517b2271d6ac
    mojombo/github-flavored-markdown@16c999e8c71134401a78d4d46435517b2271d6ac

**在仓库中的 Issue 引用**

任何对一个 Issue 或 Pull Request 的引用将会被自动转换为一个链接。

**用户名 @mentions**

键入 @ 符号，后面跟一个用户名，将通知该用户来查看评论。这被称之为“@memtion”（@提及），因为你提到了这个人。你也可以 @memtion 组织内部的一个小组。

**自动链接网址**

任何网址（如 [http://www.github.com][http_www.github.com]）都会自动转换为可点击的链接。

**删除线**

任何使用两个波浪符号包裹的单词（如 ~~ this ~~）会出现删除线。

**Emoji**

GitHub 支持 [Emoji][]！ ![224538q4pcfx044vpt4t5v.png][] ![224538qe5n3lul5qpezcee.png][] ![224537a38t4z083orelo0x.png][]

要查看我们支持的每个 Emoji 图标列表，请查看表情符号表 -> [传送门][Link 3]。

[Link 1]: https://guides.github.com/features/mastering-markdown
[Markdown]: http://daringfireball.net/projects/markdown
[Gists]: https://gist.github.com/
[Link 2]: http://google.com/
[013239bhcp5ddwphph4h6x.png]: /images/20220326/4f8d1ebee1bc41bdb1452c1192f63f45.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTU2MzE4_size_16_color_FFFFFF_t_70]: /images/20220326/c7ed7c74e6cc459f9a7063e9aca82413.png
[160935vshzz47u4ffl4lh7.jpg]: /images/20220326/0676fb4cef404e10a221a4bb60e890d7.png
[kneath]: https://github.com/kneath
[162735sobdo3s44roxb3h5.jpg]: /images/20220326/58cbab742feb408da0c536d920885a63.png
[162446sa87rf0a7zzw4kor.png]: https://xxx.ilovefishc.com/forum/201702/16/162446sa87rf0a7zzw4kor.png
[162446b3jgxjqr3x7zt8pj.png]: https://xxx.ilovefishc.com/forum/201702/16/162446b3jgxjqr3x7zt8pj.png
[162445f8ztdka7zfmxxijk.png]: /images/20220326/365c629d9c5145bea21f6a5cb312c7e2.png
[GitHub Flavored Markdown]: https://help.github.com/categories/writing-on-github
[SHA-1]: https://zh.wikipedia.org/zh/SHA-1
[http_www.github.com]: http://www.github.com/
[Emoji]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#using-emoji
[224538q4pcfx044vpt4t5v.png]: https://xxx.ilovefishc.com/forum/201702/16/224538q4pcfx044vpt4t5v.png
[224538qe5n3lul5qpezcee.png]: https://xxx.ilovefishc.com/forum/201702/16/224538qe5n3lul5qpezcee.png
[224537a38t4z083orelo0x.png]: /images/20220326/90381005520d4dbab8e4069154d8134b.png
[Link 3]: http://www.webpagefx.com/tools/emoji-cheat-sheet