Back to blog
·

Content Formatting Guide for Markdown: Basics to Pro

Content formatting guide for markdown: learn the basics, pro tips, and platform differences to create clean, readable content faster.

Introduction: What Markdown Is and Why It Matters

Markdown is a lightweight markup language that turns plain text into formatted content with simple symbols. You write in plain text, add conventions for headings, lists, links, images, and code blocks, and the result stays easy to read, edit, and move between tools.

That simplicity is why Markdown appears in blog posts, technical documentation, team knowledge bases, and README files. Writers use it to draft faster. Developers keep docs close to code. Marketers use it to publish clean, consistent content.

This guide covers the core Markdown syntax, the most common formatting patterns, and the platform differences that affect how content renders. You’ll learn how to format text, structure pages, add links and images, write code blocks, and avoid the mistakes that cause broken output.

What Is Markdown?

Markdown is a plain-text formatting syntax created by John Gruber with help from Aaron Swartz. You write with simple characters like #, *, and [], then convert that text into formatted output.

Unlike HTML, which uses tags like <h1> and <p>, or rich-text editors that hide formatting behind buttons, Markdown stays clean and portable. A Markdown file is readable before rendering, so you can scan notes, docs, or a GitHub README without opening a special editor.

That clarity makes Markdown common in documentation, note-taking apps like Obsidian, publishing tools, and GitHub workflows. Different platforms support slightly different Markdown flavors, so formatting can vary between GitHub, Slack, and static site generators.

How Do You Format Text in Markdown?

Markdown formatting starts with plain text and a small set of symbols. The goal is to keep the source readable while still producing structured output.

Use these basics:

  • # for headings
  • *italic* or _italic_ for emphasis
  • **bold** or __bold__ for strong emphasis
  • - or * for unordered lists
  • 1. for ordered lists
  • [text](URL) for links
  • ![alt text](image-url) for images
  • backticks for inline code and fenced blocks for multi-line code

A simple example looks like this:

# Product Update

We added `inline code`, a [reference link][1], and an image.

[1]: https://example.com

How Headings Work in Markdown

Markdown headings use # through ######: # for H1, ## for H2, down to ###### for H6. Use one clear H1 per page, then nest headings logically so the structure matches the content, not the design. That hierarchy improves readability and helps readers scan long pages.

A practical rule: use headings to organize ideas, not to make text look bigger. If a section needs a new topic, give it a heading. If it only needs emphasis, use bold or italics instead.

Bold and Italic Text in Markdown

Use *italic* or _italic_ for emphasis, and **bold** or __bold__ for strong emphasis. Most Markdown editors render both styles the same way, but some teams prefer one symbol consistently to keep source files uniform.

Examples:

  • *important* → important
  • **warning** → warning
  • _note_ → note
  • __key point__ → key point

Use bold sparingly so it highlights the most important terms. Overusing emphasis makes text harder to scan.

How to Create Lists in Markdown

Use unordered lists when the order does not matter, such as feature summaries or tool options:

  • Draft the content
  • Review the structure
  • Publish the page

Use ordered lists when the sequence matters, such as setup steps or instructions:

  1. Open the file
  2. Add the heading
  3. Preview the result
  4. Publish the page

Markdown also supports task lists in GitHub Flavored Markdown (GFM):

  • Write the draft
  • Check links
  • Add images

Lists are one of the most useful parts of Markdown because they make instructions easier to scan in documentation, README files, and knowledge base articles.

How to Add Links in Markdown

Use inline links for most cases: [GitHub Docs](https://docs.github.com) is clearer than [click here](https://docs.github.com). Descriptive anchor text tells readers and screen readers what the link does.

Use reference links when you want cleaner source text or need to reuse the same URL:

[GitHub Docs][1]

[1]: https://docs.github.com

Reference links are especially useful in long documentation pages where repeated URLs would clutter the text.

How to Add Images in Markdown

Images use ![alt text](image-url). Write alt text that explains the image’s purpose, not just what it is. For example, ![Markdown table example](table-screenshot.png) is more useful than ![image](table-screenshot.png).

Good alt text helps accessibility and also gives context if the image fails to load. In a CMS or documentation system, image handling may vary, so always check how the platform stores paths, captions, and resizing.

How Code Blocks Work in Markdown

Use inline code for short references such as npm install, README.md, or API_KEY. Use fenced code blocks for multi-line examples, shell commands, or sample Markdown.

Add a language identifier for syntax highlighting when the platform supports it:

npm install markdown-it

{
  "title": "Markdown"
}

Fenced code blocks preserve spacing, which makes them essential for technical writing, documentation, and tutorials.

Tables, Blockquotes, Horizontal Rules, and Footnotes

Use tables to compare features or summarize structured information:

Syntax Use
Links Navigate to another page
Tables Compare data

Use blockquotes for quoted text, editor notes, or callouts:

Blockquotes work well for warnings, source excerpts, and short takeaways.

Use horizontal rules (---) to separate sections when a visual break helps the reader.

Use footnotes when you want to add a source or clarification without interrupting the main text:

Markdown can support footnotes in some flavors[^1].

[^1]: A footnote can point to a source or explain a term without interrupting the main text.

CommonMark vs GitHub Flavored Markdown

Markdown is not one fixed standard in every tool. CommonMark defines a clear baseline, while GitHub Flavored Markdown (GFM) adds features GitHub users rely on, such as tables, task lists, and strikethrough.

That difference matters because content that looks perfect in one editor can break or display differently in a CMS, knowledge base, or publishing platform. GitHub supports GFM well, but another system may strip task lists, ignore footnotes, or treat line breaks differently.

If portability matters, write to the lowest common denominator first. Then test the final output in the destination platform, especially if the content will live in GitHub, a CMS, or a documentation site.

Why Markdown Renders Differently on Different Platforms

Markdown rendering depends on the parser, the platform, and the surrounding content system. A GitHub README, a CMS article, and a documentation site may all interpret the same source slightly differently.

Common reasons for differences include:

  • Different Markdown flavors, such as CommonMark or GFM
  • Platform-specific extensions or restrictions
  • Different handling of line breaks, tables, and footnotes
  • Sanitization rules in a CMS or knowledge base

The safest approach is to write simple, standard Markdown first, then verify the final result in preview mode and in the live destination.

How to Escape Special Characters in Markdown

If you need to show Markdown symbols literally, escape them with a backslash. Common examples include \*, \_, \[, \], and ```.

Escaping matters when you want to display syntax examples, product names, or text that would otherwise be interpreted as formatting. For example, \# shows a literal hash instead of a heading marker.

Common Markdown Mistakes

The most common Markdown mistakes are usually simple:

  • Missing blank lines around headings, lists, and code blocks
  • Broken links from copied URLs or malformed link syntax
  • Using unsupported syntax such as GFM tables in a tool that only supports basic Markdown
  • Forgetting alt text for images
  • Mixing heading levels in a way that breaks the page structure

These issues are easy to catch in preview mode, which is why editors and publishing workflows should always include a final review step.

Is Markdown Good for Blogging and Documentation?

Yes. Markdown is a strong choice for blogging and documentation because it is fast to write, easy to review, and portable across tools.

It works especially well for:

  • Blog drafts in a CMS
  • README files in GitHub repositories
  • Documentation and knowledge base articles
  • Internal notes and editorial workflows

Markdown is less ideal when you need highly complex layouts, but for most content teams it offers the right balance of speed and structure.

The Best Way to Learn Markdown Quickly

Start with the most common syntax: headings, paragraphs, bold, italics, lists, links, images, and code blocks. Then practice by writing a short README or blog draft from scratch.

A fast learning path:

  1. Use a Markdown cheat sheet
  2. Write in one of the best Markdown editors
  3. Turn on preview mode and compare source to output
  4. Publish a test page and check how it renders in your CMS or documentation tool
  5. Review Markdown publishing tips to improve your workflow

If you write documentation often, also read Markdown for documentation for practical structure and publishing advice.

Final Takeaway

Markdown is a simple, durable way to format content in plain text. Learn the core syntax, understand how CommonMark and GFM differ, and test your output before publishing. That approach keeps Markdown dependable for blogging, documentation, and collaborative publishing.