简体中文
English
Website review
This review may include AI-generated content and is not individually verified. Domain, certificate and other facts come from the observed data on this page.
What is Markdown Guide?
Markdown Guide is a free, open-source reference site that teaches Markdown, the lightweight markup language used to format text with plain characters like # for headings or **bold** for emphasis. It is aimed at anyone who writes for the web or in tools that accept Markdown—bloggers, developers, students, technical writers and note-takers—and it works as both a beginner tutorial and a quick lookup reference. Its core content is split into a getting-started walkthrough, a basic syntax reference, and an extended syntax section covering tables, fenced code blocks and automatic links.
Markdown Guide
How people typically use it
- Learning from zero: follow the Getting Started path if you have never typed Markdown before.
- Checking a specific format: jump straight to the basic syntax page when you forget how to make a link or a list.
- Going beyond the basics: use the extended syntax pages when you need tables or code blocks that plain Markdown does not cover.
- Keeping a cheat sheet handy: the site offers a condensed cheat sheet for everyday reference.
A practical example
Suppose you write documentation in a Git-based tool and need a table with a header row and aligned columns. Basic Markdown will not do it, so you would open the extended syntax material, copy the pipe-and-dash pattern, and adapt it to your content. That is faster than searching a general forum, because the reference is organized around syntax rather than around a specific app.
Trade-offs to keep in mind
Markdown flavours differ. A syntax that works on one platform may render differently or not at all on another, so the site's own guidance about which features are widely supported is worth reading before you commit to a format. It is a reference, not an interactive editor or a publishing service, so you will still need a separate tool to write and preview your files.
Next step
Pick one small document you already need to write—meeting notes, a README, a blog draft—and rewrite it in Markdown while keeping the basic syntax page open. That single exercise will tell you whether you need the extended syntax pages or a dedicated editor next.
How do I start writing in Markdown if I've never used it before?
Start with a plain text editor and three pieces of syntax: # for headings, **bold** for emphasis, and - for bullet lists. That is enough to write a real document today. Markdown is just ordinary text with a few punctuation marks that tell a renderer how to format it, so you can learn it while writing rather than before.
Markdown Guide is built for exactly this starting point. Its Getting Started section is aimed at novices, and the Basic Syntax page works as a lookup table for formatting questions as they come up. When you want tables, fenced code blocks or automatic links, the Extended Syntax section covers those separately, which keeps the beginner material uncluttered.
A first session that works
- Open any plain text editor — Notepad, TextEdit in plain-text mode, or a code editor.
- Save the file as
notes.md. - Write a title with
#, a couple of paragraphs, and a short-list. - Paste the text into an online Markdown previewer, or open the file in an app that renders Markdown, to see the formatted result side by side with your source.
That last step matters most. Seeing the same text rendered and unrendered is how the syntax stops feeling arbitrary.
Where you will actually use it
- Notes and to-do lists in apps that store Markdown files locally.
- README files and documentation on code hosting platforms, where Markdown is the default format.
- Blog posts and static sites, where you write in Markdown and a generator produces the HTML.
- Long-form writing in editors that support it, so you keep clean plain-text drafts you can move between tools.
If none of those apply to you, Markdown may be more overhead than it is worth — a word processor is fine for a single formatted letter.
A realistic next step
Pick one document you need to write this week and write it in Markdown instead. Keep the Basic Syntax page open in a second tab and check it only when you get stuck. After two or three documents, the common marks become automatic, and you can start exploring extended syntax for the features you actually miss.
Which Markdown syntax should I use to format tables, code blocks, and links in my documents?
For tables, fenced code blocks, and links, Markdown's core syntax covers links and code, while tables require extended syntax (not every Markdown processor supports them).
Links: Use inline links for one-off references — [link text](https://example.com) — or reference-style links when the same URL appears repeatedly or you want to keep sentences readable: define [label]: https://example.com elsewhere and write [link text][label]. Reference style is handy in long documents where inline URLs clutter the prose.
Code blocks: For anything longer than a phrase, use fenced code blocks with triple backticks, and add a language name for syntax highlighting:
```python
print("hello")
```
Indented code blocks (four spaces) also work but are harder to read and can't carry a language tag, so fenced blocks are the better default. Use single backticks for inline code like npm install.
Tables: These come from extended syntax, typically with pipes and a separator row:
| Tool | Purpose |
| ---- | ------- |
| Linter | Checks style |
The trade-off: tables render inconsistently across processors, and cells can't hold multi-line content. If a table needs complex formatting, consider a list instead.
The Markdown Guide separates basic from extended syntax, which is a useful distinction: check whether your target platform (GitHub, a static site generator, a notes app) supports the extended features before relying on them. A practical next step is to write one short test document with a link, a fenced code block, and a small table, then preview it in your actual publishing tool — that reveals which syntax your workflow truly supports.
How can I convert my Markdown files into a published web page?
The Markdown Guide itself is a learning and reference site, not a publishing platform. It teaches the syntax you need, then you choose a separate tool or service to turn your .md files into a live web page. Start with its Getting Started guide and basic syntax pages at Markdown Guide, then pick a publishing route based on how much control you want.
Common conversion routes
- Static site generator: Tools like Jekyll, Hugo, Eleventy or Astro read your Markdown files and output HTML you can host anywhere. Best for blogs, documentation and sites with many pages.
- Hosted publishing service: Platforms such as GitHub Pages, Netlify or Vercel can build from a repository and serve the result. Little server administration, but you follow their build conventions.
- One-click converters: Some tools turn a single Markdown file into a shareable web page with minimal setup. Convenient for notes and drafts, less flexible for large sites.
- Manual conversion: A Markdown-to-HTML converter plus your own hosting gives maximum control but the most work.
The Markdown Guide's extended syntax page matters here: tables, fenced code blocks and automatic links behave differently across converters. Check what your chosen tool supports before you rely on a feature.
A practical first step
Create one small file, index.md, with a heading, a paragraph and a link. Run it through your chosen tool and open the output in a browser. If the link and heading render correctly, scale up to your real content. If not, the problem is your toolchain, not your Markdown.
For version-controlled publishing, a repository plus a static host is the most durable pattern: you keep the Markdown source, and the host rebuilds the page on each push. For a single document you want to share immediately, a one-click converter is faster.
What tools and editors work best for writing Markdown?
The best Markdown tool depends less on the language itself and more on where your text needs to end up. Markdown is plain text, so almost any editor can open it; the differences show up in preview, export, collaboration and platform quirks.
Markdown Guide is a reference site rather than an editor. It is useful for checking basic and extended syntax, including tables, fenced code blocks and automatic links, and for seeing how different flavors diverge before you commit to a tool. Use it to settle syntax questions, then pick an editor around your workflow.
Match the tool to the job
- Quick notes and drafts: a lightweight editor with live preview and distraction-free writing suits people who want to see formatting without leaving the keyboard.
- Code and technical docs: an editor built into your code editor, or one with fenced code block support and a folder-based file view, keeps documentation next to the project.
- Long documents and books: look for outline navigation, cross-references, footnotes and reliable export to PDF or DOCX.
- Collaboration: a browser-based editor with comments, suggestions and version history is usually better than emailing files.
- Publishing: some tools export straight to a static site or CMS; others require a converter step.
A practical comparison
| Need | What to prioritize | Trade-off |
|---|---|---|
| Learning syntax | Preview and a syntax reference | Fewer export options |
| Writing code docs | Code fences, file tree, Git integration | Less polished typography |
| Reports and books | Export to PDF/DOCX, outline, citations | Heavier, sometimes paid tiers |
| Team editing | Comments, history, shared workspace | Lock-in and online-only access |
Next step
Write the same short document in two candidates: one heading, one list, one table, one code block and one link. Export it to the format you actually deliver. The tool that survives that test with the fewest manual fixes is the right one for you, regardless of popularity.
How does Markdown differ across platforms like GitHub, Reddit, and documentation sites?
Markdown is a shared core with platform-specific extensions. The basics — # headings, **bold**, *italic*, [links](url), and - lists — render almost everywhere. Differences appear when you move past that core: tables, footnotes, task lists, syntax highlighting, and how raw HTML is treated.
The Markdown Guide frames this as "basic syntax" versus "extended syntax," which is a useful mental model. Basic syntax is the safe common denominator; extended syntax is where platforms diverge. Markdown Guide
H3 Comparison
| Feature | GitHub | Typical documentation sites | |
|---|---|---|---|
| Core formatting | Supported | Supported | Supported |
| Tables | Yes (GFM) | Yes | Usually, via the generator |
Task lists - [ ] |
Yes | No | Rarely |
| Footnotes | Yes | No | Depends on generator |
| Fenced code blocks | Yes, with language tags | Yes, with language tags | Yes, often with highlighting |
| Raw HTML | Filtered and sanitized | Not supported | Varies; often allowed or stripped |
Strikethrough ~~text~~ |
Yes | Yes | Sometimes |
| Auto-linking URLs | Yes | Yes | Usually |
H3 What This Means in Practice
GitHub uses GitHub Flavored Markdown (GFM), which adds tables, task lists, strikethrough, autolinks, and footnotes. It also sanitizes raw HTML, so embedded scripts or unusual tags won't work. Reddit keeps closer to the original Markdown spec, so task lists and footnotes generally don't render there.
Documentation sites are the least predictable category. Many use static site generators or doc platforms that support Markdown but add their own shortcodes, admonition blocks, or component syntax. A page that renders perfectly on GitHub may break or display literally on a docs site, and vice versa.
H3 A Practical Next Step
If you write for more than one platform, draft in the basic syntax first, then add extended features only for the platform you're targeting. Before publishing, preview the rendered output rather than trusting the raw text.
For example, a README with - [ ] checkboxes works on GitHub but shows as a literal bullet on Reddit. If the same content needs to appear in both places, use plain bullets and mention the checklist in prose.
H3 Decision Criterion
Ask what the reader will actually see. If portability matters more than features, stay with basic syntax. If you're writing for one platform and know its rules, use its extensions freely — just re-check the rendering whenever you copy the content elsewhere.
Cloudflare
Fastly
Fastmail
User reviews (0)