掌握Markdown

翻译自 https://guides.github.com/features/mastering-markdown/
转载请注明链接

掌握Markdown

Markdown是Github平台上一种轻量且易用，用于设计写作的样式的语法。

我们会学习什么

  • Markdown格式如何简化风格化的协作编辑
  • Markdown和传统格式有何不同
  • 如何使用Markdown格式化文本
  • 如何使用Github的Markdown自动渲染
  • 如何应用Github独有的Markdown扩展

什么是Markdown？

Markdown是一中在web上设置文本样式的方法。你可以控制文档的显示；使用加粗或者斜体格式化单词，添加图片、创建列表只是我们使用Markdown时可以做的少数几件事情。最主要的是，Markdown只是包含一些非字母字符的普通文本，就像 # 和 *。

你可以在GItHub上的大多数地方使用Markdown：

  • Gists （GitHub的一个服务，类似于一个在线的记事本或便利贴，可以用来记录一些代码的小片段或者其他类似的内容）
  • 在问题中评论和合并请求（Pull Requests，应该是执行git pull命令的意思，获取并合并其他的库）
  • 文件使用.md和.markdown作为扩展名

更多内容，请参阅github帮助中的“Writing on GitHub”

例子

文本——Text
It's very easy to make some words \*\*bold** and other words \*italic* with Markdown. You can even \[link to Google!\]\(http://google.com)
效果如下：

It's very easy to make some words bold and other words italic with Markdown. You can even link to Google!

列表——Lists
Sometimes you want numbered lists:
    
1. One
2. Two
3. Three
    
Sometimes you want bullet points:
    
* Start a line with a star
* Profit!
    
Alternatively,
    
- Dashes work just as well
- And if you have sub points, put two spaces before the dash or star:
  - Like this
  - And this
效果如下：

Sometimes you want numbered lists:

  1. One
  2. Two
  3. Three

Sometimes you want bullet points:

  • Start a line with a star
  • Profit!

Alternatively,

  • Dashes work just as well
  • And if you have sub points, put two spaces before the dash or star:
    • Like this
    • And this
图片——images
If you want to embed images, this is how you do it:

![Image of Yaktocat](https://octodex.github.com/images/yaktocat.png)
效果如下：

If you want to embed images, this is how you do it:

Image of Yaktocat

标题和注释——Headers & Quotes
# Structured documents

Sometimes it's useful to have different levels of headings to structure your documents. Start lines with a `#` to create headings. Multiple `##` in a row denote smaller heading sizes.

### This is a third-tier heading

You can use one `#` all the way up to `######` six for different heading sizes.

If you'd like to quote someone, use the > character before the line:

> Coffee. The finest organic suspension ever devised... I beat the Borg with it.
> - Captain Janeway
效果如下：

Structured documents

Sometimes it's useful to have different levels of headings to structure your documents. Start lines with a # to create headings. Multiple ## in a row denote smaller heading sizes.

This is a third-tier heading

You can use one # all the way up to ###### six for different heading sizes.

If you'd like to quote someone, use the > character before the line:

Coffee. The finest organic suspension ever devised... I beat the Borg with it.

  • Captain Janeway
代码——code
There are many different ways to style code with GitHub's markdown. If you have inline code blocks, wrap them in backticks: `var example = true`.  If you've got a longer block of code, you can indent with four spaces:

    if (isAwesome){
      return true
    }

GitHub also supports something called code fencing, which allows for multiple lines without indentation:

```
if (isAwesome){
  return true
}
```

And if you'd like to use syntax highlighting, include the language:

```javascript
if (isAwesome){
  return true
}
```
效果如下

There are many different ways to style code with GitHub's markdown. If you have inline code blocks, wrap them in backticks: var example = true. If you've got a longer block of code, you can indent with four spaces:

if (isAwesome){
  return true
}

GitHub also supports something called code fencing, which allows for multiple lines without indentation:

if (isAwesome){
  return true
}

And if you'd like to use syntax highlighting, include the language:

if (isAwesome){
  return true
}
其他——Extras
GitHub supports many extras in Markdown that help you reference and link to people. If you ever want to direct a comment at someone, you can prefix their name with an @ symbol: Hey @kneath — love your sweater!

But I have to admit, tasks lists are my favorite:

- [x] This is a complete item
- [ ] This is an incomplete item

When you include a task list in the first comment of an Issue, you will see a helpful progress bar in your list of issues. It works in Pull Requests, too!

And, of course emoji! :sparkles: :camel: :boom:
效果如下

GitHub supports many extras in Markdown that help you reference and link to people. If you ever want to direct a comment at someone, you can prefix their name with an @ symbol: Hey @kneath — love your sweater!

But I have to admit, tasks lists are my favorite:

When you include a task list in the first comment of an Issue, you will see a helpful progress bar in your list of issues. It works in Pull Requests, too!

And, of course emoji! ✨ 🐫 💥

语法指南

这里是Markdown语法的一个概述，你可以在GitHub.com上或者你自己的文本文件中的任何地方使用。

页眉 headers

# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag

强调 Emphasis

*This text will be italic*
_This will also be italic_

**This text will be bold**
__This will also be bold__

_You **can** combine them_

列表 Lists

无序列表

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

有序列表

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

图片 images

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

链接

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

块注释 Blockquotes

As Kanye West said:

> We're living the future so
> the present is our past.

行内代码 Inline code

I think you should use an
`<addr>` element here instead.

GitHub风格的Markdown

GitHub.com使用它自己的Markdown语法版本，提供附加的有用的功能集，其中许多功能使它更容易在GitHub.com上处理内容。

注意，GitHub风格的Markdown的一些特性仅在对问题和拉动请求描述和评论时有效。这包括@mentions（这里的mentions应该是跟QQ里@一个人的意思类似，表示通知人），以及对SHA-1 hashes，Issues 和合并请求的引用。在Gist描述和Gist Markdown中任务列表也有效。

语法高亮

这了是一个如何使用GitHub风格的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

任务列表

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

如果你在一个问题的第一评论里使用了一个任务列表，你会在你的问题列表中得到一个简单的进度指示器。它在合并请求时也可以工作。

表格

你可以通过组合单词列表并使用连字符-（在第一行）来创建一个表格，然后使用管道符|分开每一列。

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

会变成

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

SHA引用

对提交的SHA-1 hash任何引用都会自动转换成一个指向GitHub上的提交的链接。

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

发布存储库中的引用

任何涉及问题和合并请求的数字都会自动转换成一个链接。

#1
mojombo#1
mojombo/github-flavored-markdown#1

Username @mentions

这里的mentions应该是通知的意思

输入一个@，后面跟一个用户名，会通知那个人来查看评论。这叫做“@mention”，因为你提到的是一个人。你还可以在一个组织内@mention（通知）一个团队

URLS的自动连接

任何URL（类似http://www.github.com/）会自动转换成一个可点击的链接。

删除线

任何使用两个波浪线包起来的单词会出现删除线（就像~~this~~）。

emoji

GitHub支持emoji！
要查看我们支持的所有图片的列表，请查看Emoji Cheat Sheet

posted on 2018-02-13 23:14  R_e  阅读(798)  评论(0)  编辑  收藏  举报

导航