掌握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

效果如下：

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! ✨ 🐫 💥

效果如下

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

tag

This is an

tag

This is an
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
Format: Alt Text

链接

http://github.com - automatic!
GitHub

块注释 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 tags 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  阅读(882)  评论(0)    收藏  举报

导航