Markdown Syntax Guide

What is Markdown?

Markdown is a lightweight markup language created by John Gruber. It allows people to "write documents in an easy-to-read and easy-to-write plain text format, then convert them into valid HTML documents."
https://www.markdownlang.com/

The History of Markdown

Markdown was born in 2004. In its early days, it was designed to simplify HTML syntax, mainly for writing README-type documents that are frequently read and updated, but whose content format is relatively stable.

Markdown's real popularity began after GitHub appeared in 2008. GitHub adopted Markdown as the default Readme file format and provided a rendering specification. As GitHub became popular, more and more developers started using Markdown as their preferred tool for writing.

Markdown is a lightweight markup language with a simple syntax that allows you to focus more on content rather than formatting. It uses a readable and writable plain text format, can be mixed with HTML, and can be exported to HTML, PDF, or its own .md file format.

HTML Compatibility

The goal of Markdown’s syntax is to be a writing language suitable for the web.

Markdown does not aim to replace HTML, nor even to be close to it. Its syntax is limited and only covers a small subset of HTML tags.

Tags not covered by Markdown can be written directly in the document using HTML. There’s no need to mark whether it’s HTML or Markdown; just add the tags directly.

For example, add an HTML table in a Markdown file:

This is a regular paragraph.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

This is another regular paragraph.

Automatic Special Character Conversion

In HTML files, two characters need special handling: < and &.

• < is used for opening tags
• & is used for HTML entities Markdown lets you write these characters naturally and handles the conversion for you. If the & you use is part of an HTML entity, it will be preserved; otherwise, it will be converted to &.

Markdown Best Practices

Markdown Headings

• Use only one level 1 heading (#) per document
• Keep heading levels logical; do not skip levels
• Leave blank lines before and after headings

List Formatting

Keep unordered list symbols consistent (use only -, *, or +)
No need for blank lines between list items unless there are multiple ## paragraphs

Markdown Links and Images

• Provide meaningful text descriptions for links
• Provide alt text for images

Markdown Code Display

• Use inline code for short code
• Use code blocks for long or multi-line code
• Specify the language for code blocks to enable syntax highlighting

Tool Support

Almost all Markdown applications support these basic syntax elements. There may be slight differences between different Markdown processors, but the basic syntax is universal.