Markdown Guide: Writing, Previewing, and Converting

What Is Markdown and Why Does It Matter?

Markdown is a lightweight markup language created by John Gruber in 2004. Its purpose is simple: let people write formatted text using plain text syntax that remains readable even without rendering. Unlike HTML or rich text editors, Markdown files are just text files. You can open them in any editor, on any operating system, and they will always be readable.

Markdown has become the de facto standard for technical writing. GitHub uses it for README files and documentation. Static site generators like Hugo, Jekyll, and Astro use it for content. Note-taking apps like Obsidian, Notion, and Bear support it natively. If you write documentation, blog posts, or technical notes, Markdown is a skill that pays off immediately.

The appeal is productivity. You never take your hands off the keyboard. There is no toolbar to click, no formatting menu to navigate. Once you learn the syntax, you can write structured documents faster than in any word processor. And because Markdown files are plain text, they work perfectly with version control systems like Git.

Basic Syntax: Headers, Lists, Links, and Images

Markdown syntax maps to HTML elements through simple text patterns. Headers use hash symbols: one hash for h1, two for h2, up to six for h6. For example, "## Section Title" becomes a second-level heading. Most documents use h1 for the title and h2 or h3 for sections.

Paragraphs are separated by blank lines. If you want a line break within a paragraph, end the line with two spaces or use a backslash. Bold text is wrapped in double asterisks like bold, and italic text uses single asterisks like italic. You can combine them: bold and italic.

Unordered lists use dashes, asterisks, or plus signs at the start of a line. Ordered lists use numbers followed by a period. You can nest lists by indenting with two or four spaces. Links follow the pattern [link text](URL), and images are the same with an exclamation mark in front: . Blockquotes use a greater-than symbol at the start of the line.

Horizontal rules are created with three or more dashes, asterisks, or underscores on a line by themselves. Inline code uses single backticks, like `variable`. These basics cover about 80% of what you will write in Markdown.

Extended Syntax: Tables, Code Blocks, and Task Lists

The original Markdown specification was intentionally minimal. Over time, extensions added features that are now widely supported. The most common extension is CommonMark, which standardized ambiguous parts of the original spec. GitHub Flavored Markdown (GFM) added tables, task lists, strikethrough, and autolinked URLs.

Code blocks use triple backticks (```) on their own line before and after the code. You can specify the programming language after the opening backticks to enable syntax highlighting: ```javascript, ```python, ```sql. This is essential for technical documentation because highlighted code is dramatically easier to read.

Tables use pipes and dashes to define columns and rows. The header row is separated from the body by a line of dashes. You can align columns left, right, or center by placing colons in the separator line. Building tables by hand is tedious, which is why table generator tools exist. They let you input data in a spreadsheet-like interface and output correctly formatted Markdown.

Task lists use a dash followed by square brackets: "- [ ]" for unchecked and "- [x]" for checked items. These render as interactive checkboxes on GitHub. Strikethrough text uses double tildes: ~~deleted text~~. Footnotes, definition lists, and other extensions vary by platform.

Markdown Across Platforms: GitHub, Docs, and Beyond

Each platform that supports Markdown has its own flavor with slight differences. GitHub Flavored Markdown supports task lists, tables, autolinked references to issues and pull requests, and emoji shortcodes like :rocket:. It also renders Markdown files automatically in repositories, which is why README.md files are so prominent.

Documentation platforms like GitBook, Read the Docs, and Docusaurus extend Markdown with features like admonitions (info/warning boxes), tabbed content, and embedded components. Many of these use MDX, which lets you include React components directly in Markdown files.

Note-taking apps have their own conventions. Obsidian supports wiki-style internal links with double brackets: [[page-name]]. Notion converts Markdown input on the fly but stores content in its own format. Bear and iA Writer focus on clean writing experiences with Markdown as the underlying syntax.

The key takeaway is that basic Markdown syntax works everywhere. The differences are in extensions. If you stick to headers, lists, links, code blocks, and bold/italic text, your content will render correctly on any platform.

Converting Markdown to HTML

Since Markdown was designed as an easier way to write HTML, conversion between the two is straightforward. Every Markdown element has a direct HTML equivalent: # becomes h1, ** becomes strong, - list items become ul with li elements, and so on.

There are several reasons to convert Markdown to HTML. You might be writing content in Markdown for speed but need HTML for a website that does not support Markdown natively. Email templates often need HTML. Some CMS platforms accept HTML but not Markdown. Converting also lets you inspect what HTML your Markdown produces, which is useful for debugging rendering issues.

Programmatic conversion is handled by libraries like marked, markdown-it, and remark in JavaScript, or Python-Markdown and mistune in Python. These parse the Markdown into an abstract syntax tree and then render it to HTML. Most support plugins that extend the syntax.

For quick one-off conversions, an online tool is faster than setting up a library. You paste your Markdown, see the HTML output, and copy it. This is especially handy when you need to include formatted content in an HTML email or a platform that only accepts raw HTML.

Creating Tables Efficiently

Tables are the most painful part of Markdown to write by hand. Keeping columns aligned, adding the right number of pipes, and formatting the separator row correctly takes more effort than it should. This is one area where a dedicated tool saves real time.

A Markdown table generator lets you define rows and columns visually, enter your data, and get perfectly formatted output. Some generators support importing data from CSV or TSV, which is useful when you have data in a spreadsheet. Others let you sort columns, add or remove rows and columns dynamically, and choose alignment per column.

When writing tables manually, a few tips help. Start with the header row and separator, then fill in data. Use a monospaced font in your editor so pipes align visually. Some editors like VS Code have extensions that auto-format Markdown tables when you save the file.

For very large datasets, consider whether a table is the right format. Markdown tables do not support cell merging, row spanning, or complex layouts. If your table exceeds five or six columns, it may be more readable as a structured list or a linked spreadsheet. Markdown is best for simple, concise tabular data.