Write a README in Markdown
25 min · Beginner
Need help? Ask a tutor on WhatsApp (opens in a new tab)Showing steps for Windows. They are marked “On Windows” below.
A README is the first thing anyone sees when they open your repository. A teacher or recruiter reads it to learn what your project does and how to run it, often before they open a single code file.
README: your project's front page
A README is a text file, usually README.md, in the top folder of a project that explains what the project is, how to run it and how to use it. GitHub shows it, formatted, below the file list.
Without a README, a visitor sees only a list of file names and leaves. With one, they know in ten seconds what shop-bill does and how to try it.
The .md ending means the file is written in Markdown, so GitHub shows real headings, lists and code boxes instead of plain text.
Markdown: headings, lists and bold
Markdown is a simple way to format plain text with a few symbols: # for a heading, - for a list item, ** for bold and backticks for code. Files end in .md, and GitHub shows them formatted.
A line that starts with # and a space is a heading; ## is a smaller one. - starts a bullet, 1. a numbered item, and **two stars** make bold text. Leave an empty line between blocks.
Example 1 · Headings, lists and bold
# Shop BillKeeps the bill for a **shop order**.## Features- Notebook, pen and ruler prices- Total in rupees## Steps1. Open `bill.txt`.2. Check the total.Shop Bill <- big heading
Keeps the bill for a shop order. ("shop order" in bold)
Features <- smaller heading
• Notebook, pen and ruler prices
• Total in rupees
Steps <- smaller heading
1. Open bill.txt.
2. Check the total.What this code does
#makes the page title and##the section headings under it. The space after#is required.-makes bullets and1.a numbered list;**shop order**shows in bold without the stars.- The empty lines keep each block separate. Two lines with no empty line between them join into one paragraph.
Code blocks and links
Commands must be copied exactly, so they go in code. One backtick on each side marks inline code. Three backticks on their own lines, above and below, make a code block; a link is [text](address).
Example 2 · Inline code, a code block and a link
Run it with Python:```bashpython bill.py```Or with Java 17 or newer:```bashjava Bill.java```Get Python from the [Python website](https://www.python.org/downloads/).Run it with Python:
┌────────────────────┐
│ python bill.py │ <- code box with a Copy button
└────────────────────┘
Or with Java 17 or newer:
┌────────────────────┐
│ java Bill.java │ <- code box with a Copy button
└────────────────────┘
Get Python from the Python website. ("Python website" is a link)What this code does
- Single backticks make inline code inside a sentence.
- Three backticks on their own lines make a code box;
bashafter the first three colours the command. Use the commands of your own language here. [text](address)shows only the text, as a link. An image is the same with!in front:.
What a good README has
A good README answers a visitor's questions in order: what is it, how do I use or run it, what does a sample look like, who made it. Here is Priya's full README for shop-bill.
Example 3 · Priya's README.md
# Shop BillA small project that keeps a shop order and its bill in one text file.## How to useOpen `bill.txt` in any text editor, or print it in a terminal:```bashcat bill.txt```## Sample bill```textNotebook x 2: Rs. 30Pen x 3: Rs. 36Ruler x 1: Rs. 20Total to pay: Rs. 86```## What I learned- Saving a project with Git commits- Writing a README in Markdown## AuthorPriya Sharma ([GitHub profile](https://github.com/priya-dev))Shop Bill <- big heading
A small project that keeps a shop order and its bill in one text file.
How to use <- heading
Open bill.txt in any text editor, or print it in a terminal:
[code box] cat bill.txt
Sample bill <- heading
[code box] the four lines of the bill
What I learned <- heading
• Saving a project with Git commits
• Writing a README in Markdown
Author <- heading
Priya Sharma (GitHub profile) ("GitHub profile" is a link)What this code does
- The order matches a visitor's questions: what it is, how to use or run it, what a sample looks like, who made it. A code project lists its real run commands here, such as
python app.pyorjava App.java. - The sample bill is copied from the real
bill.txt, so anyone who follows the steps sees exactly the same lines. - The
textcode block keeps output exactly as printed, with no colours.
Add a licence too, so people know what they may do with your code: on GitHub, Add file → Create new file, name it LICENSE, then Choose a license template. MIT is the usual choice for student projects. With no licence, people may read your public code but have no right to reuse it.
Preview, commit and push
Markdown never shows an error: a mistake just looks wrong on GitHub. So preview the file before you commit it, then commit and push it like any other file.
On Windows
In VS Code, open README.md and press Ctrl + Shift + V for the preview. IDEs such as IntelliJ IDEA and PyCharm show a preview beside .md files. Then, in PowerShell:
PS C:\Users\Priya\shop-bill> git status --shortPS C:\Users\Priya\shop-bill> git add README.mdPS C:\Users\Priya\shop-bill> git commit -m "Write README with run steps"PS C:\Users\Priya\shop-bill> git pushOutput M README.md [main add90c1] Write README with run steps 1 file changed, 29 insertions(+) Enumerating objects: 5, done. Counting objects: 100% (5/5), done. Delta compression using up to 12 threads Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 567 bytes | 567.00 KiB/s, done. Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0) To https://github.com/priya-dev/shop-bill.git 13ec897..add90c1 main -> main
M README.md: the README changed and is not committed yet.29 insertions(+): the new README lines. The push sends that commit to GitHub.- Open the repository page: the formatted README is shown under the file list.
priya-dev/priya-dev) with a README.md. Two or three lines about you and links to your best projects are enough.Next step
Check your understanding
8 quick questions