Obs082｜Learn Markdown with Obsidian

Version: v1.0 2022/04/04
　　 v1.1 2022/10/22

Source: 簡睿隨筆
Tutorial Video: 簡睿學堂 Best enjoyed together 😄
PDF Download: Google Drive

1. What is Markdown?

1. Markdown is a lightweight markup language. Compared to the complex and extensive HTML, Markdown is simpler and easier to use.
2. It adds formatting markup to plain text content, enabling the text to be converted into HTML.
3. Markdown provides an easy-to-read and easy-to-write markup format.
4. Invented by John Gruber in 2004.
5. As technology has progressed, several versions of Markdown have emerged.

2. Why learn Markdown?

• Markdown has a wide range of applications: Used in websites, presentations, notes, documents, books, emails, and instant messaging software.
• Markdown is highly portable.
• Markdown is platform-independent.

2.1. Some Applications of Markdown

Too many to list exhaustively; here are a few examples.

• Online Markdown Editors: StackEdit, HackMD
• Static Site Generators: Hugo, MkDocs, VuePress
• Browser Extensions:
  • Email Formatting Conversion: Markdown Here
  • Download Websites as Markdown: MarkDownload
• Windows Markdown Editors: Markdown Monster, ghostwriter
• macOS Markdown Editors: iA Writer, MacDown, Bear, Craft, Drafts
• Linux Markdown Editors: ghostwriter, ReText
• Cross-platform Markdown Editors: Typora
• iOS / Android Markdown Editors: iA Writer, Drafts

3. Markdown Processing Steps

4. Covered Syntax

4.1. Block Elements

4.2. Inline Elements

5. Heading

5.1. Alternative Headings

5.2. Paragraph

Separate paragraphs with a blank line.

6. Line break

The 'Strict line breaks' setting affects line break behavior.

7. Emphasis

7.1. Italic

Text surrounded by one asterisk (*), one underscore (_), or $ (non-Markdown) becomes italic.

7.2. Bold

Text surrounded by two asterisks (**) or two underscores (__) becomes bold.

7.3. Bold Italic

Text surrounded by three asterisks (***) or three underscores (___) becomes bold italic. Combinations like __* or **_ might also work, but are not recommended.

7.4. Strikethrough

Text surrounded by two tildes (~~) becomes strikethrough.

Text surrounded by two tildes (`~~`) becomes ~~strikethrough~~.

7.5. Highlight

Text surrounded by two equal signs (==) becomes highlighted.

The best way to learn Obsidian is to ==start writing==, ==write seriously==; themes and plugins are just aids.

7.6. Underline

Non-Markdown: Markdown does not have native underline syntax. You can use the HTML tags <u> and </u> to create underlined text.

Don't spend too much energy on Obsidian plugins; <u>the notes themselves</u> are the most important thing.

7.7. Overline / Emphasis Marks

Non-Markdown: Use HTML tags like <ruby> or CSS styles.

<ruby style="ruby-position: under">漢字<rt>ㄏㄢˋ ㄗˋ</rt></ruby>
 <ruby style="ruby-position:under">電腦<rt>dian nao</ruby>
 <span style="-webkit-text-emphasis: filled red">Important content!</span>
 <span style="border-top: 1px solid red">Important content!</span>

7.8. Superscript and Subscript

Non-Markdown: Obsidian does not directly support superscript and subscript syntax. There are two ways to achieve this.

7.8.1. Method 1: MathJax

Use MathJax (JavaScript display engine for LaTeX, MathML, and AsciiMath notation) syntax (this document uses the Quick Latex for Obsidian plugin).

* $E=MC^2$
* $CO_2$

• $E=MC^2$
• $CO_2$

7.8.2. Method 2: Using HTML tags

* E=MC<sup>2</sup>
* CO<sub>2</sub>

• E=MC²
• CO₂

7.9. Inline Code

`Inline code` (text surrounded by single backticks) can also change the text's appearance and can be used when needed.

8. Blockquotes

1. Start each line with > (greater-than sign followed by a space) to create a blockquote.
2. Start each line with >> (two greater-than signs followed by a space) to create a nested blockquote.
3. Some Markdown syntax can be used within blockquotes; the specific supported syntax depends on the application's implementation.

> 111
>> 222 **Bold**
>>> AAA *Italic*
>>> BBB ***Bold Italic***
>> 333
> 444

111

222 Bold

AAA Italic
BBB Bold Italic
333
444

9. Lists

9.1. Ordered Lists

1. Start with number. (number, period, space) or number) .
2. The numbers do not need to be sequential.
3. The list will start with the number of the first item and increment sequentially.
4. If list items are separated by blank lines, they will be rendered with paragraph spacing. A blank line followed by non-list content ends the list; a subsequent ordered list will restart numbering.
5. Automatic renumbering: Press <span class="keybs">Tab</span> then <span class="keybs">Shift+Tab</span>.
6. Indent with four spaces or a <span class="keybs">Tab</span> to create a nested list.

9.2. Unordered Lists

1. Start with * , - , or + (asterisk, hyphen, or plus sign followed by a space).
2. If list items are separated by blank lines, they will be rendered with paragraph spacing.
3. Indent with four spaces or a <span class="keybs">Tab</span> to create a nested list.
4. If a list item starts with number. (e.g., 1. ), it might be misinterpreted; escape the period with a backslash (1\. ).

10. Code

10.1. Inline Code

1. Surround the code with single `backticks`.
2. Use double backticks ( ` ) to include literal backticks within an inline code span.

10.2. Code Blocks

1. Start the block with three backticks (```) and end it with a line of three backticks.
2. Three tildes (~~~) can also be used instead of backticks.
3. Alternatively, indent each line of the code block with at least four spaces or one <span class="keybs">Tab</span>.

```
<kbd>Ctrl+Enter</kbd>
```

10.3. Syntax Highlighting

Specify the programming language after the opening triple backticks for syntax highlighting.

```html
<kbd>Ctrl+Enter</kbd>
```

11. Horizontal Rule

Three or more asterisks, hyphens, or underscores on a line by themselves.

---

12. Links

The title text is optional.

💡 Mnemonic Tip

'Square brackets first, parentheses second'

13. Images

14. Tables

14.1. Table with Alignment

| Header 1 | Header 2 | Header 3 |
|:---------|:--------:|---------:|
| 111      | 222      | 333      |
| 444      | 555      | 666      |

14.2. Simple Table

Header 1 | Header 2 | Header 3
---|---|---
111 | 222 | 333
444 | 555 | 666

15. Block Reference ID

Insert ^blockID at the end of a block (like a paragraph) to allow internal links to reference it.

16. Footnotes

1. [^footnoteID]: Marks the footnote reference point; automatically rendered as sequential numbers.
2. [^footnoteID]: Footnote description text: Defines the footnote content.

The Markdown markup language¹ was invented by John Gruber.

The author of Dream of the Red Chamber is Cao Xueqin², and the novel is also known as The Story of the Stone³

17. Task Lists

After typing the task description, press <span class="keybs">Ctrl+Enter</span> (in some editors) to quickly format it as a task list item. The starting character can be -, +, or *.

18. Comments

Content that is not rendered in the output is a comment.

19. Embedding Webpages

<iframe src="URL"></iframe>

20. Third-party Integrations

20.1. Mermaid: Flowcharts, etc.

Core support (in Obsidian).

• Online FlowChart & Diagrams Editor - Mermaid Live Editor

```mermaid
sequenceDiagram
    Alice->>+John: Hello John, how are you?
    Alice->>+John: John, can you hear me?
    John-->>-Alice: Hi Alice, I can hear you!
    John-->>-Alice: I feel great!
```

sequenceDiagram
    Alice->>+John: Hello John, how are you?
    Alice->>+John: John, can you hear me?
    John-->>-Alice: Hi Alice, I can hear you!
    John-->>-Alice: I feel great!

```mermaid
pie title This Week's Pomodoros
	"Monday": 5
	"Tuesday": 11
	"Wednesday": 12
	"Thursday": 22
	"Friday": 10
	"Saturday": 7
	"Sunday": 6
```

pie title This Week's Pomodoros
	"Monday": 5
	"Tuesday": 11
	"Wednesday": 12
	"Thursday": 22
	"Friday": 10
	"Saturday": 7
	"Sunday": 6

20.2. Excalidraw

20.3. Diagrams

20.4. Emoji

21. YAML Front Matter

Default Keywords:

21.1. tags

• Cannot contain spaces.
• Can use underscores (_) or hyphens (-) as separators.
• Cannot be entirely numeric: #3c is usable, but #2022 is not (as a tag, though tag: 2022 might be valid YAML).
• Can use forward slashes (/) to create nested tags: tech/software

tags: test1, test2, test3/test3-1

tags: [ test1, test2, test3/test3-1 ]

tags:
  - test1
  - test2
  - test3/test3-1

tags:
  - test1 test2 test3/test3-1 # This might be interpreted differently depending on parser

21.2. aliases

Aliases for the note's filename, allowing a note to have multiple names or ways to link to it.

---
aliases: [MarkdownUsage, MarkdownSyntaxSummary]
---

21.3. cssClasses

Both cssClass or cssClasses can be used. Applies specific CSS classes to this note for custom styling.

21.4. publish

publish: true publishes the note to Obsidian Publish, publish: false prevents publishing.

22. Related Links

💡 解說文章(繁體中文): https://jdev.tw/blog/7066/
💡 Explanation article(English): https://quaily.com/jdevtw-en/p/obs-use-obsidian-learn-markdown
💡 解説記事(日本語): https://quaily.com/jdevtw-jp/p/obs-use-obsidian-learn-markdown

• Markdown Syntax Description (markdown.tw)
• Tutorial - MarkDown (markdown.cn)
• Format your notes - Obsidian Help

23. Tutorial Videos

▼ YouTube

▼ Bilibili