Markdown Preview

Markdown is a lightweight, plain-text markup language designed to convert simple human-readable text formatting into valid HTML. It was created by John Gruber and Aaron Swartz in 2004 with the primary design goal of readability — Markdown source text should be readable as-is, without appearing to be tagged with HTML or formatting instructions. Today, Markdown is one of the world's most widely used document formatting standards.

Original Markdown (John Gruber's 2004 specification) left many edge cases and ambiguous syntax rules unresolved. CommonMark is a 2014 standardization effort by John MacFarlane that created an unambiguous, mathematically precise specification resolving all edge cases. GitHub Flavored Markdown (GFM) is a CommonMark superset used by GitHub, GitLab, and many developer platforms, adding extra features: tables, task lists (checkboxes), strikethrough (~~text~~), autolinked URLs, and fenced code blocks with syntax highlighting.

Markdown headings use the hash/pound symbol (#) at the beginning of a line. One # produces an H1 heading (primary heading), ## produces H2, ### produces H3, up to ###### for H6. An alternative ATX-style uses underline syntax: text followed by === on the next line for H1, or --- for H2. Best practice is to include a space between the # symbol and the heading text (# My Heading), and to follow correct heading hierarchy for accessibility.

Markdown tables use the pipe | character as column separators and dashes --- as the header row divider. Example: | Name | Age | City | / |------|-----|------| / | Alice | 30 | London |. Each row starts and ends with a pipe character. Column alignment can be controlled with colons: |:---| for left, |:---:| for center, and |---:| for right alignment.

An inline code span uses single backticks to format a short code snippet within a sentence: `variable_name`. A fenced code block uses triple backticks (```) on their own lines to create a multi-line code display block, and supports optional language specification for syntax highlighting: ```python followed by the code and closing ```. Most Markdown renderers (including GitHub) apply color syntax highlighting when a language identifier is specified.

Links use the syntax [Link Text](https://url.com) or [Link Text](https://url.com 'Optional Title'). Images use nearly identical syntax with an exclamation mark prefix: . The exclamation mark is what tells the parser to render it as an embedded image rather than a clickable hyperlink. Reference-style links allow you to define URLs separately at the bottom of the document for cleaner source readability.

Yes, HTML-to-Markdown conversion (sometimes called 'reverse Markdown' or 'Turndown') is possible for basic HTML elements that have direct Markdown equivalents (headings, bold, italic, links, lists, code). However, complex or custom HTML elements — CSS-styled divs, forms, SVG, or JavaScript-enhanced widgets — have no Markdown counterpart and cannot be losslessly reverse-converted.

Markdown is used across an enormous range of platforms and workflows: (1) GitHub and GitLab use it for README.md files, issue descriptions, pull request comments, and project wikis. (2) Static site generators like Jekyll, Hugo, Gatsby, and Next.js use Markdown for blog post content files. (3) Documentation tools like MkDocs, Docusaurus, and GitBook store all documentation in Markdown. (4) Note-taking apps like Obsidian, Notion, and Bear support Markdown natively. (5) Email platforms, Slack, Discord, and many chat applications support a Markdown subset.

The .md file extension is an abbreviation for Markdown. It identifies plain text files formatted using Markdown syntax. The extension .markdown is also valid and identical, but .md has become the dominant convention due to brevity, particularly for GitHub README files (README.md).

Raw Markdown conversion to HTML is not inherently XSS-safe. Standard Markdown allows inline HTML tags, meaning malicious script injection like <script>alert('xss')</script> can be embedded in Markdown source and executed if rendered without sanitization. Secure Markdown renderers use an HTML sanitizer (like DOMPurify) after the Markdown-to-HTML conversion step to strip dangerous tags, attributes, and JavaScript protocol links before rendering to the DOM.