Markdown Tutorial

Markdown is a lightweight markup language that allows people to write documents using a plain text format that is easy to read and write.

The Markdown language was created by John Gruber in 2004.

Markdown's design philosophy is "easy to read and write", allowing people to write structured documents using a simple plain text format.

Documents written in Markdown can be exported to multiple formats such as HTML, Word, images, PDF, and Epub.

The file extension for documents written in Markdown is.md, .markdown。

The core features of Markdown include:

Simplicity: Uses intuitive symbols to represent formatting, for example, use#for headings, and use*for list items. These symbols convey their meaning visually, and remain highly readable even without rendering.

Readability: Even Markdown documents in plain text form can clearly present the structure and hierarchy of the document. Readers can understand how the content is organized without needing specialized software.

Portability: Markdown files are plain text format and can be opened and edited in any text editor, without relying on specific software or operating systems.

Convertibility: Can be easily converted to HTML, PDF, Word documents, and other formats to meet different publishing needs.

Concept of Lightweight Markup Language

A markup language is a language that uses specific symbols to describe the structure and formatting of a document. Traditional markup languages like HTML are powerful but have complex syntax, while lightweight markup languages simplify this process.

Compared with HTML, the advantages of Markdown are:

  • Low learning cost; you can master the basic syntax in a few minutes
  • High writing efficiency; no need to input complex tags
  • Focus on content rather than formatting details
  • Version control friendly, facilitating collaboration and change tracking

Relationship Between Markdown and HTML

Markdown is not a replacement for HTML, but a simplified version of HTML. In fact, the ultimate goal of Markdown is to be converted to HTML. The relationship between the two can be understood as follows:

Markdown 源码 → 解析器 → HTML 输出 → 浏览器渲染

For example, when you write:

# This is a heading

It will be converted to:

<h1>这是一个标题</h1>

Importantly, you can directly use HTML tags in Markdown, which provides flexibility for complex formatting. When Markdown's basic syntax cannot meet your needs, you can embed HTML code to achieve specific effects.

Why Choose Markdown

Improve writing efficiency: No need to frequently use the mouse for formatting, maintaining continuity of thought. Writers can focus on content creation without being distracted by formatting issues.

Lower the learning threshold: Compared with markup languages such as LaTeX and HTML, Markdown's syntax is extremely simple; most people can master the basic usage within an hour.

Broad compatibility: Almost all modern text editors, code editors, and note-taking apps support Markdown. From simple Notepad to professional IDEs, you can find Markdown everywhere.

Version control friendly: Since it is a plain text format, Markdown files work well with version control systems such as Git, making it easy to track document revision history and collaborate with teams.

Future adaptability: Even if a particular software or platform disappears, Markdown files as plain text can still be accessed and edited, ensuring the long-term availability of content.

Application Scenarios of Markdown

Technical Documentation Writing

In the field of software development, Markdown has become the standard format for technical documentation. It is especially suitable for:

  • API Documentation: Clear heading hierarchy and code block display make API descriptions both professional and readable. Many API documentation generation tools (such as Swagger) support descriptions in Markdown format.

  • Project Description: From installation guides to user manuals, Markdown can effectively organize technical information. Code examples, configuration files, and command-line operations can all be properly displayed.

  • Development Standards: Team coding standards, design guidelines, workflows, etc. can all be written in Markdown for easy reference and updating by team members.

Blog Post Creation

Most modern blogging platforms and static site generators support Markdown:

  • Content Management: Bloggers can focus on content creation without worrying about complex HTML coding. Formatting articles is done with simple markers.

  • Platform Migration: Articles written in Markdown can be easily migrated between different platforms without being locked in by platform-specific formats.

  • Offline Writing: Articles can be written offline in any text editor and then published in batches, increasing writing flexibility.

GitHub README File

The GitHub platform widely uses Markdown, especially for project README files:

  • Project Introduction: Clearly presents key information such as the project's purpose, features, and usage.

  • Installation Guide: Provides detailed installation and configuration steps through code blocks and lists.

  • Contribution Guide: Explains how to participate in project development, including code standards, submission processes, etc.

  • Issue Tracking: In Issues and Pull Requests, developers use Markdown to describe problems and provide solutions.

Note-taking and Knowledge Management

Markdown is becoming the preferred format for digital notes:

  • Study Notes: Supports various content types such as mathematical formulas, code highlighting, and charts, suitable for technical learning and knowledge organization.

  • Meeting Notes: Clear heading structure and list format make meeting key points clear at a glance.

  • Knowledge Base Construction: Enterprises and individuals are using Markdown to build knowledge bases, organizing information through links and tags.

Online Writing Platforms

More and more writing platforms are beginning to support Markdown:

  • GitHub, Jianshu, Zhihu: The editors on these platforms support Markdown syntax, allowing creators to format articles quickly.

  • GitBook、Notion: Professional document and note platforms that natively support Markdown and provide powerful organization and collaboration features.

  • Static Blog Generators: Tools such as Jekyll, Hugo, and Hexo allow users to create professional websites with Markdown.

Useful Books

"Amazing Markdown":

Other Extensions