Markdown 102: list, quote และ codeMarkdown 102: lists, quotes, and code

The fastest way to make a README readable is to stop writing one giant paragraph.

Lists, quotes, and code blocks give the reader scanning handles. They can jump to the command, checklist, warning, or decision without reading every sentence.

Bullets

Use - for normal bullets.

## Features

- Live Markdown preview
- Copy button
- GitHub-style tables

Keep each bullet parallel. If the first bullet starts with a verb, make the others start with verbs too.

Good:

- Install dependencies
- Run the dev server
- Open the preview

Messy:

- Install dependencies
- The dev server
- Preview should be opened

Numbered lists

Use numbers when order matters.

1. Clone the repository
2. Install dependencies
3. Start the dev server

Most Markdown renderers will fix the displayed numbers for you, but beginners should write the real numbers anyway. It keeps the source easier to read.

Checklists

GitHub-flavored Markdown supports task lists:

- [x] Create the project
- [x] Add a README
- [ ] Add screenshots
- [ ] Publish the first release

Use checklists for work status, launch steps, migration steps, and "before you submit" items.

Blockquotes

Use > when you want a note to stand apart.

> This project is a prototype. Do not use it for production data yet.

A quote should be short. If it becomes three paragraphs long, it is probably a section, not a quote.

Inline code

Use backticks for command names, filenames, package names, and exact values.

Run `pnpm install`, then open `README.md`.

Do not put every technical word in backticks. Reserve them for exact text the reader may need to type, copy, or recognize.

Code blocks

Use fenced code blocks for commands or code snippets.

```bash
pnpm install
pnpm run dev
```

Add the language name when you know it. GitHub can use it for syntax highlighting.

Common language labels:

Common beginner mistakes

Forgetting the blank line before a list.

This often renders badly:

Install the tool:
- Step one
- Step two

This is safer:

Install the tool:

- Step one
- Step two

Using tabs for nested lists.

Use two spaces for a simple nested list:

- Setup
  - Install Node
  - Install pnpm

Mixing a checklist marker with normal text.

This is a checkbox:

- [ ] Write docs

This is just text:

- [] Write docs

That missing space matters.

Checkpoint

Turn this rough note into Markdown:

Setup
install node
install pnpm
run pnpm install
warning this uses local environment variables

A clean answer:

## Setup

- Install Node
- Install pnpm
- Run `pnpm install`

> Warning: this uses local environment variables.

Next: Markdown 103 - links, images, tables, and footnotes.