Markdown Note

Learning material (zhCN)#

I wrote this on 2021-10-09
Copy it to a markdown renderer to see formatted version.

# Markdown 学习资料

## 目录

自动生成目录：
[TOC]

本地插件生成目录：

- [Markdown 简介](#markdown-简介)
- [基础技巧](#基础技巧)
  - [基本概念](#基本概念)
  - [换行](#换行)
  - [转义字符](#转义字符)
- [排版技巧](#排版技巧)
  - [标题](#标题)
  - [列表](#列表)
  - [强调字体](#强调字体)
  - [分割线](#分割线)

## Markdown 简介

> Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档，然后转换成格式丰富的 HTML 页面。

—— [维基百科](https://zh.wikipedia.org/wiki/Markdown)

## 基础技巧

### 基本概念

- 非“所见即所得”
- 有**源代码**（markdown 语言）和**输出文档**。
  理解成编程，字符串不用双引号引用。
- 编译：**源代码**转换为**输出文档**的过程

### 换行

- 列表，标题等会自动换行
- 要在正文中换行，源代码中的“双空格+回车”会渲染为换行符。
- 源代码中的换行符（回车）不会渲染为换行符号。

### 转义字符

- 为了打出来\*和\_等字符，源代码中需要输入`\*`和`\_`等。

## 排版技巧

### 标题

- 共有六个等级（对应 HTML 语言的`h1`到`h6`）
- 语法

  markdown

  # 一级标题

  ## 二级标题

- 井号`#`后面要加空格

### 列表

- 无序序列表
  - 语法：行首加`- `（横杠和空格），横杠`-`处也可用加号`+`和型号`*`，但是不推荐。
    - 这是一个列表嵌套的例子
- 有序列表
  - 语法：行首加`1. `（数字，小数点和空格）。
    1. 有序列表嵌套的例子
- 列表嵌套通过缩进实现

### 强调字体

- _斜体_：语法：在文字的两端输入\*或\_，可以使文字变成斜体
- **加粗**： 在文字的两端输入\*\*或\_\_，可以使文字变成粗体

### 分割线

- 语法： 独占一行的 `---`（或者`***`，不推荐）
  这是一个分割线

---

## 格式

没写完：链接，表格

## 内部链接，（暂时作为搜索标记使用）

[[Markdown学习]]

## 参考文档

1. https://zhuanlan.zhihu.com/p/55816380
2. https://maxiang.io/
3. https://www.jianshu.com/p/774f70629770

GitHub flavor markdown#

This is used in GitHub Wiki

Additional syntax rules#

@2021-09-20
Cannot embed video. Best work-around so far I'v seen is to add a video screen shot with hyperlink referring to the video address.
Had to use <code/>tag to quote `(backtick character), GH Doesn't support ` nor \
```
 nor \ tag in internal link [[]]
```


Cannot import an MD to another. Best work-around: link wiki page of same repo: ../../wiki reason here: github/markup#346 and github/markup#172.


GitHub flavor markdown Links#

@2021-10-03
Internal link like [[]] support syntax [[shown|title#chapter]] name with -(dash),  (space). Omit the space is not working, only in chapter it won't resolve the link, in title it will report an error with red font color and direct to create a new page.
Examples:

1
2
3
4
5
6
7
8
9 [[MarkdownNote#GitHub flavor markdown Links]]   This doesn't work
[[MarkdownNote#GitHub-flavor-markdown-Links]]   This doesn't work
[[MarkdownNote#GitHubflavormarkdownLinks]]      This doesn't work
[[Markdown Note#GitHub flavor markdown Links]]  This works
[[Markdown Note#GitHub-flavor-markdown-Links]]  This works
[[Markdown Note#GitHubflavormarkdownLinks]]     This doesn't work
[[Markdown Note#GitHub flavor markdown Links]]  This works
[[Markdown Note#GitHub-flavor-markdown-Links]]  This works
[[Markdown Note#GitHubflavormarkdownLinks]]     This doesn't work


GH Wiki Local Env#

@2021-10-29



How to: Pull from the URL on the right side then do the normal git things
bash
git init
git remote add origin https://github.com/Pablion/Pablion.wiki.git
git pull origin master



Use it like a normal repo.


[ ] #TODO Any tool for the local env? I found no extension that supports the Link syntax [[shown|title#chapter]].

Obsidian flavor markdown#
Links in Obsidian#

@2021-12-14
Internal link like [[link|shown]] is reverse to GitHub Flavor [[shown|link]]
Easy fix with regex substitution/\[\[(.+)\|(.+)\]\]/g => [[$2|$1]]

Markdown specifications#

@2021-01-26
There are two most popular Markdown specifications mentioned in the discussion of mkdocs/mkdocs#2761. And they are used on different projects.




CommonMark spec
original Markdown spec




GitHub
Python-markdown


Prettier VSCode extension
mkdocs



Render Pipe character in table#

@2021-01-26
Use this way to render a pipe char | in code tag table.

1
2
3 | test              | test |
| ----------------- | ---- |
| <code> \| </code> | a    |


General#
Footnote with link#
Front matter#

First thing in the file
must take the form of valid YAML set (between triple-dashed lines).
For example and extra reading: Front matter - jekyllrb