Markdown Learning Guide

Introduction

Markdown is a lightweight markup language that allows you to write documents using an easy-to-read and easy-to-write plain text format, which can then be converted to structurally valid HTML. Its design philosophy is "easy to read, easy to write." Markdown is widely used in documentation, blog posts, README files, forum posts, and more.

Basic Syntax

Headings

Markdown supports six levels of headings by adding different numbers of # symbols before the heading text. The number of # symbols corresponds to the heading level.

Best Practice: For compatibility, always add a space after the # symbols, and leave blank lines before and after headings.

Paragraphs

To create paragraphs, simply separate lines or blocks of text with a blank line. Markdown treats each text block separated by blank lines as a paragraph.

Example:

This is a paragraph.

This is another paragraph.

Best Practice: Unless the paragraph is in a list, don't indent paragraphs with spaces or tabs.

Line Breaks

To create a line break (<br>) within a paragraph, add two or more spaces at the end of the line, then press Enter.

Example:

This is the first line.
This is the second line.

Best Practice: For better compatibility across different Markdown applications, use trailing spaces or the <br> HTML tag to create line breaks.

Emphasis

You can use asterisks (*) or underscores (_) to emphasize text, making it bold or italic.

Best Practice: For better compatibility when emphasizing text in the middle of a word, use asterisks (*) instead of underscores (_).

Blockquotes

Create blockquotes by adding a > symbol before paragraphs.

Example:

> This is a blockquote.
> Blockquotes can span multiple lines.

HTML Output:

Lists

Markdown supports both ordered and unordered lists.

Unordered Lists

Use asterisks (*), plus signs (+), or hyphens (-) as list item markers.

Example:

* List item one
* List item two
  * Nested list item

HTML Output:

• List item one
• List item two
  • Nested list item

Ordered Lists

Use numbers followed by a period (.) to create ordered lists.

Example:

1. First item
2. Second item
   1. Nested ordered item

HTML Output:

1. First item
2. Second item
   1. Nested ordered item

Code

Inline Code

Wrap code snippets with backticks (`) to create inline code.

Example:

This is an example of `console.log("Hello World!");`.

Code Blocks

Wrap multiple lines of code with three backticks (```), and optionally specify the language after the first backticks for syntax highlighting.

Example:

```python
def hello_world():
    print("Hello, Markdown!")
```

HTML Output:

def hello_world():
    print("Hello, Markdown!")

Horizontal Rules

Use three or more asterisks (***), hyphens (---), or underscores (___) to create horizontal rules.

Example:

---

***

___

HTML Output:

Links

Inline Links

Use [link text](URL) format to create inline links.

Example:

Visit [Markdown Guide](https://www.markdownguide.org/) to learn more.

HTML Output:

Visit Markdown Guide to learn more.

Reference-style Links

Use [link text][reference], then define [reference]: URL anywhere in the document.

Example:

Visit [Google][1] or [GitHub][github_link].

[1]: https://www.google.com
[github_link]: https://www.github.com

Images

Image syntax is similar to links, but with an exclamation mark (!) at the beginning.

Example:

![Alt text](image-url "Optional title")

![Markdown Logo](https://www.markdownguide.org/assets/images/markdown-guide-logo.svg "Markdown Logo")

Tables

Use hyphens (-) to create header separators and pipes (|) to separate columns. Add colons (:) in the header separator to set alignment.

Example:

| Header 1 | Header 2 | Header 3 |
| :------- | :------: | -------: |
| Left     | Center   | Right    |
| Cell A   | Cell B   | Cell C   |

HTML Output:

Best Practice: For better readability, add pipes at the beginning and end of each row.

Extended Syntax (GitHub Flavored Markdown)

Many Markdown processors support extended syntax, with GitHub Flavored Markdown (GFM) being one of the most commonly used. GFM adds many useful features to the basic syntax.

Strikethrough

Use two tildes (~~) to wrap text for strikethrough.

Example:

~~This text is deleted~~.

HTML Output:

This text is deleted.

Task Lists

Use - [ ] or - [x] to create task lists.

Example:

- [x] Complete task one
- [ ] Complete task two
- [ ] Complete task three

HTML Output:

• Complete task one
• Complete task two
• Complete task three

Automatic URL Linking

GFM automatically converts URLs to links.

Example:

Visit https://www.example.com.

HTML Output:

Visit https://www.example.com.

Emoji

GFM supports inserting emoji using :<emoji_name>: syntax.

Example:

:smile: :+1: :sparkles:

HTML Output:

😄 👍 ✨

Markdown Best Practices

1. Maintain Consistency: Keep your Markdown syntax style consistent throughout the document. For example, choose whether to use * or _ for italics and stick with it.
2. Use Blank Lines: Use blank lines between block-level elements (headings, paragraphs, lists, code blocks) to improve readability.
3. Avoid Excessive HTML: While Markdown supports embedded HTML, try to use Markdown syntax to maintain document simplicity and portability.
4. Preview Documents: Always use a Markdown preview tool to check the rendering before publishing to ensure it meets expectations.
5. Add Alt Text to Images: Provide meaningful alt text for images, which is important for both accessibility and SEO.
6. Use Meaningful File Names: Choose clear, descriptive file names for Markdown documents.

Popular Markdown Editors and Tools

• Visual Studio Code: Powerful code editor with built-in Markdown preview and rich Markdown extensions.
• Typora: A WYSIWYG Markdown editor offering a smooth writing experience.
• Obsidian / Notion / Joplin: Note-taking apps with extensive Markdown support and knowledge management features.
• Dillinger.io / StackEdit.io: Online Markdown editors with real-time preview and multiple export formats.

Summary

Markdown is a simple yet powerful writing tool. Mastering its basic syntax and best practices can significantly improve the efficiency and quality of document writing. We hope this guide helps you get started quickly and become proficient in using Markdown.

How MD2Anki Can Help

With MD2Anki, you can easily convert your Markdown learning notes into Anki flashcards! Simply:

1. Write your notes in Markdown format
2. Upload your .md file to MD2Anki
3. Download the generated .apkg file
4. Import into Anki and start learning!

This makes it perfect for creating flashcards from technical documentation, study guides, or any structured content written in Markdown.

References

1. Markdown Guide - Basic Syntax
2. Markdown Guide - Extended Syntax