What Is a README.md?

A README.md is a plain-text file that explains a project. It is written in Markdown, a lightweight formatting language that stays readable as text and can also be rendered with headings, lists, tables, and links.

Why projects use a README

A README is usually the first file someone opens in a repository. It explains what the project does, how to install it, and how to use it. On GitHub and many other code hosts, a file named README.md is displayed on the repository homepage.

The content can be short. A small project might only need a title, one paragraph, and a few setup steps. A larger project may include screenshots, configuration details, contributing notes, and a license section.

What is Markdown?

Markdown is a way to add structure to plain text. Instead of clicking toolbar buttons, you type simple markers: # for a heading, - for a list item, and backticks for code. The file remains easy to read in a text editor, and a Markdown viewer can turn those markers into formatted HTML.

Common Markdown syntax

Headings

Start a heading with one or more hash marks. More hash marks create a lower level.

# Project title

## Installation

### Configuration

Lists

Use dashes or numbers at the start of a line to create a list.

- First item
- Second item
- Third item

Code blocks

Wrap a block of code in three backticks. You can add a language name after the opening backticks to enable syntax highlighting.

```bash
npm install
```

Tables

Separate columns with pipes and use a row of dashes below the header. Tables are useful for commands, options, and short comparisons.

| Command | What it does |
| --- | --- |
| npm start | Run the app |
| npm run build | Create a build |

Links

Put the link text in square brackets and the address in parentheses. The result is a clickable link when the Markdown is rendered.

[Glance](https://glance.niranjans.tech/)

How to open a README.md on Windows

You can open the file in Notepad to read the raw text, use the preview in Visual Studio Code, or use a dedicated Markdown viewer. The guide to opening a .md file on Windows compares those options and their tradeoffs.

Glance is a Markdown viewer for Windows that opens single files and whole folders. It is source-available and free for noncommercial use.

Read README files without a browser tab.
Glance is free for noncommercial use.

See the download options