Markdown Syntax Guide: Headings, Links, Lists, Code, and Preview

Markdown is a lightweight way to write structured text without typing full HTML for every heading, link, list, and code block.

It is widely used in README files, GitHub issues, technical documentation, static-site generators, developer notes, and content-management systems.

Duck Cloud's Markdown Preview lets you preview Markdown locally in a sandboxed document.

Headings

Markdown headings commonly use hash symbols:

# Main heading
## Section heading
### Subsection heading

Keep heading levels logical. Do not jump between levels only because a smaller heading looks better visually.

For documentation and SEO-oriented articles, a clear hierarchy makes content easier to scan.

Paragraphs

Write ordinary text as normal paragraphs.

Separate paragraphs with a blank line:

This is the first paragraph.

This is the second paragraph.

Markdown renderers may differ in how they treat single line breaks, so use explicit paragraph separation when structure matters.

Bold and italic text

Common syntax is:

**bold text**
*italic text*

Use emphasis to clarify meaning, not to style every second sentence. Too much bold text makes a page harder to scan.

Links

A standard Markdown link looks like:

[Duck Cloud](https://www.duckcloud.info/)

For internal site content, descriptive anchor text is better than vague phrases such as “click here.”

For example:

[Unix Timestamp Converter](/tools/unix-timestamp-converter)

tells both readers and maintainers what the destination is.

Lists

Unordered lists commonly use a hyphen:

- JSON
- YAML
- CSV

Ordered lists use numbers:

1. Validate the data.
2. Convert the format.
3. Inspect the result.

Lists are useful when the content is genuinely sequential or categorical. Do not turn every paragraph into a list.

Inline code

Wrap short code, command names, file names, and exact values in backticks:

Use `npm run build` before deployment.

This visually separates machine-readable values from surrounding prose.

Code blocks

Use fenced code blocks for longer examples:

````markdown

const message = "Hello";
console.log(message);

````

When your renderer supports language identifiers, specify the language so syntax highlighting can work.

Blockquotes

Use a greater-than symbol:

> This is a quoted or highlighted passage.

Blockquotes are useful for actual quotations or important callouts, but avoid using them only for decorative indentation.

Horizontal rules

Many Markdown flavors support a horizontal rule such as:

---

Use it sparingly. Headings usually provide better semantic structure.

Tables

Some Markdown flavors support tables:

| Format | Best for |
|---|---|
| JSON | APIs |
| YAML | Configuration |
| CSV | Tabular data |

Table support is not identical across all Markdown implementations, so verify what your target platform supports.

Markdown flavors differ

There is no single renderer behavior shared by every platform.

GitHub-flavored Markdown, CommonMark-oriented renderers, static-site generators, CMS platforms, and custom Markdown libraries may differ around:

• tables;
• task lists;
• automatic links;
• HTML support;
• line breaks;
• extensions;
• sanitization.

Always preview the content in the environment where it will actually be published.

Preview before publishing

Use the Markdown Preview to inspect structure before moving content into your documentation or CMS.

If you need HTML output, use Markdown to HTML.

If you have existing semantic HTML that needs to become editable Markdown, use HTML to Markdown.

Security and raw HTML

Some Markdown systems permit embedded HTML.

If the input comes from untrusted users, rendering raw HTML without sanitization can create security risks.

Do not assume that “Markdown” automatically means safe. The rendering and sanitization policy matters.

Duck Cloud's Markdown conversion and preview tools are designed around local browser processing, but production applications still need an explicit security model for user-generated content.

Documentation checklist

• Use one clear page title.
• Keep heading levels logical.
• Use descriptive links.
• Put code and commands in code formatting.
• Preview tables and fenced blocks.
• Verify the Markdown flavor used by the destination.
• Sanitize untrusted rendered content.
• Keep source readable enough for code review.

Markdown works because it stays close to plain text. The best Markdown source remains easy to understand even before it is rendered.