Need AI Training/Help?CloudYeti.io/meet
MarkdownMe
Markdown editor guide

How to Write a README in Markdown

Structure a clear README.md with a title, badges, install and usage sections, and a live preview before you commit.

Direct answer

A strong README opens with an H1 project title and one-line description, then covers Installation, Usage, Configuration, and License as H2 sections. Write it in a live editor so you can confirm code blocks, links, and tables render before committing README.md to your repo.

Open the Markdown Editor

When to use this

  • You are starting a new repository and need a README.md from scratch.
  • Your current README renders badly on GitHub and you want to fix the structure.
  • You want to preview headings, code blocks, and tables before pushing.

Steps

  1. Start with a single H1 title and a one-sentence description underneath.
  2. Add an H2 Installation section with a fenced code block for the install command.
  3. Add an H2 Usage section with a minimal, copy-ready example.
  4. List configuration options in a Markdown table if there are more than two.
  5. Close with License and contribution links.
  6. Preview the rendered README, then copy or download it as README.md.

Example

Markdown you type
# ProjectName

One-line description of what this project does.

## Installation

```bash
npm install projectname
```

## Usage

```js
import { run } from "projectname";
run();
```

## Configuration

| Option | Default | Description |
| --- | --- | --- |
| `debug` | `false` | Log verbose output |
| `retries` | `3` | Retry count on failure |

## License

MIT
How it renders
ProjectName  (large H1 title)

One-line description of what this project does.

Installation  (H2)
  npm install projectname   (copy button on GitHub)

Usage  (H2)
  import { run } from "projectname";
  run();

Configuration  (H2)
  Option    | Default | Description
  debug     | false   | Log verbose output
  retries   | 3       | Retry count on failure

License  (H2)
  MIT

Common mistakes

  • Use only one H1 in a README; put every other section under H2 so the GitHub outline stays readable.
  • Always label fenced code blocks with a language (bash, js, python) so GitHub highlights them.
  • Avoid pasting raw HTML tables when a Markdown pipe table renders more reliably across viewers.

FAQ

What sections should every README include?
At minimum: a title and description, Installation, Usage, and License. Add Configuration, Contributing, and Badges when the project needs them.
How do I preview a README before pushing to GitHub?
Write it in a live Markdown editor with a preview pane. You will see the exact heading sizes, code highlighting, and table alignment before you commit README.md.
Should a README use one H1 or several?
Use exactly one H1 for the project name. GitHub builds the sidebar outline from your headings, so multiple H1s make the outline confusing.

Related Markdown guides

Convert a README to an HTML Page

Related Markdown editor guides

Markdown Syntax Cheat Sheet

A copy-ready Markdown cheat sheet covering headings, bold, italics, lists, links, images, code, tables, and blockquotes.

Markdown Table Syntax

Write Markdown tables with pipes and dashes, set column alignment, and keep them readable in the editor before you paste.

Markdown for GitHub Comments

Format GitHub issue and pull request comments with task lists, code blocks, mentions, and collapsible sections.

Markdown Editor With Live Preview Online

Edit Markdown on the left and see the rendered result on the right in real time, with no login and browser-only drafts.

How to Add Links and Images in Markdown

Add inline links, reference links, and images in Markdown, including titles and clickable image links.

Markdown Task List and Checkboxes

Create checkbox task lists in Markdown for READMEs, GitHub issues, and personal to-do notes with live preview.

Markdown Code Blocks and Syntax Highlighting

Add fenced code blocks with a language for syntax highlighting, plus inline code, in Markdown.