The Complete Markdown Guide: Syntax, Tools, and Best Practices

Markdown is the closest thing developers have to a lingua franca. It is plain text, human-readable, and works everywhere, GitHub, your terminal, your static site generator, and yes, your documentation pipeline.

But Markdown is also a mess. Six competing flavors. Tables that render differently in every renderer. Code blocks that lose syntax highlighting. Diagrams impossible to write as text.

This guide is the antidote: everything you need to write, read, and ship Markdown in 2026.

Markdown is plain text with lightweight formatting. You write # Heading 1 and it becomes a heading. **bold** becomes bold. You can learn the core syntax in 10 minutes. Mastering it, tables, diagrams, citations, multi-format publishing, takes a day.

If you are starting a project that will be read on screens, ship Markdown. If it will be printed or formally reviewed, Markdown with a good export pipeline still beats Word for version control and collaboration.

The five things you use 90% of the time:

What you want	Markdown syntax
Headings	# Heading 1, ## Heading 2
Bold / italic	**bold**, *italic*, __underline__
Lists	- item, 1. item, nested with 2 spaces
Links	[text](url)
Code	`inline`, fenced blocks with language for syntax

Everything else, tables, diagrams, footnotes, cross-references, is bonus.

Core Markdown syntax (the 80% you need daily)

Headings and structure

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

That is it. No closing tags. Markdown headings map to HTML h1 through h6. Most renderers (GitHub, GitLab, ForgeMD) auto-generate a table of contents from these.

Why this matters: If your headings are inconsistent, your TOC breaks. Use ## for sections, ### for subsections, and do not skip levels (never go from ## to ####).

Emphasis and inline styling

**Bold text**
*Italic text*
``code``
~~Strikethrough~~ (GitHub Flavored Markdown)

Common mistake: *Italic* with spaces renders as literal asterisks in some renderers. Write *Italic text* without adjacent spaces.

Lists

Ordered lists, unordered lists, and nested combinations. GitHub Flavored Markdown lets you write 1. for every item and it auto-numbers.

1. First item
2. Second item
   1. Nested ordered
   - Nested unordered
3. Third item (numbers auto-increment)

Pro tip: Use CTRL+SHIFT+] (or the equivalent) in a real editor to auto-indent list items. Don’t fight the indentation by hand.

Links and images

[Anchor text](https://example.com)
![Alt text](image.png)
![Alt](image.png){width=500px}  

Best practice: Use descriptive anchor text, not “click here.” Links should make sense out of context.

Code blocks and syntax highlighting

Fenced code blocks with language identifiers get syntax highlighting in every serious renderer:

```javascript
const greeting = "Hello, world!";
console.log(greeting);

def hello(name):
    print(f"Hello, {name}!")

Languages that work everywhere: javascript, python, bash, json, yaml, sql, html, css.

Blockquotes

> This is a blockquote.
> It can span multiple lines.

Useful for callouts, notes, and quoting issues from bug reports.

Horizontal rules

---

Three hyphens, asterisks, or underscores. Creates a thematic break.

Beyond basic Markdown: the extensions you should know

Plain Markdown was designed for blog posts. Modern Markdown (GitHub Flavored, CommonMark) supports far more.

Tables (GFM)

| Feature | ForgeMD | HackMD |
|---------|---------|--------|
| Offline | Full (Tauri) | Web only |
| Collaboration | Yjs CRDT | Basic |
| Export | 8+ formats | 3 formats |

Rendering note: Tables require a blank line before them in GFM. Some renderers are picky.

Footnotes

Here is a statement with a footnote[^1].

[^1]: The footnote content.

Use case: Academic writing, legal disclaimers, tangential explanations that would break reading flow.

Task lists (GFM)

- [x] Write the guide
- [ ] Review with the team
- [ ] Ship it

Renders as checkboxes in GitHub and ForgeMD.

Mermaid diagrams

Mermaid is text-based diagramming embedded in Markdown:

```mermaid
graph TD
    A[Start] --> B{Is it raining?}
    B -->|Yes| C[Take umbrella]
    B -->|No| D[Go for a walk]
    C --> E[Arrive dry]
    D --> E

Supported in GitHub, GitLab, ForgeMD, and Obsidian. No images needed. Pure text. Version-controllable.

Mathematical notation (KaTeX / MathJax)

Inline math: $E = mc^2$

Block math:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Supported in Obsidian, ForgeMD, and GitHub (via MathJax).

Frontmatter

---
title: "My Document"
author: "Jane Doe"
date: 2026-01-01
tags: [markdown, guide]
---

Frontmatter sits at the top of the file, between --- lines. It feeds into static site generators, CMS pipelines, and document metadata.

Markdown flavors: why your tables break

Markdown has no single standard. Your document renders one way on GitHub, another in Obsidian, and a third in your static site generator.

Flavor	Where it lives	Key differences
CommonMark	The standard	Safe baseline, no extensions
GitHub Flavored Markdown	GitHub, GitLab	Tables, task lists, strikethrough, autolinks
Markdown Extra	Pandoc, typora	Tables, footnotes, definition lists
Obsidian Flavored	Obsidian	Wikilinks, Dataview, callouts
ForgeMD	ForgeMD	GFM + Mermaid + KaTeX + wikilinks + callouts

Rule of thumb: Write in GFM. It is the most widely supported extended flavor. If you need Obsidian-specific features (wikilinks, Dataview), wrap them in conditional comments or keep them in a separate “Obsidian” version.

Editors: choosing the right tool for the job

For developers (you live in the terminal)

Editor	Offline	Git-native	Markdown support
VS Code	Full	Native	Excellent (extensions, preview, lint)
Vim / Neovim	Full	Native	Via plugins (vim-markdown, glow)
Emacs	Full	Native	Built-in (markdown-mode)
ForgeMD	Full	Folder sync	Full GFM + Mermaid + KaTeX

For writers and mixed teams

Editor	Collaboration	Offline	WYSIWYG
ForgeMD	Yes (Yjs CRDT)	Full	Yes (two live views)
Obsidian	Via Sync	Full	Plugin
Typora	No	Full	Yes (seamless preview)
HackMD	Yes	No	Yes (live preview)

The middle ground problem: Most editors pick a side, developer tool vs writer tool. ForgeMD’s two-view model (Markdown + WYSIWYG simultaneously) serves both in one editor.

Linting and validation: treat Markdown like code

If your Markdown goes through CI/CD, lint it. If it does not, start.

markdownlint

The standard linter for Markdown. It flags structure problems: inconsistent list markers, trailing spaces, headings without a blank line after them, and over-long lines. Runs locally and in CI.

# .markdownlint.yaml
default: true
MD013: false  # Line length, disable for long lines
MD024: false  # Duplicate headings, allow across different files

CI integration (real action reference):

# .github/workflows/lint.yml
- uses: DavidAnson/markdownlint-cli2-action@v15
  with:
    globs: 'docs/**/*.md'

Prose linters

Tools like write-good and textlint catch weak phrasing (weasel words, passive voice, adverbial intensifiers) in documentation. Optional, but useful when multiple authors contribute.

Link checking

Dead links rot content. Use lychee in CI:

lychee --verbose docs/

Export and publishing: getting Markdown to the right format

Markdown is a source format. You ship it as PDF, HTML, or DOCX.

Static site generators

SSG	Language	Best for
Astro	TypeScript/JS	Content-focused sites, fast
Hugo	Go	Fast builds, large sites
Next.js	JavaScript	Full-stack apps with content
Jekyll	Ruby	GitHub Pages, simple blogs
MkDocs	Python	Documentation sites
Docusaurus	JavaScript	Developer docs

All consume Markdown + frontmatter natively.

Print-ready PDF

Three paths:

1. Pandoc, pandoc input.md -o output.pdf. Maximum control, requires LaTeX.
2. Typst, typst compile input.md output.pdf. Modern, fast, no LaTeX.
3. ForgeMD export, File → Export → PDF. Uses TipTap’s print CSS, preserves Mermaid diagrams and code highlighting.

Word (.docx) for stakeholders

pandoc input.md -o output.docx gets you 80% there. For clean styling, use a reference template. ForgeMD’s DOCX export preserves tables, code blocks, and images, useful when stakeholders insist on Word track changes.

Markdown and version control: the Git workflow

Markdown and Git are the pair that never breaks up.

# Standard workflow
git add changelog.md
git commit -m "docs(changelog): add v1.2 release notes"

# Reviewing a doc change
git diff main -- docs/api.md

Why this wins: You can diff documentation the same way you diff code. Three-way merges work on plain text. No binary blob conflicts.

Writing for diffs

• One sentence per line makes diffs readable.
• Keep lines under 80 characters (markdownlint MD013).
• Use relative links between docs ([API Reference](./api-reference.md)).

Commit message convention

docs: add authentication endpoints reference
docs(api): update token refresh flow
docs: fix broken link in deployment guide

Tools that enforce this: commitlint, semantic-release.

Common mistakes (and how to avoid them)

1. Inconsistent heading levels

Jumping from ## to #### breaks the document outline. Screen readers and TOC generators rely on sequential hierarchy. Always use ## for sections, ### for subsections.

2. Hard line breaks

Pressing Enter in the middle of a paragraph creates a
. In most Markdown, you need two spaces at end-of-line OR a blank line between paragraphs. Configure your editor to show trailing whitespace.

3. Tables without context

Tables are data-dense. Always include a brief caption or the row above explaining what the table shows. A standalone table with no context confuses readers.

4. Images without alt text

Every ![description](image.png) needs a meaningful alt description. If the image fails to load, or a screen reader parses it, the alt text carries the meaning.

5. Links that break

Use absolute URLs for external links (so relative base tags do not interfere), and relative URLs for internal links (so they work across staging and production).

Best practices that survive tooling changes

1. One sentence per line in your .md source. Makes diffs readable, and tools that reflow text (Pandoc, Typst) handle it cleanly.
2. Use GFM as your baseline. It is the most widely supported extended flavor.
3. Lint in CI. markdownlint catches structure problems before they ship.
4. Version control from day one. Even for solo projects, git init in your docs folder pays off.
5. Choose one export pipeline and stick to it. Do not switch between Pandoc and Typst mid-project, the rendering differences will drive you mad.

Tools and workflows worth having

Tool	Purpose
markdownlint	Linting, editor integration
glow	Terminal Markdown preview
prettier –parser markdown	Auto-formatting
lychee	Link checking in CI
Pandoc	Multi-format export
Typst	Beautiful PDF output
ForgeMD	Collaborative editing + full offline
Obsidian	Local graph-based knowledge bases
Mark Text	Live-preview editor

When Markdown is not enough

Markdown is not a replacement for:

• Word processors (Pages, Word, Google Docs), when you need precise layout control.
• Presentation tools (PowerPoint, Keynote, Google Slides), when you need slide-level formatting.
• CAD / scientific software, when you need precise vector graphics or embedded computation.

The strength of Markdown is that it stays out of your way. Use it when the content matters more than the formatting.

FAQ

Do I need to know Markdown to write docs?

No. ForgeMD’s editor supports WYSIWYG and Markdown as two views of the same document, write in rich text, the Markdown updates. Switch to Markdown when you want direct control.

What is the difference between GFM and CommonMark?

CommonMark is the base spec: a stable standard. GFM (GitHub Flavored Markdown) adds tables, task lists, strikethrough, autolinks, and HTML passthrough. Write in GFM; it is the default on GitHub, GitLab, and most modern tools.

Can I write diagrams in Markdown?

Yes, Mermaid embeds in code blocks. ```mermaid supports flowcharts, Gantt charts, sequence diagrams, class diagrams, and more. Pure text, renderer-independent.

How do I export Markdown to PDF?

Three ways: (1) ForgeMD’s export (File → Export → PDF, preserves diagrams), (2) Pandoc with LaTeX (pandoc file.md -o file.pdf), (3) Typst (typst compile file.md file.pdf). The free browser converter at forgemd.io/tools/markdown-to-pdf works with no install.

Can I lint Markdown in CI?

Yes, markdownlint for structure, prettier --check for formatting, lychee for broken links. All run in GitHub Actions with a few lines of YAML.

What is frontmatter and why use it?

Frontmatter is metadata at the top of a Markdown file (between --- lines). It feeds titles, authors, tags, and dates into static site generators and CMS pipelines.

Does ForgeMD support Mermaid diagrams?

Yes, render Mermaid natively in the editor. Export to PDF/PNG/SVG with diagrams intact.

What export formats does ForgeMD support?

Markdown (native), PDF, HTML, DOCX, LaTeX, Epub, and ODT. Extended formats via Pandoc integration.