दीपक (Gopal) दुबे ·(Deepak's Blog)

Markdown Concise Notes

15 Sep 2019 Tech-Post

Github Pages recommends using the Markdown language to write blog content. Let’s talk about Markdown today!

Markdown — Markdown is the language of choice for blogging.

When I went to school, I briefly touched Markdown, but I put it down after I learned a little bit of it, and I didn’t pay much attention to it because I didn’t need to use it in my work until one day when I found out that even the most basic syntax can be written wrongly, and so I decided to spend some time to refresh myself. I started using it in GitHub Pages to write blogs and edit README files of projects. After doing a little research, I found that writing development documents, editing WeChat public number articles and email content, etc. can be perfectly supported natively, and suddenly I realized that Markdown is not a chicken rib. On the contrary, it can be said that Markdown has now penetrated all aspects of technology and become the first choice for writing text documents.

So first let’s look at the definition of Markdown:

Markdown is a lightweight markup language, founded by John Gruber, that allows people to “write documents in an easy-to-read, easy-to-write, plain text format and then convert them into valid XHTML (or HTML) documents”. -Wikipedia

Take a look at the language together!

Background

Advantages

  1. focused on textual content;

  2. plain text, easy to read and write, can be easily incorporated into version control;

  3. simple syntax, no learning cost, can easily make beautiful and generous layout while coding.

Usage Scenarios

  • :: Various types of code hosting platforms

    Mainstream code hosting platforms, such as GitHub, GitLab, BitBucket, Coding, Gitee, etc., all support Markdown syntax, and many open-source projects use Markdown to write READMEs, development documents, help files, and wikis.

  • Technical communities and writing platforms

    StackOverflow, Nuggets, Jane Book, GitBook

Personally, I feel sorry that the platforms may use different languages to implement the Markdown parsing engine, or use different versions of the same parsing engine, and there may be different degrees of customization and extension, which leads to the use of Markdown on different platforms when writing experience is not entirely consistent. Luckily, there are some standard syntaxes that are recognized and supported by all of them.

Editing Tools

Theoretically, any text editor can be used to edit a Markdown document, and they all offer varying degrees of syntax highlighting, previewing, etc. The following is just a list of some of the tools available, so choose the one that suits your needs.

  • Modern editors

    VSCode

  • Traditional editors

    Vim / Sublime Text / Notepad++

  • IDE’s own editor

    IntelliJ IDEA / WebStorm

  • Specialized editors

    Ulysses / Mou / Typora / Markpad

  • Online editors

    Various Markdown-enabled websites offer online editors

Syntax

Title

Markdown:

## atx-style primary headings

## Secondary headings

###### Six-level headings

Setext-style First-level headings
===

Second-level headings
---

Preview effect:

atx-style First level header

Secondary header

Sixth level header

Setext-style first-level headings

Secondary headings

** Corresponds to HTML:**

<h1>atx-style primary heading</h1>

<h2>second-level headings</h2>

<h6>Sixth-level headings</h6>

<h1>Setext-style Primary headings</h1>

<h2>Second-level headings</h2>
``

### Paragraph

Several consecutive lines of text without a blank line in the middle are considered a paragraph.

**Markdown:**

``##
The sun is over the mountains.

The Yellow River flows into the sea.
(No space after the period.)

I want to see a thousand miles.

To reach the next level.  
(There are two spaces after the period.)

**Preview: **

The sun is over the mountains.

The Yellow River flows into the sea. (No space after the period)

I want to see a thousand miles.

To reach the next level.
(There are two spaces after the period.)

** corresponds to HTML: **

<p>The sun is over the mountains.

<p>The Yellow River flows into the sea.
（句号后面没有空格）</p>

<p>欲穷千里目，</p>
	@@ -163,167 +156,127 @@ To reach the next level.
  <br>
  （句号后面有俩空格）
</p>

In-line formatting

Emphasis effects on paragraphs or parts of text.。

Markdown：

followed by two words **italicized**
Two words at the end *Italicized*

Preview effect:

Two words at the end Blackened

Two words at the end *Italicized

对应 HTML：

<p>
  Two words at the end.
  <strong>darken</strong>
</p>
<p>
  Two words at the end.
  <em>italicized font</em>
</p>

quotation block

Markdown：

> blockquote一。
>
> blockquote二。
>> Inline quote block paragraph一。
>
> ### Title within the quote block

Preview effect:

Quote block paragraph one.

Quote block paragraph two.

Inline quote block paragraph one.

Inline quote block title

** Corresponds to HTML:**

<blockquote>
  <p>Quote block paragraph one. </p>
  <p>Quote block paragraph two. </p>
  <blockquote>
    <p>Inline quote block paragraph one. </p>
  </blockquote>
  <h3 id="Title within quote block">Title within quote block</h3>
</blockquote>
``

### Hyperlinks

Markdown supports both in-line and in-quote links.

**Markdown:**

``##
Inline [Blog](https://zhenyu0519.github.io "My Personal Blog") link with title.

Inline [GitHub](https://github.com/zhenyu0519) link.
Quoted [Blog][1] link.
Quoted [GitHub][2] link with title.

[1]: https://zhenyu0519.github.io
[2]: https://github.com/zhenyu0519 "我的 GitHub 主页"

Preview effect：

Inside the Lines Blog Link with title。

in-line GitHub link。

Quoted Blog link.

Quoted GitHub link with title。

** corresponds to HTML:**

<p>in-line <a href="https://gopal-blog.github.io" title="My personal blog">blog</a> link with title。</p>

<p>in-line <a href="https://github.com/gopalmani">GitHub</a> Link。 </p>

<p>in-line <a href="https://gopal-blog.github.io">Blog</a> Link。 </p>

<p>in-line <a href="https://github.com/gopalmani" title="my GitHub Home">GitHub</a> link with the title。</p>

图片

在超链接的写法前加一个 ! ，就是引用图片的方法。

Markdown：

! [Alt text](https://zhenyu0519.github.io/favicon.ico "favicon")

预览效果：

! Alt text

对应 HTML：

<img src="https://zhenyu0519.github.io/favicon.ico" alt="Alt text" title="favicon">

列表

包括有序列表和无序列表。

Markdown：

- 苹果
- 葡萄
- 榴莲

1. 苹果
2. 葡萄
3. 榴莲

预览效果：

  • 苹果
  • 葡萄
  • 榴莲
  1. 苹果
  2. 葡萄
  3. 榴莲

对应 HTML：

<ul>
  <li>苹果</li>
  <li>葡萄</li>
	@@ -334,38 +287,30 @@ Quoted [GitHub][2] link with title。
  <li>葡萄</li>
  <li>榴莲</li>
</ol>

其中无序列表的标记可以使用 +、- 或 *，有序列表前的数字可以是乱序的。

代码块

支持行内代码和代码块。

Translated with DeepL.com (free version)

Markdown：

Given an array of integers, return indices of the two numbers such that they add up to a specific target.
You may assume that each input would have exactly one solution, and you may not use the same element twice.

``` python
def twoSum(self, nums: 'List[int]', target: 'int') -> 'List[int]':
    dict = {}
    for i, v in enumerate(nums):
        another = target - v
        if another not in dict:
            dict[v] = [another, i]
        else:
            return [dict[another][1],i]
```

预览效果：

Given an array of integers, return indices of the two numbers such that they add up to a specific target. You may assume that each input would have exactly one solution, and you may not use the same element twice.

def twoSum(self, nums: 'List[int]', target: 'int') -> 'List[int]':
        dict = {}
        for i, v in enumerate(nums):
	@@ -374,73 +319,51 @@ def twoSum(self, nums: 'List[int]', target: 'int') -> 'List[int]':
                dict[v] = [another, i]
            else:
                return [dict[another][1],i]

上例中的语言标记 python 可选填，可用于在编辑器和渲染后的效果里添加语法高亮。

块式代码也可以对整个代码段缩进四个空格，或一个 Tab 来实现。

水平分割线

使用一个单独行里的三个或以上 *、- 来生产一条水平分割线，它们之间可以有空格。

Markdown：

***
-----
- - -

预览效果：

对应 HTML：

<hr />

<hr />

<hr />

嵌入 HTML

Markdown 标记语言的目的不是替代 HTML，也不是发明一种更便捷的插入 HTML 标签的方式。它对应的只是 HTML 标签的一个很小的子集。

对于那些没有办法用 Markdown 语法来对应的 HTML 标签，直接使用 HTML 来写就好了。

扩展语法

本节的内容是介绍一些受到广泛支持的 Markdown 扩展语法。

表格

Markdown：

| 编号  | 姓名（左） | 年龄（右） | 性别（中） |
| ----- | :--------  | ---------: | :------:   |
| 0     | 张三       | 28         | 男         |
| 1     | 李四       | 29         | 男         |

预览效果：

编号 姓名（左） 年龄（右） 性别（中）
0 张三 28 男
1 李四 29 男

对应 HTML：

<table>
  <thead>
    <tr>
	@@ -465,106 +388,74 @@ Markdown 标记语言的目的不是替代 HTML，也不是发明一种更便捷
    </tr>
  </tbody>
</table>

任务列表

在 GitHub / GitLab 里有较好的支持。

Markdown：

- [x] 洗碗
- [ ] 清洗油烟机
- [ ] 拖地

预览效果：

  • 洗碗
  • 清洗油烟机
  • 拖地

对应 HTML：

<ul class="contains-task-list">
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox" checked=""> 洗碗</li>
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox"> 清洗油烟机</li>
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox"> 拖地</li>
</ul>

Delete line

Markdown:

`` Type the last three words strikethrough.

**Preview effect:**

The next three words are typed ~~strikethrough~~.

**Corresponding HTML:**
```html.
<p>The next three words are typed with <del>strikethrough</del>. </p>

The autolink extension, i.e.: automatically generates a tags for URLs, or URLs included with <, >, when they are recognized. Markdown：

https://github.com

<example@gmail.com>

预览效果：

https://github.com

example@gmail.com

对应 HTML：

<p><a href="https://github.com">https://github.com</a></p>

<p><a href="mailto:example@gmail.com">example@gmail.com</a></p>

emoji

以 GitHub Pages 为例。

Markdown：

:camel: :blush: :smile:

预览效果：

:camel: :blush: :smile:

对应 HTML：

<p>
  <img class="emoji" title=":camel:" alt=":camel:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f42b.png" height="20" width="20">
  <img class="emoji" title=":blush:" alt=":blush:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f60a.png" height="20" width="20">
  <img class="emoji" title=":smile:" alt=":smile:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f604.png" height="20" width="20">
</p>

参考

Search

    Table of Contents