Markdown Github Guide

Locations of key files/directories

GitHub Pages is a service that turns Markdown files into a website and hosts them for free on the internet. If you know how to use GitHub and you need to create a simple webpage, you can’t do better than GitHub Pages. Just create a new repository on GitHub, commit the Markdown files, and enable the GitHub Pages feature. Markdown style guide. Much of what makes Markdown great is the ability to write plain text, and get great formatted output as a result. To keep the slate clean for the next author, your Markdown should be simple and consistent with the whole corpus wherever possible.

GitHub Flavored Markdown, often shortened as GFM, is the dialect of Markdown that is currently supported for user content on GitHub.com and GitHub Enterprise. This formal specification, based on the CommonMark Spec, defines the syntax and semantics of this dialect. The comprehensive Markdown reference guide. Contribute to mattcone/markdown-guide development by creating an account on GitHub.

  • Basic config options: _config.yml
  • Top navigation bar config: _data/navigation.yml
  • Single pages: _pages/
  • Collections of pages are .md or .html files in:
    • _publications/
    • _portfolio/
    • _posts/
    • _teaching/
    • _talks/
  • Footer: _includes/footer.html
  • Static files (like PDFs): /files/
  • Profile image (can set in _config.yml): images/profile.png

Tips and hints

  • Name a file “.md” to have it render in markdown, name it “.html” to render in HTML.
  • Go to the commit list (on your repo) to find the last version Github built with Jekyll.
    • Green check: successful build
    • Orange circle: building
    • Red X: error
    • No icon: not built

Resources

Markdown guide

Header three

Header four

Header five
Header six

Blockquotes

Single line blockquote:

Quotes are cool.

Tables

Table 1

EntryItem
John Doe2016Description of the item in the list
Jane Doe2019Description of the item in the list
Doe Doe2022Description of the item in the list

Table 2

Header1Header2Header3
cell1cell2cell3
cell4cell5cell6
cell1cell2cell3
cell4cell5cell6
Foot1Foot2Foot3

Definition Lists

Definition List Title
Definition list division.
Startup
A startup company or startup is a company or temporary organization designed to search for a repeatable and scalable business model.
#dowork
Coined by Rob Dyrdek and his personal body guard Christopher “Big Black” Boykins, “Do Work” works as a self motivator, to motivating your friends.
Do It Live
I’ll let Bill O’Reilly explain this one.

Unordered Lists (Nested)

  • List item one
    • List item one
      • List item one
      • List item two
      • List item three
      • List item four
    • List item two
    • List item three
    • List item four
  • List item two
  • List item three
  • List item four

Ordered List (Nested)

  1. List item one
    1. List item one
      1. List item one
      2. List item two
      3. List item three
      4. List item four
    2. List item two
    3. List item three
    4. List item four
  2. List item two
  3. List item three
  4. List item four

Buttons

Make any link standout more when applying the .btn class.

Notices

Watch out! You can also add notices by appending {: .notice} to a paragraph.

HTML Tags

Address Tag

1 Infinite Loop
Cupertino, CA 95014
United States

Anchor Tag (aka. Link)

This is an example of a link.

Abbreviation Tag

The abbreviation CSS stands for “Cascading Style Sheets”.

Cite Tag

“Code is poetry.” —Automattic

Code Tag

You will learn later on in these tests that word-wrap: break-word; will be your best friend.

Strike Tag

This tag will let you strikeout text.

Emphasize Tag

The emphasize tag should italicize text.

Insert Tag

This tag should denote text.

Keyboard Tag

This scarcely known tag emulates keyboard text, which is usually styled like the <code> tag.

Preformatted Tag

This tag styles large blocks of code.

Quote Tag

Developers, developers, developers… –Steve Ballmer

Strong Tag

This tag shows bold text.

Subscript Tag

Markdown github guide pdf

Getting our science styling on with H2O, which should push the “2” down.

Superscript Tag

Still sticking with science and Isaac Newton’s E = MC2, which should lift the 2 up.

Variable Tag

This allows you to denote variables.

目录:

  • # 1 Introduction
    • ## 1.2 How to read This Books
  • # 2 Getting Started
  • # 3 Doing Things With Markdown
  • # 4 Basic Syntax
    • ## 4.1 Headings
    • ## 4.4 Emphasis
    • ## 4.5 Blockquotes
    • ## 4.6 Lists
      • ### 4.6.1 Ordered Lists
      • ### 4.6.2 Unordered Lists
      • ### 4.6.3 Adding Elements in Lists
    • ## 4.7 Code
    • ## 4.9 Links
      • ### 4.9.4 Reference-style Links
    • ## 4.11 Escaping Characters
  • # 5 Extendes Syntax
    • ## 5.1 Availability
    • ## 5.2 Tables
    • ## 5.3 Fenced Code Bloks
    • ## 5.5 Heading IDs
    • ## 5.9 Automatic URL Linking
  • # 6 Cheat Sheet

1.1Where to Get This Books

1.2 How to read This Books

1.2.1 Beginner Resources

1.2.2 Syntax Examples

1.2.3 Asides

1.2.4 Quirks

1.3 Contrbuting

1.4 Reporting Issues

1.5 Acknowledgements

2.1 Kicking the Tires

2.2 How Markdown Works

The short answer is that you need a Markdown application capable of processing the Markdown file. There are lots of applications available — everything from simple scripts to desktop applications that look like Microsoft Word. Despite their visual differences, all of the applications do the same thing. Like Dillinger, they all convert Markdown-formatted text to HTML so it can be displayed in web browsers.

Markdown applications use something called a Markdown processor (alsocommonly referred to as a “parser” or an “implementation”) to take the Markdown-formatted text and output it to HTML format. At that point, your document can be viewed in a web browser or combined with a style sheet and printed. You can see a visual representation of this process below.

2.3 Additional Resources

  • John Gruber’s Markdown documentation. The original guide written by the creator of Markdown.
  • Markdown Tutorial. An open source website that allows you to try Markdown in your web browser.
  • Awesome Markdown. A list of Markdown tools and learning resources.
  • Typesetting Markdown. A multi-part series that describes an ecosystem for typesetting Markdown documents using pandoc and ConTeXt.

注:

  1. 这里作者似乎在讲怎么配置以在这些应用的环境下实现markdown功能。

3.1 Webstes

3.2 Documents

3.3 Notes

3.4 Books

3.5 Presentations

3.6 Emails

3.7 Documentation

Nearly all Markdown applications support the basic syntax outlined in John Gruber’s original design document. There are minor variations and discrepancies between Markdown processors — those are noted inline wherever possible.

Using Markdown doesn’t mean that you can’t also use HTML. You can add HTML tags to any Markdown file. This is helpful if you prefer certain HTML tags to Markdown syntax. For example, some people find that it’s easier to use HTML tags for images.

4.1 Headings

To create a heading, add number signs (#) in front of a word or phrase.The number of number signs you use should correspond to the heading level. For example, to create a heading level three (<h3>), use three number signs (e.g., ### My Header).

Markdown

# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6

Display

Heading level 2

Heading level 3

Heading level 4

Heading level 5
Heading level 6

4.1.1 Alternate Syntax

Alternatively, on the line below the text, add any number of = characters for heading level 1 or - characters for heading level 2.

Markdown

Heading level 1

Heading level 2
------

Display

Heading level 2

4.2 Paragraphs

To create paragraphs, use a blank line to separate one or more lines of text. You should not indent paragraphs with spaces or tabs.要创建段落,请使用空行来分隔一行或多行文本。段落不应用空格或制表符来缩进。

Markdown

I really like using Markdown.
{blank line}
I think I'll use it from now on.

Display

I really like using Markdown.

I think I'll use it from now on.

4.3 Line Breaks

To create a line break (<br>), end a line with two or more spaces, and then type return.至少两空格并回车,以达到行末换行的目的。Markdown

This is the first line.{more than two space and then enter}
And this is the second line.

Display

This is the first line.
And this is the second line.

4.4 Emphasis

You can add emphasis by making text bold or italic.

4.4.1 Bold

To bold text, add two asterisks or underscores before and after a word or phrase. To bold the middle of a word for emphasis, add two asterisks without spaces around the letters.

Markdown

I love **bold text**.

I love __bold text__.

Love **is** bold

Display

I love bold text.

I love bold text.

Love is bold

4.4.2 Italic

To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisk without spaces around the letters.

Markdown

The *cat's meow*.

The _cat's meow_.

A *cat meow*

Display

The cat's meow.

The cat's meow.

A cat meow

4.4.3 Bold and Italic

To emphasize text with bold and italics at the same time, add three asterisks or underscores before and after a word or phrase.

Markdown

***Important*** text.

___Important___ text.

__*Important*__ text.

**_Important_** text.

Display

Important text.

Important text.

Important text.

Important text.

4.5 Blockquotes

To create a blockquote, add a > in front of a paragraph.

Markdown

> Dorothy followed her through many rooms.

Display

Dorothy followed her through many rooms.

4.5.1 Blockquotes with Multiple Paragraphs

Blockquotes can contain multiple paragraphs. Add a > on the blank lines between the paragraphs.

Markdown

> This the first paragraph.
>
> And this is the second paragraph.

Display

This the first paragraph.

And this is the second paragraph.

4.5.2 Nested Blockquotes

lockquotes can be nested. Add a >> in front of the paragraph you want to nest.

Markdown

> This the first paragraph.
>
>> And this is the nested paragraph.

Display

This the first paragraph.

And this is the nested paragraph.

4.5.3 Blockquotes with Other Elements

Blockquotes can contain other Markdown formatted elements. Not all elements can be used — you’ll need to experiment to see which ones work.

注:

  1. 块索引中其它功能的实现,不一定都能,作者发现斜体和加粗还是有效。

Markdown

> ##### The quarterly results look great!
>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
> *Everything* is going **well**.

Display

The quarterly results look great!
  • Revenue was off the chart.
  • Profits were higher than ever.

Everything is going well.

4.6 Lists

You can organize items into ordered and unordered lists.

注:

  1. 列表的实现需要保证列表全体独在一个段落并仅在一个段落,比如本列表含有2个项目(items),那应在项目1前和项目2后各有不少于一个空行并项目1、2之间不得有空行。
  2. 列表的紧上文字可解释为列表的标题,如:我在这里的列表紧上加了“注:”即表示列表内的项目1、2均是注释。
  3. 赘述一下,列表遇到空行方止。遇到换行符仅能换行,不能实现停止列表。

Markdown

注:

1. 列表的实现需要保证列表全体独在一个段落并仅在一个段落,比如本列表含有2个项目(items),那应在项目1前和项目2后各有不少于一个空行并项目1、2之间不得有空行。
2. 列表的紧上文字可解释为列表的标题,如:我在这里的列表紧上加了“注:”即表示列表内的项目1、2均是注释。
3. 赘述一下,列表遇到空行方止。遇到换行符仅能换行,不能实现停止列表。

Display

注:

  1. 列表的实现需要保证列表全体独在一个段落并仅在一个段落,比如本列表含有2个项目(items),那应在项目1前和项目2后各有不少于一个空行并项目1、2之间不得有空行。
  2. 列表的紧上文字可解释为列表的标题,如:我在这里的列表紧上加了“注:”即表示列表内的项目1、2均是注释。
  3. 赘述一下,列表遇到空行方止。遇到换行符仅能换行,不能实现停止列表。

4.6.1 Ordered Lists

To create an ordered list, add line items with numbers followed by periods. The numbers don’t have to be in numerical order, but the list should start with the number one.

Markdown

1. First item
2. Second item
3. Third item
4. Fourth item

Display

  1. First item
  2. Second item
  3. Third item
  4. Fourth item

Markdown

1. First item
1. Second item
1. Third item
1. Fourth item

Display

  1. First item
  2. Second item
  3. Third item
  4. Fourth item

Markdown

1. First item
8. Second item
3. Third item
5. Fourth item

Display

  1. First item
  2. Second item
  3. Third item
  4. Fourth item

4.6.1.1 Nesting List Items

To nest line items in an ordered list, indent the items four spaces or one tab.

Markdown

1. First item
2. Second item
3. Third item
{a tab or four spaces}1. Indented item
{a tab or four spaces}2. Indented item
4. Fourth item

Display

  1. First item
  2. Second item
  3. Third item
    1. Indented item
    2. Indented item
  4. Fourth item

4.6.2 Unordered Lists

To create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items. Indent one or more items to create a nested list.

Markdown

- First item
- Second item
- Third item
- Fourth ite

Display

  • First item
  • Second item
  • Third item
  • Fourth ite

Markdown

* First item
* Second item
* Third item
* Fourth item

Display

  • First item
  • Second item
  • Third item
  • Fourth item

Markdown

+ First item
* Second item
- Third item
+ Fourth item

Display

  • First item
  • Second item
  • Third item
  • Fourth item

4.6.2.1 Nesting List Items

To nest line items in an unordered list, indent the items four spaces or one tab.

Markdown

- First item
- Second item
- Third item
{a tab or four spaces}- Indented item
{a tab or four spaces}- Indented item
- Fourth item

Display

  • First item
  • Second item
  • Third item
    • Indented item
    • Indented item
  • Fourth item

4.6.3 Adding Elements in Lists

To add another element in a list while preserving the continuity of the list, indent the element four spaces or one tab, as shown in the following examples.

4.6.3.1 Paragraphs

Markdown

* This is the first list item.
* Here's the second list item.

{a tab or four spaces}I need to add another paragraph below the second list item.

* And here's the third list item.

Display

  • This is the first list item.
  • Here's the second list item.

    I need to add another paragraph below the second list item.

  • And here's the third list item.

4.6.3.2 Blockquotes

Markdown

* This is the first list item.
* Here's the second list item.

{a tab or four spaces}> A blockquote would look great here.

* And here's the third list item.

Display

  • This is the first list item.
  • Here's the second list item.

    A blockquote would look great here.

  • And here's the third list item.

4.6.3.3 Code Blocks

Code blocks are normally indented four spaces or one tab. When they’re in a list, indent them eight spaces or two tabs.

Markdown

1. Open the file.
2. Find the following code block on line 21:

{two tabs or eight spaces}Test

3. Update the title to match the name of your website.

Display

  1. Open the file.
  2. Find the following code block on line 21:

  3. Update the title to match the name of your website.

4.6.3.4 Images

Markdown

1. Open the file containing Tux, the Linux mascot.
2. Marvel at its beauty.

{a tab or four spaces}![Tux](images/tux.png)

3. Close the file.

Display

  1. Open the file containing Tux, the Linux mascot.
  2. Marvel at its beauty.

  3. Close the file.

4.7 Code

To denote a word or phrase as code, enclose it in tick marks (`).

Markdown

At the command prompt, type `nano`.

Display

At the command prompt, type nano.

4.7.1 Escaping Tick Marks

If the word or phrase you want to denote as code includes one or more tick marks, you can escape it by enclosing the word or phrase in double tick marks (``).

Markdown

``Use `code` in your Markdown file. Use `code` in your Markdown file. Use `code` in your Markdown file. Use `code` in your Markdown file. Use `code` in your Markdown file.``

Display

Use `code` in your Markdown file. Use `code` in your Markdown file. Use `code` in your Markdown file. Use `code` in your Markdown file. Use `code` in your Markdown file.

注:

  1. 看作者示例,似乎````中间的``将直接显示,但看紧上示例,我的博客markdown环境似乎````仍解读为代码块。

4.7.2 Code Blocks

To create code blocks, indent every line of the block by at least four spaces or one tab.

Markdown

{a tab or four spaces}<html>
{a tab or four spaces}{a tab or four spaces}<head>
{a tab or four spaces}{a tab or four spaces}</head>
{a tab or four spaces}</html>

Display

注:

  1. 代码块也可以用``````,若用紧上示例方式,标记代码块可每行前加至少一Tab,若代码本身有缩进,应相应增加Tab。

4.8 Horizontal Rules

To create a horizontal rule, use three or more asterisks (***), dashes (---), or underscores (___) on a line by themselves.

Markdown

Display

注:

  1. 本笔记正是靠这种方式呈现Markdown语法和其显示效果。
  2. 最好使用___来表示水平线,如用---来表示水平线,将与标题(二级标题)的替代用法冲突。

4.9 Links

To create a link, enclose the link text in brackets (e.g., [Duck Duck Go]) and then follow it immediately with the URL in parentheses (e.g., (https://duckduckgo.com)).

Markdown

Use [Duck Duck Go](https://duckduckgo.com).

Display

Use Duck Duck Go.

4.9.1 Adding Titles

You can optionally add a title for a link. This will appear as a tooltip when the user hovers over the link. To add a title, enclose it in parentheses after the URL.

Markdown

Use [Duck Duck Go](https://duckduckgo.com 'My search engine!').

Display

Use Duck Duck Go.

4.9.2 URLs and Email Address

To quickly turn a URL or email address into a link, enclose it in angle brackets.

Markdown

<'>https://eff.org>
<[email protected]>

Display

https://eff.org
[email protected]

注:

  1. 作者示例环境中,上述方法对网址和邮箱均有效,我的博客markdown环境仅对邮箱有效。

4.9.3 Formatting Links

To emphasize links, add asterisks before and after the brackets and parentheses.

Markdown

I love supporting **[EFF](https://eff.org)**.
This is the *[EFF](https://eff.org)*.

Display

I love supporting EFF.
This is the EFF.

4.9.4 Reference-style Links

Reference-style links are a special kind of link that make URLs easier to display and read in Markdown. Reference-style links are constructed in two parts: the part you keep inline with your text and the part you store somewhere else in the file to keep the text easy to read.

4.9.4.1 Formatting the First Part of the Link

The first part of a reference-style link is formatted with two sets of brackets. The first set of brackets surrounds the text that should appear linked. The second set of brackets displays a label used to point to the link you’re storing elsewhere in your document.

Although not required, you can include a space between the first and second set of brackets. Also, the label in the second set of brackets is not case sensitive and can include letters, numbers, spaces, or punctuation.

This means the following example formats are all roughly equivalent for the first part of the link:

Markdown

[hobbit-hole][1]

[hobbit-hole] [1]

[hobbit-hole][a]

[hobbit-hole][A]

Display

[hobbit-hole][a]

[hobbit-hole][A]

注:

1.如上示例,我的博客markdown环境仅支持前两种形式。按我理解,两个中括号,前一中括号内是文本中显示的内容,后一中括号是连接的编号,对应下面给出的链接。

4.9.4.2 Formatting the Second Part of the Link

The second part of a reference-style link is formatted with the following attributes:

  1. The label, in brackets, followed immediately by a colon and at least one space (e.g., [label]: ).
  2. The URL for the link, which you can optionally enclose in angle brackets.
  3. The optional title for the link, which you can enclose in double quotes, single quotes, or parentheses.

This means the following example formats are all roughly equivalent for the second part of the link:

Markdown

[hobbit-hole]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle
[hobbit-hole]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit lifestyles'
[hobbit-hole]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit lifestyles'
[hobbit-hole]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle (Hobbit lifestyles)
[hobbit-hole]: <'>https://en.wikipedia.org/wiki/Hobbit#Lifestyle> 'Hobbit lifestyles'
[hobbit-hole]: <'>https://en.wikipedia.org/wiki/Hobbit#Lifestyle> 'Hobbit lifestyles'
[hobbit-hole]: <'>https://en.wikipedia.org/wiki/Hobbit#Lifestyle> (Hobbit lifestyles)

Display

注:

  1. 行内链接和参考式链接均不会显示链接,以上是参考式链接第二部分,当然不会有显。

4.9.4.3 An Example Putting the Parts Together

Say you add a URL as a standard URL link to a paragraph and it looks like this in Markdown:

Markdown

In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to eat: it was a [hobbit-hole](https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit life 5 styles'), and that means comfort.

Display

In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to eat: it was a hobbit-hole, and that means comfort.

Markdown

Markdown Github Guide Pdf

In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to eat: it was a [hobbit-hole][1], and that means comfort.

{can 1000 lines between the text and its URL}

[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit lifestyles'

Display

In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to eat: it was a hobbit-hole, and that means comfort.

注:

  1. 前者为行内链接,后者为参考式链接。

4.10 Images

To add an image, add an exclamation mark (!), followed by alt text in brackets, and the path or URL to the image asset in parentheses. You can optionally add a title after the URL in the parentheses.

Markdown

![Philadelphia's Magic Gardens. This place was so cool!](images/philly-magic-garden.png 'Philadelphia's Magic Gardens')

Display

4.11 Escaping Characters

To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash () in front of the character.

Markdown

* Without the backslash, this would be a bullet in an unordered list.

Display

* Without the backslash, this would be a bullet in an unordered list.

4.11.1 Characters You Can Escape

You can use a backslash to escape the following characters.

Markdown


`

*
_
{ }
[ ]
()
#
+
-
.
!

Display


`

*
_
{ }
[ ]
( )
#
+
-
.
!

The basic syntax outlined in John Gruber’s original design document added many of the elements needed on a day-to-day basis, but it wasn’t enough for some people. That’s where extended syntax comes in. Several individuals and organizations took it upon themselves to extend the basic syntax by adding additional elements like tables, code blocks, syntax highlighting, URL auto-linking, and footnotes. These elements can be enabled by using a lightweight markup language that builds upon the basic Markdown syntax, or by adding an extension to a compatible Markdown processor.

Markdown

Display

5.1 Availability

Extended syntax isn’t available in all Markdown applications. You’ll need to check whether or not the lightweight markup language your application is using supports extended syntax. If it doesn’t, it may still be possible to enable extensions in your Markdown processor.

注:

  1. 作者这里说了,扩展语法不是在每个markdown环境中均有效。

Markdown

Display

5.1.1 Lightweight Markup Languages

There are several lightweight markup languages that are supersets of Markdown. They include Gruber’s basic syntax and build upon it by adding additional elements like tables, code blocks, syntax highlighting, URL auto-linking, and footnotes. Many of the most popular Markdown applications use one of the following lightweight markup languages:

  • CommonMark
  • GitHub Flavored Markdown (GFM)
  • Markdown Extra
  • MultiMarkdown

注:

  1. 作者说,以上三个轻量级标记语言(lightweight markup languages),从语法包含的内容上来说是markdown语法的超集。也即,此三者可实现markdown全部基本语法功能并增加了新的扩展功能。

Markdown

Display

5.1.2 Markdown Processors

There are dozens of Markdown processors available. Many of them allow you to add extensions that enable extended syntax. Check your processor’s documentation for more information.

Markdown

Display

5.2 Tables

To add a table, use three or more hyphens (---) to create each column’s header, and use pipes ( ) to separate each column. You can optionally add pipes on either end of the table.

Markdown

Syntax Description
------ ------
Header Title
Paragraph Text

Display

SyntaxDescription
HeaderTitle
ParagraphText

Creating tables with hyphens and pipes can be tedious. To speed up the process, try using the Markdown Tables Generator. Build a table using the graphical interface, and then copy the generated Markdown-formatted text into your file.

5.2.1 Alignment

You can align text in the columns to the left, right, or center by adding a colon (:) to the left, right, or on both side of the hyphens within the header row.

Markdown

Syntax Description Test Text
:--- :----: ---:
Header Title Here's this
Paragraph Text And more

Display

SyntaxDescriptionTest Text
HeaderTitleHere's this
ParagraphTextAnd more

5.2.2 Formatting Text in Tables

You can format the text within tables. For example, you can add links, code (words or phrases in tick marks (`) only, not code blocks), and emphasis. You can’t add headings, blockquotes, lists, horizontal rules, images, or HTML tags.

Markdown

Syntax Description Test Text
:--- :----: ---:
Header ```Title<br>Title<br>Title<br>Title<br>Title<br>Title<br>Title<br>Title<br>Title``` Here's this
Paragraph Text And more

Display

SyntaxDescriptionTest Text
HeaderTitle<br>Title<br>Title<br>Title<br>Title<br>Title<br>Title<br>Title<br>TitleHere's this
ParagraphTextAnd more

注:

  1. 显然表格内无法实现代码块(Code Bloks)语法,因其需要靠换行加一会车或四空格来确定代码块内的每行,而换行是表(table)的语法,所以两者将冲突。
  2. 若说到表格内实现有栅栏的代码块(Fenced Code Bloks)语法(``````这种),可以使用,但代码块需要换行,而表内的``````的内部的<br>将不被解析只能直接显示。

5.2.3 Escaping Pipe Characters in Tables

You can display a pipe ( ) character in a table by using its HTML character code (&#124;).

Markdown


&#124;

Display


注:

  1. 按上,直接显示 有两种办法,如下所示。

5.3 Fenced Code Bloks

The basic Markdown syntax allows you to create code blocks by indenting lines by four spaces or one tab. If you find that inconvenient, try using fenced code blocks. Depending on your Markdown processor or editor, you’ll use three tick marks (```) or three tildes(∼∼∼) on the lines before and after the code lock. The best part? You don’t have to indent any lines!

Markdown

```
{
'firstName': 'John',
'lastName': 'Smith',
'age': 25
}
```

Display

5.3.1 Synatax Highlighting

Many Markdown processors support syntax highlighting for fenced code blocks. This feature allows you to add color highlighting for whatever language your code was written in. To add syntax highlighting, specify a language next to the tick marks before the fenced code block.

Markdown

```json
{
'firstName': 'John',
'lastName': 'Smith',
'age': 25
}
```

Display

注:

  1. 我的博客markdown环境不支持语法高亮,语法高亮即变成语法对应的类(如函数等)将相应显示不同颜色。

5.4 Footnotes

Footnotes allow you to add notes and references without cluttering the body of the document. When you create a footnote, a superscript number with a link appears where you added the footnote reference. Readers can click the link to jump to the content of the footnote at the bottom of the page. 脚注允许您添加注释和引用,而不会打乱文档的主体。当您创建脚注时,在添加脚注引用的地方将出现一个带链接的上标数字。读者可以点击链接跳转到页面底部脚注的内容。

To create a footnote reference, add a caret and an identifier inside brackets ([^1]). Identifiers can be numbers or words, but they can’t contain spaces or tabs. Identifiers only correlate the footnote reference with the footnote itself — in the output, footnotes are numbered sequentially. 要创建脚注引用,请在括号内添加插入符号和标识符([^1])。标识符可以是数字或单词,但不能包含空格或制表符(tabs)。标识符只将脚注引用与脚注本身关联—在输出中,脚注按顺序编号。

Add the footnote using another caret and number inside brackets with a colon and text ([^1]: My footnote.). You don’t have to put footnotes at the end of the document. You can put them anywhere except inside other elements like lists, block quotes, and tables.使用括号内的另一个插入符号和数字加上冒号和文本添加脚注([^1]: My footnote.)。不必在文件的末尾加上脚注。可将脚注放在任何位置,不放在列表(lists)、块引用(block quotes)和表(tables)内部即可。(注:不必将脚注放在文末,脚注内容将自动出现在文末。)

Markdown

Here's a simple footnote,[^1] and here's a longer one.[^bignote]
[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.<br>
{a tab or four spaces}Indent paragraphs to include them in the footnote.<br>
{a tab or four spaces}`{ my code }`<br>
{a tab or four spaces}Add as many paragraphs as you like.

Display

Here's a simple footnote,1 and here's a longer one.2

注:

  1. 脚注是对文本位置进行补充说明,格式为在需添加脚注的文本位置处添加[^标识符],并在除列表快引用、表内部以外任何地方写下脚注的内容,格式为[^标识符]: 脚注文本。
  2. 文本位置和脚注依靠标识符对应,标识符可取不包含空格符和制表符的任何字符,但无论取了什么合法的标识符,显示的标识符均将按照脚注出现在文本的位置自动从1开始。
  3. 无论脚注放在什么位置,脚注文本均将自动出现在文末。
  4. 按作者意思,其markdown环境下,脚注文本可分段,分段时候只需增加缩进(一个制表符或四个空格符)。但我博客markdown环境下,按作者方法脚注无法分段,增加缩进仅起到表明之后内容也属于脚注的作用。在缩进基础上再在段后加入分行符号(<br>),仍仅能分行而非真正分段。

5.5 Heading IDs

Many Markdown processors support custom IDs for headings — some Markdown processors automatically add them. Adding custom IDs allows you to link directly to headings and modify them with CSS. To add a custom heading ID, enclose the custom ID in curly braces on the same line as the heading.许多Markdown处理器支持标题的自定义id——一些Markdown处理器会自动添加它们。添加自定义id允许您直接链接到标题并用CSS修改它们。要添加自定义标题ID,请将自定义ID用大括号括起来,与标题位于同一行。

Markdown

### My Great Heading {#custom-id}

Display

My Great Heading

5.5.1 Linking to Heading IDs

You can link to headings with custom IDs in the file by creating a standard link with a number sign (#) followed by the custom heading ID.可以通过创建一个标准链接来链接到文件中带有自定义ID的标题,该链接的数字符号(#)后面跟着自定义标题ID。

Other websites can link to the heading by adding the custom heading ID to the full URL of the webpage(e.g,[Heading IDs](https:/www.eff.org/page#heading-ids)).其他网站可以通过将自定义标题ID添加到网页的完整URL链接到标题(例如e.g,[Heading IDs](https:/www.eff.org/page#heading-ids))。

Markdown

[Heading IDs](#heading-ids)

Display

注:

  1. 猜测此语法应能实现文章内部导航,即点击标题内容自动到达标题所对应的文字位置。暂未实验,待本文全部完成再来试验。
  2. 确实此功能是用来根据标题进行页面导航,导航后页面顶端即目标标题,结合列表实现了目录功能。但是此方法应不是最好方法,暂时先这样。
  3. 呈现博客文章内容最好的方式也许是根据标题折叠展开,当不需要看的时候折叠,当需要看的时候展开。Markdown能实现吗?
  4. VSCode中搜索toc,可其示例似乎可以自动生成可导航目录,有空试一下效果。

5.5.1.1

Markdown

Title

content!!!

Display

CLICK ME标签与正文间一定要空一行!!!

这似乎是html语法,实现折叠功能,见于markdown折叠内容语法。

5.6 Definition Lists

Some Markdown processors allow you to create definition lists of terms and their corresponding definitions. To create a definition list, type the term on the first line. On the next line, type a colon followed by a space and the definition.一些Markdown处理器允许您创建术语及其对应定义的定义列表。在第一行键入这个术语。在下一行中,键入冒号,后跟空格和定义。

Markdown

First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.

Display

First Term
This is the definition of the first term.
Second Term
This is one definition of the second term.
This is another definition of the second term.

注:

  1. 必须留空格。

5.7 Strikethrough

You can “strikethrough” words by putting a horizontal line through the center of them. This feature allows you to indicate that certain words are a mistake not meant for inclusion in the document. To strikethrough words, use two tilde symbols (∼∼) before and after the words.可以通过在单词中间画一条水平线来“划掉”单词。这个特性用来标记文内错误文字。错误文字前后使用两个波浪线(∼∼)来“划掉”此错误文字。

Markdown

The world is ~~flat~~ round.

Display

The world is flat round.

5.8 Task Lists

Task lists allow you to create a list of items with checkboxes. In Markdown applications that support task lists, checkboxes will be displayed next to the content. To create a task list, add dashes (-) and brackets with a space ([ ]) in front of task list items. To select a checkbox, add an x in between the brackets ([x]).任务列表允许您创建带有复选框的项列表。在支持任务列表的标记应用程序中,复选框将显示在内容旁边。要创建任务列表,请在任务列表项前添加破折号(-)和带空格([ ])的方括号。要选中复选框,在中括号内加x([x])。

Markdown

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

Display

5.9 Automatic URL Linking

Many Markdown processors automatically turn URLs into links. That means if you type http://www.example.com, your Markdown processor will automatically turn it into a link even though you haven’t used brackets.许多Markdown处理器自动将URL转换为链接。这意味着,如果您输入http://www.example.com,Markdown处理器将自动将其转换为链接,即使没有使用方括号。

Markdown

Display

5.9.1 Disabling Automatic URL Linking

If you don’t want a URL to be automatically linked, you can remove the link by denoting the URL as code with tick marks.如果不希望URL被自动链接,可以通过将URL标记为带有标记的代码来删除链接。

Markdown

`http://www.example.com`

Adobe premiere elements 2017. Display

http://www.example.com

This cheat sheet provides a quick overview of all the Markdown syntax elements. It can’t cover every edge case! If you need more information about any of these elements, refer back to the chapters on basic and extended syntax.此备忘单提供了所有Markdown语法元素的快速概览。它不能覆盖所有的边缘情况!如果您需要关于这些元素的更多信息,请参阅关于基本语法和扩展语法的章节。

Markdown

Display

6.1 Basic Syntax

These are the elements outlined in John Gruber’s original design document. All Markdown applications support these elements.这些是John Gruber的原始设计文档中概述的元素。所有的Markdown应用程序都支持这些元素。

Markdown

Heading
# H1
## H2
### H3

Bold
**bold text**

Italic
*italicized text*

Blockquote

> blockquote

Ordered list

1. First item
2. Second item
3. Third item

Unordered list

- First item
- Second item
- Third item

Code
`code`

Horizontal Rule
___

Link
[title](https://www.example.com)

Image
![alt text](image.jpg)

Display

Heading

H2

H3

Bold
bold text

Italic
italicized text

Blockquote

blockquote

Ordered list

  1. First item
  2. Second item
  3. Third item

Unordered list

  • First item
  • Second item
  • Third item

Code
code

Horizontal Rule

Link
title

Image

6.2 Extended Syntax

These elements extend the basic syntax by adding additional features. Not all Markdown applications support these elements.这些元素通过添加附加功能扩展了基本语法。并非所有的Markdown应用程序都支持这些元素。

Markdown

Table

Syntax Description
------ ------
Header Title
Paragraph Text

Fencd Code Block
```
{
'firstName': 'John',
'lastName': 'Smith'
}
```
Footnote
Here's a sentence with a footnote. [^1]

Heading IDs
### My Great Heading {#custom-id}

Definition List

term
: definition

Strikethrough
~~The world is flat.~~

Task List

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

Display

Table

SyntaxDescription
HeaderTitle
ParagraphText

Fencd Code Block

Footnote
Here's a sentence with a footnote. 1

Heading IDs

Markdown File Format

My Great Heading

Definition List

term
definition

Github Markdown Reference

Strikethrough
The world is flat.

Task List

Matt Cone is a technical writer at Fastly. He has experience creating documentation for organizations like Linode and the U.S.Department of Health and Human Services. Matt’s first book, Master Your Mac, was published by No Starch Press. To get in touch with Matt, visit http://mattcone.com. 作者Matt Cone是Fastly的技术作家。他有为Linode和美国卫生及公众服务部等组织编写文档的经验。Matt的第一本书《掌握你的Mac》是由No Starch出版社出版。请访问http://mattcone.com与Matt联系。

Github Markdown Tutorial

  1. This is the first footnote. [return]
  2. Here's one with multiple paragraphs and code.
    Indent paragraphs to include them in the footnote.
    { my code }
    Add as many paragraphs as you like.

    [return]