Markdown Tutorial

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

Markdown was created by John Gruber in 2004.

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

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

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

Markdown's core features include:

Simplicity: Use intuitive symbols to represent formatting, such as using#to represent headings, and use*to represent list items. These symbols convey their meaning visually and remain readable even without rendering.

Readability: Even Markdown documents in plain text form can clearly show the structure and hierarchy of the document. Readers can understand the organization of the content without 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: It 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 document structure and formatting. Traditional markup languages such as HTML are powerful but have complex syntax, while lightweight markup languages simplify this process.

Compared with HTML, Markdown's advantages are:

  • Low learning cost; you can master the basic syntax in a few minutes
  • High writing efficiency; no need to enter complex tags
  • Focus on content rather than formatting details
  • Version control friendly, easy for 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 can be understood as follows:

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

For example, when you write:

# This is a title

It will be converted to:

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

Importantly, you can directly use HTML tags in Markdown, which provides flexibility for complex formatting. When the basic Markdown 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 barrier: Compared with markup languages like LaTeX and HTML, Markdown's syntax is extremely simple; most people can grasp the basic usage within an hour.

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

Version control friendly: Since it is 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 remain accessible and editable as plain text, ensuring long-term usability of content.

Application Scenarios of Markdown

Writing Technical Documentation

In the field of software development, Markdown has become the standard format for technical documentation. It is particularly 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 descriptions: From installation guides to user manuals, Markdown can effectively organize technical information. Code examples, configuration files, and command-line operations can all be displayed appropriately.

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

Creating Blog Posts

Most modern blog platforms and static site generators support Markdown:

  • Content management: Bloggers can focus on content creation without worrying about complex HTML coding. Formatting of articles can be 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, improving writing flexibility.

GitHub README Files

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

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

  • Installation guide: Provide detailed installation and configuration steps through code blocks and lists.

  • Contribution guide: Explain 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 minutes: Clear heading structure and list format make meeting key points clear at a glance.

  • Knowledge base building: Both businesses 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, natively supporting Markdown, provide powerful organization and collaboration features.

  • Static blog generators: Tools like Jekyll, Hugo, Hexo, etc., allow users to create professional websites using Markdown.

Useful Books

The Amazing Markdown:

Other Extensions