What Is Markdown?
Markdown is a lightweight markup language created by John Gruber in 2004 as a way to write formatted text using a plain-text editor. Instead of relying on complex HTML tags or WYSIWYG editors, Markdown uses simple, intuitive punctuation marks to indicate formatting — asterisks for bold, hash symbols for headings, square brackets for links, and so on. The result is a writing experience that is fast, portable, and readable even in its raw form.
Today, Markdown is the de facto standard for writing documentation, README files, blog posts, technical articles, comments on GitHub and GitLab, chat messages in Slack and Discord, and much more. Its simplicity and human-readability have made it one of the most widely adopted lightweight markup languages in the world. You can preview your Markdown in real time using our Markdown Preview tool, which renders your text as you type.
Basic Syntax
Headings
Headings in Markdown are created using hash symbols (#) at the beginning of a line. One hash creates an H1 heading (the largest), two hashes create an H2, three create an H3, and so on up to H6. For example,## My Section creates a second-level heading. It is recommended to add a space between the hashes and the heading text for compatibility with all parsers. Many Markdown authors also place a heading at the top of each document using a single hash, which serves as the page title.
Bold and Italic Text
To create bold text, wrap the text with two asterisks or two underscores on each side: **bold text** or __bold text__. For italic text, use a single asterisk or underscore on each side: *italic text* or _italic text_. You can combine both for bold italic text using three asterisks: ***bold and italic***. The asterisk syntax is more universally supported and is generally preferred over underscores, since underscores can sometimes conflict with text containing variable names in programming contexts.
Links and Images
Links are created using square brackets for the link text followed by parentheses for the URL: [Calcify](https://calcify.dev). You can also add a title attribute that appears on hover by placing it in quotes inside the parentheses: [Calcify](https://calcify.dev "Developer Tools"). For images, prepend an exclamation mark before the link syntax: . The alt text is important for accessibility and is displayed when the image fails to load.
Lists
Unordered Lists
Unordered lists are created by starting each line with a hyphen (-), asterisk (*), or plus sign (+), followed by a space. All three characters produce the same result in most parsers. For example: - First item, - Second item, - Third item. You can create nested lists by indenting items with two or four spaces (depending on the parser). Mixing and matching list markers within the same list is allowed but generally discouraged for consistency.
Ordered Lists
Ordered lists use numbers followed by a period: 1. First item, 2. Second item, 3. Third item. An interesting property of Markdown ordered lists is that the actual numbers you type do not need to be sequential — the renderer will number them correctly regardless. Many writers use1.for every item to make reordering easier, since the numbers in the source don't affect the output. Nested ordered lists are created by indenting with spaces, and you can nest ordered lists inside unordered lists and vice versa.
Task Lists
Task lists (also called checkbox lists) are a GitHub-Flavored Markdown extension that adds interactive checkboxes to list items. They are created using square brackets: - [x] Completed task for a checked item and - [ ] Pending task for an unchecked item. Task lists are widely used in GitHub Issues, Pull Requests, and project management documents. While not part of the original Markdown specification, they are supported by most modern Markdown renderers including GitHub, GitLab, and many documentation tools.
Code Blocks and Inline Code
Inline code is created by wrapping text with single backticks: `code here`. This is typically rendered in a monospaced font and is used for referencing variable names, function names, short commands, or any technical term that should stand out from the surrounding prose. If the inline code itself contains backticks, you can use double backticks as delimiters: ``code with `backticks` inside``.
For multi-line code blocks, use triple backticks (```) on their own line before and after the code. You can specify a language identifier after the opening backticks to enable syntax highlighting: ```javascript, ```python, ```bash, and so on. Syntax highlighting makes code blocks significantly easier to read by color-coding keywords, strings, comments, and other language elements. Most modern Markdown renderers support dozens of languages for syntax highlighting.
Blockquotes
Blockquotes are created by prefixing each line with a greater-than sign ('>): > This is a blockquote.. They are rendered as visually distinct quoted sections, typically with a left border or different background color. Blockquotes can contain other Markdown elements, including headings, lists, code blocks, and even nested blockquotes (by adding additional greater-than signs). They are commonly used for attributing quotes, highlighting important callouts, or creating visually distinct note sections in documentation.
Tables
Tables are created using pipes (|) and hyphens to separate columns and define the header row. The second row must contain hyphens separated by pipes to separate the header from the body. Colons in the separator row control text alignment: a colon on the left (:---) left-aligns, a colon on both sides (---:) right-aligns, and colons on both sides (:-:) center-aligns. For example, a basic table looks like: | Column 1 | Column 2 | followed by |---------|---------| and then the data rows.
Tables are part of the GitHub-Flavored Markdown (GFM) specification and are not supported in all Markdown parsers. While tables work well for small to medium datasets, they become difficult to read and maintain in plain text for very wide tables with many columns. In such cases, consider using alternative formats like lists or HTML tables for better readability in the source document.
GitHub-Flavored Markdown (GFM) Extensions
GitHub-Flavored Markdown extends the original Markdown specification with several additional features that have become widely adopted beyond GitHub itself. GFM adds support for tables, task lists, strikethrough text (using double tildes: ~~strikethrough~~), automatic linking of URLs without explicit markup, and emoji shortcodes (e.g., :smile:). These extensions are supported by most modern Markdown renderers, including GitLab, Notion, Obsidian, and many static site generators.
Another useful GFM feature is the ability to create alerts or admonitions using special blockquote syntax. For example, > [!NOTE] creates a styled callout box for notes, > [!WARNING] creates a warning callout, and > [!TIP] creates a tip callout. These are particularly valuable in documentation for drawing attention to important information, warnings, or actionable advice without cluttering the main content flow.
Converting Between Markdown and HTML
Markdown was designed to be a superset of HTML in many respects. You can include raw HTML tags directly in your Markdown document, and most renderers will pass them through unchanged. This is useful for elements that Markdown does not natively support, such as embedded videos, custom-styled divs, or complex layouts. However, the reverse is not always straightforward — converting HTML to Markdown requires a parser that can infer the correct Markdown syntax from the HTML structure.
For converting Markdown to HTML in JavaScript, libraries like marked, markdown-it, and remarkable are popular choices. In Python, the markdown library is the standard option. For converting HTML to Markdown, tools like turndown (JavaScript) and html2text (Python) handle the reverse transformation. When building content management systems or documentation sites, it is common to store content as Markdown and render it as HTML on the fly or at build time.
Key Takeaways
- Markdown is a lightweight, plain-text markup language that uses simple punctuation to indicate formatting, making it fast and portable.
- Core syntax includes headings (#), bold (**), italic (*), links ([]()), and images (![]()).
- Lists, code blocks, blockquotes, and tables cover the majority of formatting needs for technical writing.
- GitHub-Flavored Markdown extends the standard with tables, task lists, strikethrough, and alerts.
- Markdown is supported by virtually every developer tool and platform, including GitHub, GitLab, Notion, and static site generators.
- Use a Markdown Preview tool to see your formatted output as you write.
Frequently Asked Questions
What is the difference between Markdown and HTML?
Markdown is a simplified, human-readable way to write formatted content that is later converted to HTML for display. While HTML uses explicit tags like <h1> and <strong>, Markdown uses intuitive symbols like # and **. Markdown is meant to be written and read as plain text, while HTML is a markup language designed for web browsers. You can embed raw HTML inside Markdown, and most Markdown is eventually converted to HTML for web rendering.
Can I use Markdown in my code editor?
Yes. Most modern code editors including VS Code, Sublime Text, Atom, and JetBrains IDEs have built-in or plugin-based Markdown support with features like syntax highlighting, live preview, keyboard shortcuts for formatting, and export options. VS Code in particular has excellent out-of-the-box Markdown support with a built-in preview pane, table of contents generation, and extension support for advanced features like Mermaid diagrams and math equations.
How do I add line breaks in Markdown?
In standard Markdown, a single newline in the source text does not create a line break in the rendered output. To create a line break, end the line with two or more spaces followed by a newline. Alternatively, you can use the HTML <br> tag for an explicit line break. For a new paragraph, leave a blank line between blocks of text. GitHub-Flavored Markdown (GFM) also respects single newlines as line breaks in certain contexts like comments and issues.
Is Markdown the same everywhere?
No, there are several slightly different flavors of Markdown, and parsers may handle edge cases differently. The original Markdown specification by John Gruber had some ambiguities that led to divergent implementations. Common flavors include GitHub-Flavored Markdown (GFM), CommonMark (an attempt to standardize the specification), MultiMarkdown (adds footnotes, tables, and more), and PHP Markdown Extra. For maximum compatibility, stick to well-established syntax and test your documents with the specific renderer you plan to use.