The Ultimate
Markdown Handbook

Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004. It was designed to be readable and writable as plain text, while converting cleanly to HTML — a human-friendly alternative to writing raw markup.

A Markdown parser reads plain text and converts it to HTML. The original specification was intentionally loose, which led to inconsistent behaviour across tools. In 2014, CommonMark was established as a stricter, unambiguous specification that most modern tools now follow.

Where Markdown is used

• —GitHub — README files, issues, pull requests, wikis, and discussions
• —Documentation tools — Docusaurus, MkDocs, Sphinx, Read the Docs
• —Static websites — Jekyll, Hugo, Eleventy, Astro, Next.js
• —Note-taking — Obsidian, Notion, Bear, Typora, Logseq
• —AI prompts — Claude, ChatGPT, and other LLMs respond well to structured Markdown
• —Technical writing — API docs, internal wikis, knowledge bases
• —Messaging — Slack, Discord, Jira, Confluence (all support subsets of Markdown)

Benefits

• —Human-readable in its raw form — no special application needed to read it
• —Portable — plain text files work everywhere, in any editor
• —Version-control friendly — git diff shows meaningful changes
• —Fast to write — no mouse or toolbar required

Limitations

• —No universal standard — different renderers behave differently
• —Limited layout control — no native image sizing, columns, or colour
• —Complex content (callouts, diagrams) requires platform-specific extensions
• —Assumes plain-text delivery — not suited for pixel-perfect visual layouts

Common flavours

• —Original Markdown — John Gruber's 2004 specification — the original, intentionally loose
• —CommonMark — A strict, unambiguous specification (2014) — the modern baseline
• —GitHub Flavoured Markdown (GFM) — CommonMark plus tables, task lists, alerts, mentions, and autolinks
• —MultiMarkdown — Extends CommonMark with footnotes, tables, cross-references, and metadata
• —Pandoc Markdown — Extensive extensions for academic writing, citations, and multi-format export

Headings are created with hash (#) symbols. The number of hashes maps directly to the HTML heading level — one hash for H1, two for H2, up to six for H6. Always include a space between the hash and the heading text.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Bold, italic, and combined emphasis use asterisks or underscores. Using asterisks (*) is more universally supported than underscores inside words.

**Bold text**
*Italic text*
***Bold and italic text***
__Also bold__
_Also italic_

~~Strikethrough text~~

Use `npm install` to install the package.
The variable `isActive` controls visibility.

Paragraphs

Paragraphs are separated by a blank line. A single line break within a paragraph is rendered as a space in most Markdown renderers — it does not create a new paragraph.

First paragraph here.
Still the first paragraph.

This is a new paragraph.

Line breaks

To create a hard line break within a paragraph, end the line with two or more trailing spaces, or use the HTML <br> tag. Some parsers also accept a backslash (\) at the end of a line.

Line one with two trailing spaces  
Line two follows on a new line.

Markdown supports unordered lists (using -, *, or + as bullets), ordered lists (using numbers followed by a full stop), nested lists, and — in GitHub Flavoured Markdown — task lists.

- First item
- Second item
- Third item

1. First item
2. Second item
3. Third item

- Parent item
  - Child item
  - Another child item
- Another parent
  - Nested under second parent

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

Common mistakes

• —Missing the space after the bullet marker (- Item not -Item)
• —Inconsistent indentation when nesting lists
• —Mixing - and * markers within the same list (technically valid, but inconsistent)
• —Forgetting a blank line before the first list item when it follows a paragraph

Markdown supports several link syntaxes. The inline link is the most common. Always use meaningful, descriptive anchor text — avoid "click here" or bare URLs as anchor text.

[Visit the Anil G website](https://neelan.design)

[Anil G — UX Design Leader](https://neelan.design "Portfolio and articles")

<https://neelan.design>
<neelakhandan@gmail.com>

Read the [Markdown Handbook][handbook] for a full reference.

More detail in the [articles section][articles].

[handbook]: https://neelan.design/markdown-handbook
[articles]: https://neelan.design/articles

Anchor links

Most Markdown renderers automatically generate anchor IDs from headings, allowing links to specific sections using #heading-text. The format varies by platform — GitHub lowercases all characters and replaces spaces with hyphens.

[Jump to Chapter 3](#lists)
[Jump to Chapter 7](#code)

Image syntax is similar to links, with an exclamation mark prefix. The text in square brackets is the alternative text — a written description of the image, required for accessibility and shown when the image fails to load.

![A UX designer sketching on paper](images/ux-sketch.jpg)

![UX workshop session](workshop.jpg "Design thinking workshop, 2025")

[![Anil G — Design Leader](profile.jpg)](https://neelan.design/about)

![Wildlife photography][hero]

[hero]: /images/leopard.jpg "Leopard at dawn"

Important notes

• —Alt text is not optional — always write a meaningful description for every image
• —Core Markdown has no native image sizing syntax — use HTML width attributes or platform-specific extensions where needed
• —Relative paths work locally but may break in published environments — prefer absolute paths or root-relative paths for deployed sites
• —Some platforms strip or sanitise HTML, preventing the <img> width/height approach

<img src="diagram.png" alt="User journey diagram" width="600" />

Blockquotes are prefixed with a > symbol. They can be nested, and they can contain other Markdown elements including headings, lists, and code.

> In the stillness of the wild, I found what design often forgets:
> the value of observation before action.
>
> — Anil G

> First level of quoting.
>
>> Second level nested inside the first.

A horizontal rule creates a thematic break between sections. Three or more hyphens, asterisks, or underscores on their own line will all produce the same output.

---

***

___

Markdown provides two forms of code formatting: inline code for short snippets within text, and code blocks for multi-line code. Code blocks can be fenced (preferred) or indented.

Run `npm run dev` to start the development server.

```js
function greet(name) {
  return `Hello, ${name}`;
}

greet("Anil");
```

```
This is a plain text block.
No syntax highlighting applied.
```

    This line is indented with 4 spaces.
    It renders as a code block.

Escaping backticks inside inline code

Use double backticks: `` `backtick` `` inside inline code.

For a literal backtick in a fenced block:

````
```
This fence uses four backticks.
```
````

Tables are not part of the original Markdown specification. They are defined by GitHub Flavoured Markdown and are widely supported, but behaviour can vary. A table requires a header row, a separator row, and at least one data row.

| Name   | Role     | Location  |
| ------ | -------- | --------- |
| Anil   | Designer | Kochi     |
| Rajesh | Mentor   | Bengaluru |

| Left aligned | Centre aligned | Right aligned |
| :----------- | :------------: | ------------: |
| One          | Two            | Three         |
| Four         | Five           | Six           |

Notes on tables

• —Pipes inside table cells must be escaped with a backslash: \|
• —Tables with many columns can overflow on narrow mobile screens — consider a simplified layout for mobile users
• —Complex data is sometimes better expressed with a definition list or prose than a wide table

Footnotes allow you to add supplementary references without interrupting the flow of the main text. Support varies widely — they are available in GitHub Flavoured Markdown, Pandoc, MultiMarkdown, and some documentation tools, but not in the original Markdown spec or CommonMark.

Markdown was created in 2004.[^1]

CommonMark standardised the spec in 2014.[^2]

[^1]: John Gruber and Aaron Swartz, Daring Fireball, 2004.
[^2]: https://commonmark.org

Most Markdown renderers allow raw HTML inline within Markdown content. This is useful for elements that have no Markdown equivalent — such as collapsible sections, superscript, subscript, or custom attributes. However, HTML support is inconsistent and some platforms sanitise or strip it entirely.

<details>
  <summary>View additional context</summary>

  This content is hidden until expanded.

  You can include **Markdown** inside a details block.

</details>

x<sup>2</sup> + y<sup>2</sup> = z<sup>2</sup>

H<sub>2</sub>O

CO<sub>2</sub>

When to use HTML in Markdown

• —Only use HTML when Markdown cannot express the requirement
• —HTML inside Markdown reduces portability — the file may not render correctly in all tools
• —If your platform sanitises HTML, test before relying on it in production content
• —Prefer semantic HTML elements (details, summary, sup, sub) over presentational attributes

Callouts highlight important information — notes, tips, warnings, and cautions. There is no universal Markdown syntax for callouts. Each platform uses its own extension. The examples below are specific to the platforms listed — do not assume they work elsewhere.

GitHub alerts GitHub Flavoured Markdown

GitHub supports five alert types using a blockquote with a special keyword marker.

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information essential for users to succeed.

> [!WARNING]
> Urgent information requiring immediate attention.

> [!CAUTION]
> Advice about possible negative outcomes.

YAML frontmatter is a block of metadata placed at the very top of a Markdown file, delimited by triple-dashes (---). It is not part of Markdown itself — it is interpreted by static-site generators, documentation frameworks, and content management systems such as Jekyll, Hugo, Docusaurus, Astro, and others.

---
title: "The Ultimate Markdown Handbook"
description: "A complete visual reference to Markdown syntax and best practices."
author: "Anil G"
date: "2026-07-14"
slug: "ultimate-markdown-handbook"
tags:
  - markdown
  - documentation
  - reference
featured: true
draft: false
---

Common frontmatter fields

• —title — The page or post title used in the HTML <title> tag
• —description — A short summary used in meta descriptions and link previews
• —slug — The URL path segment for this page
• —date — Publication date — quote it to prevent YAML date parsing issues
• —tags — A YAML list of topic tags for categorisation
• —featured / draft — Boolean flags to control visibility and promotion

GitHub Flavoured Markdown (GFM) is a strict superset of CommonMark. It adds tables, task lists, strikethrough, autolinks, mentions, issue references, alerts, and diff syntax highlighting. GFM features work on GitHub and in tools that explicitly support GFM — they are not universal.

GFM features at a glance

• —Tables — Pipe-delimited tables with header and alignment rows
• —Task lists — - [x] and - [ ] checkboxes
• —Strikethrough — ~~text~~ renders as struck-through text
• —Autolinks — URLs and email addresses automatically become links without angle brackets
• —Mentions — @username links to a GitHub profile
• —Issue/PR references — #123 links to an issue or pull request in the same repo
• —GitHub alerts — > [!NOTE], > [!TIP], > [!WARNING], > [!IMPORTANT], > [!CAUTION]
• —Syntax highlighting — Language identifiers in fenced code blocks enable highlighting

```diff
+ Added line — shows in green on GitHub
- Removed line — shows in red on GitHub
  Unchanged context line
```

Autolinks in GFM

Visit https://neelan.design for more articles.

Email anil@example.com directly.

Mermaid is a diagramming language that renders inside Markdown code blocks using the mermaid language identifier. It is not part of core Markdown or CommonMark — it requires a Mermaid-enabled renderer. GitHub, GitLab, Notion, Obsidian, and many documentation frameworks support it.

```mermaid
flowchart LR
  A[Idea] --> B[Research]
  B --> C[Design]
  C --> D[Build]
  D --> E[Launch]
  E --> F{Review}
  F -->|Iterate| B
  F -->|Ship| G[Done]
```

```mermaid
sequenceDiagram
  User->>Application: Submit form
  Application->>Server: Validate and process
  Server-->>Application: Return result
  Application-->>User: Show confirmation
```

```mermaid
erDiagram
  USER ||--o{ PROJECT : creates
  PROJECT ||--o{ TASK : contains
  USER ||--o{ COMMENT : writes
  TASK ||--o{ COMMENT : receives
```

Large language models respond well to structured input. Markdown provides a natural way to create clear hierarchies, separate context from instructions, and specify exact output formats. Well-structured prompts reduce ambiguity and produce more consistent results.

Structural principles

• —Use headings to separate role, context, task, constraints, and output sections
• —Use lists for requirements — they are easier for a model to enumerate than long paragraphs
• —Use tables for structured comparison or multi-attribute data
• —Use code fences to supply source material, examples, or data the model should treat as literal text
• —Label examples explicitly — distinguish what you are showing from what you are asking
• —State the output format at the end: bullet list, numbered list, table, JSON, prose
• —Avoid deeply nested structures — they reduce clarity

# Role

Act as a senior UX researcher with experience in enterprise software.

# Context

We are evaluating an analytics dashboard used by financial analysts.
We have completed 8 user interviews. Interview notes are provided below.

# Task

Review the interview notes and identify recurring usability problems.

# Constraints

- Focus only on usability issues, not feature requests
- Do not speculate beyond what the notes support
- Flag if a finding appears only once and may not generalise

# Output

Provide:

1. A list of key themes (2–3 words each)
2. Supporting evidence for each theme (direct quotes preferred)
3. Severity: High / Medium / Low
4. Recommended next steps

---

# Interview Notes

[Paste notes here]

When publishing Markdown as web content, structure directly affects how search engines understand and rank the page. Clear heading hierarchies, meaningful links, descriptive alt text, and readable URLs all contribute to discoverability.

---
title: "UX vs CX vs Service Design: Understanding the Differences"
description: "Three overlapping disciplines — but not interchangeable ones. Here's how to tell them apart."
slug: "ux-vs-cx-vs-service-design"
date: "2025-07-25"
tags: [UX, CX, Service Design]
---

# UX vs CX vs Service Design: Understanding the Differences

Opening paragraph that introduces the topic and the central question.

## What Is UX Design?

Explanation of UX Design with concrete examples.

### The Role of Research

Subsection drilling into a specific aspect.

## What Is CX?

Explanation of Customer Experience.

## What Is Service Design?

Explanation of Service Design.

## Key Differences at a Glance

| Dimension | UX          | CX              | Service Design    |
| --------- | ----------- | --------------- | ----------------- |
| Focus     | Product use | Full journey    | System design     |
| Output    | Interface   | Experience map  | Service blueprint |

## Key Takeaways

Bulleted summary of the main points.

## References

- [Source title](https://example.com "Source site")

SEO checklist for Markdown content

• —Use exactly one H1 — the page title
• —Maintain logical heading hierarchy (H1 → H2 → H3, never skip levels)
• —Write descriptive headings that reflect the content — not just keywords
• —Add meaningful alt text to every image
• —Use descriptive anchor text for links — not "click here" or "read more"
• —Keep URLs short, lowercase, and hyphen-separated (handled via the slug field)
• —Add a concise meta description (in frontmatter) under 160 characters
• —Avoid keyword stuffing — write for readers first

Most Markdown errors fall into a small number of repeating patterns. The checklist below covers the mistakes most likely to produce unexpected rendering across tools.