The Markdown guide: syntax, extensions, and how Markups works

Markdown is plain text with lightweight markers for document structure. A Markdown file stores headings, paragraphs, lists, links, and code in a text format that people can edit in many tools. A Markdown processor turns that source into HTML or another presentation. Core Markdown syntax is portable; extensions such as tables, diagrams, or math depend on the processor and the destination where the file is viewed.

How Markdown works

A Markdown document is not itself a formatted Word or web page. It is a source file—often saved with a .md or .markdown extension—that a compatible application interprets. The symbols remain visible in the source and carry meaning to a renderer.

For example, # Project notes is a heading in the source. A renderer converts it to an HTML heading. A Markdown editor usually shows both the editable text and a rendered preview so a writer can inspect structure without losing the original file.

There is more than one Markdown specification. CommonMark describes a standardized baseline; GitHub Flavored Markdown (GFM) adds syntax such as tables and task lists. Other products add their own extensions. Always check the renderer that will display the final document.

Core syntax and examples

Headings and paragraphs

Use one to six number signs for a heading. Put a blank line between paragraphs to make their separation explicit.

# Main heading
## Section heading

This is one paragraph.

This is another paragraph.

Emphasis

Single asterisks or underscores commonly mark emphasis; double characters mark stronger emphasis. For portable writing, keep the markers around a complete word or phrase.

*emphasis* and **strong emphasis**

Lists

Unordered lists use a hyphen, plus sign, or asterisk. Ordered lists use numbers followed by a period. Indent nested items consistently.

- Draft the note
- Review the examples
  - Check the rendered preview

1. Gather the requirements
2. Record the decision

Links and images

Links place the label in square brackets and the destination in parentheses. An image adds an exclamation mark before the same pattern. Add useful alternative text because the image itself may not load or be visible to every reader.

[Markdown guide](https://example.com/guide)
![Flow diagram showing the review steps](review-flow.png)

Blockquotes and code

Start quoted lines with >. Use a backtick around inline code and a fenced block for multiple lines. Add a language after the opening fence when the renderer supports code highlighting.

> Keep the source readable for the next person.

Use `npm run build` to create the production bundle.

```js
const heading = "A clearer document";
console.log(heading);
```

Other common core constructs include thematic breaks made from three or more hyphens, asterisks, or underscores; inline links; reference-style links; and escaped punctuation when a symbol should be shown literally.

CommonMark, GFM, and extensions

Syntax beyond the shared baseline can be useful, but it is not guaranteed to travel with a file. The table below describes broad compatibility, not a promise that every renderer behaves identically.

For example, a task list marker such as - [ ] can render as a checkbox in GFM. The specification does not require every application to make that checkbox interactive. A table works in many developer tools but may not render in a minimal Markdown viewer. Keep the source file when you need the original syntax and preview the document in its actual destination.

What Markups supports today

This list was checked against the current Markups source on November 4, 2026. It describes implemented behavior, not an industry-wide Markdown promise.

• GFM parsing: the Marked parser is configured with GFM enabled. This includes common GFM constructs such as tables, task-list markers, strikethrough, and autolinks supported by the selected parser version.
• Line breaks: Markups sets the parser's breaks option to true. A source line break can render as a visible break here, even though another renderer may require two trailing spaces or a blank line.
• Heading identifiers: a heading-ID extension creates IDs used for linking to headings. Generated slug rules may differ elsewhere.
• Alerts and footnotes: configured extensions recognize their respective syntax. Treat these as extensions when sharing with a renderer that may not support them.
• Emoji shortcodes: supported shortcode names can render as emoji, such as :smile:. Shortcode dictionaries vary by tool.
• Code highlighting: fenced code uses Prism highlighting for the languages bundled with the application, including JavaScript, TypeScript, Python, JSON, Markdown, CSS, HTML/XML, Bash, YAML, Java, C, C++, C#, Rust, Go, and SQL. Unknown labels fall back to plain text.
• Math: KaTeX renders supported LaTeX-style inline and display math. Availability and macro behavior can vary by parser and renderer.
• Diagrams: Mermaid fenced blocks can render diagrams in the preview. A viewer without Mermaid support may display the source fence instead.
• Video links: supported video URLs and attachment links can be converted into preview embeds. This extension does not mean every media host or URL is supported.

Open the Markdown cheatsheet for short examples, the Mermaid examples and math examples for extension-specific syntax, and the Compatibility Lab to test a realistic document.

How Markdown is processed in Markups

1. The editor holds the Markdown source.
2. Marked parses the source with the configured GFM option and registered extensions.
3. The parsed HTML passes through Markups' preview sanitization helper before it enters the preview.
4. Code, supported video links, and Mermaid diagrams receive their specific rendering steps. Mermaid SVG output is sanitized again before insertion.
5. Preview rendering can emit updates for the editor's surrounding features.

Sanitization matters because a Markdown parser's job is to produce formatted output, not automatically to define a safe HTML policy. Markups uses DOMPurify through its sanitization helper. See the safe-rendering checklist for the security boundary and what to retest when a renderer changes.

How to use Markdown in Markups

1. Open the Markups editor and start a document or open an existing Markdown file.
2. Write in the source editor. Use headings to show the document outline and fenced code blocks to preserve code formatting.
3. Check the live preview for heading hierarchy, links, tables, code, diagrams, and math.
4. Use a toolbar action, snippet, or template when it helps insert a supported pattern; verify the result in both source and preview.
5. Keep a Markdown copy when portability or future editing matters. Choose an export only after checking the format limitations.

The Markups project also contains tabs, document navigation, autosave, snippets, templates, a Markdown linter, table of contents, live-preview editing, media controls, and export tools. Which controls are visible can depend on the current application surface and mode; consult the product UI and product overview for the current workflow.

Export notes

• Markdown: retains editable plain-text source and its syntax.
• HTML: creates a rendered-document format; check how your destination handles styles and embedded media.
• PDF: Markups currently creates an image-based PDF. The exported page is not a searchable/selectable text PDF.
• Word-compatible output: the current Word export is an HTML-based .doc file, not a native OOXML .docx.

Long documents, fonts, external images, diagrams, and browser rendering can affect export appearance. Review the resulting file in the application where it will be used. The PDF tutorial gives format-specific steps and limits.

Integrating Markdown in an application

A typical web application separates parsing from sanitization. The following browser example is illustrative; adjust imports, configuration, allowed HTML, and error handling to your application.

import { marked } from "marked";
import DOMPurify from "dompurify";

marked.setOptions({ gfm: true });

function renderMarkdown(source, preview) {
  const parsedHtml = marked.parse(source);
  const safeHtml = DOMPurify.sanitize(parsedHtml);
  preview.innerHTML = safeHtml;
}

For a production integration, verify the parser's current API and asynchronous behavior, define a deliberate sanitizer policy, and audit extensions that mutate the document after parsing. Do not put untrusted Markdown into innerHTML without sanitizing the final HTML. A Content Security Policy can be useful defense in depth, but it is not a replacement for safe output handling.

Portability and troubleshooting

• A heading link does not work: the destination may generate a different heading ID. Check the rendered destination and update the link.
• A table or checklist shows raw syntax: the destination may not implement GFM. Use a simpler list or link to a rendered copy.
• A line break disappears: line-break rules differ. Add a blank line for a paragraph or use the destination's documented hard-break syntax.
• A diagram or equation does not render: the destination needs a compatible Mermaid or math extension. Keep the original source in the file.
• Code has no colors: highlighting is presentation, not part of Markdown semantics. Add a language label and check that the target tool bundles that language.
• An image is broken: confirm that the path is correct relative to the Markdown file and that the destination can access it.

If a document is intended for many platforms, prefer core syntax for essential meaning. Use extensions when their extra presentation adds real value and provide a readable fallback for the content that matters.

Limits and future features

Markdown cannot guarantee the same rendered result in every application. CommonMark and GFM have defined behavior, but tools choose which extensions and styling to include. Markups adds optional renderers for math, diagrams, alerts, footnotes, emoji, video links, and syntax highlighting; those extensions will not automatically appear in a viewer without matching support.

No public, committed Markups feature roadmap was found in the sources checked for this guide. For that reason, it does not list speculative “upcoming” Markdown features. Treat future support as unknown until it appears in a released build and product documentation. This guide should be updated when a feature is actually shipped and verified.

Common questions

Is Markdown the same as HTML? No. Markdown is a source format that a parser may convert to HTML. The two are related through rendering, but they are not interchangeable documents.

Does Markdown always support tables? No. Tables are a widely used extension, including in GFM, but they are not part of every minimal Markdown dialect.

Can Markdown contain math or diagrams? Yes, in a compatible extension. The source needs a math or diagram renderer at the destination.

Is Markdown safe to render as HTML? The format name does not make output safe. Applications should sanitize generated HTML and review extensions; see the safe Markdown rendering guide.