Writing a Great README with Markdown

The Menu Card at the Restaurant Door

When you walk past a restaurant, the menu card near the entrance tells you everything before you sit down: what they serve, the prices, the timings. Without it, you would have to go inside and ask. Most people simply walk on to the next place.

A README is the menu card of your repository. It is a file called README.md that GitHub shows on the main page of the repository, under the list of files. It tells visitors what the project is, how to run it and who built it.

Asha’s college-fest-site is now on GitHub, and Ravi and Imran push to it every day. But a visitor sees only a list of files. In this lesson Asha writes a proper README using Markdown, a simple way to format text.

Why Recruiters Read Your README

A recruiter or senior developer looking at your GitHub profile has many profiles to check. They usually open a repository and read the README first. A good README shows that you can explain your work clearly, which is a skill every team values. A repository with no README looks unfinished, even if the code is excellent.

What Is Markdown?

Markdown is plain text with a few symbols that mean “make this a heading” or “make this bold”. The .md at the end of README.md stands for Markdown. You write it in any editor, and GitHub turns it into a neat page. GitHub uses a version called GitHub Flavored Markdown, which adds tables and task lists.

Headings, Paragraphs, Bold and Italics

# Utsav 2026
## Events
### Day 1

This is a normal paragraph. Leave an empty line
between paragraphs.

The fest has **free entry** for all students.
Registration closes *this Friday*.

• # makes the biggest heading, ## a smaller one, and so on down to ######. Always put a space after the hashes.
• An empty line starts a new paragraph.
• **text** makes text bold. *text* makes it italic.

Lists, Links and Images

Things to bring:

- College ID card
- Water bottle
- A friend

Steps to register:

1. Open the Events page
2. Choose an event
3. Fill in the form

Read the [fest rules](https://example.com/rules) before you register.

![Utsav poster](images/poster.png)

• Lines starting with - make a bullet list. Lines starting with 1., 2. make a numbered list.
• A link is [text to show](address).
• An image is the same with ! in front: ![description](path). The description helps people who use screen readers. The path can point to a file inside your repository, such as images/poster.png.

Code, Tables and Task Lists

Use `git pull` before you start work.

```bash
git clone https://github.com/asha-utsav-demo/college-fest-site.git
cd college-fest-site
```

| Event       | Day   | Venue          |
|-------------|-------|----------------|
| Dance       | Day 1 | Main auditorium |
| Coding quiz | Day 2 | Computer lab 3 |

- [x] Home page
- [x] Events page
- [ ] Sponsors page

• Single backticks `like this` mark a short piece of code inside a sentence.
• Three backticks on their own line start and end a code block. The word after the first three backticks (bash, html, css, js) tells GitHub which colours to use.
• A table uses | between columns and a line of dashes under the header row. The columns do not have to line up perfectly, but it is easier to read when they do.
• - [ ] is an empty checkbox and - [x] is a ticked one. This is called a task list.

What It Looks Like

GitHub turns Markdown into HTML, the same language you use for web pages. The box below is the HTML that matches most of the Markdown above. Press ▶ Try it yourself to see roughly how GitHub displays it (GitHub adds its own neat styling).

<h1>Utsav 2026</h1>
<p>The fest has <strong>free entry</strong> for all students.
Registration closes <em>this Friday</em>.</p>

<p>Things to bring:</p>
<ul>
  <li>College ID card</li>
  <li>Water bottle</li>
</ul>

<p>Read the <a href="https://example.com/rules">fest rules</a> before you register.</p>

<p>Use <code>git pull</code> before you start work.</p>

<table border="1" cellpadding="6">
  <tr><th>Event</th><th>Day</th><th>Venue</th></tr>
  <tr><td>Dance</td><td>Day 1</td><td>Main auditorium</td></tr>
  <tr><td>Coding quiz</td><td>Day 2</td><td>Computer lab 3</td></tr>
</table>

<ul style="list-style: none; padding-left: 0;">
  <li><input type="checkbox" checked disabled> Home page</li>
  <li><input type="checkbox" checked disabled> Events page</li>
  <li><input type="checkbox" disabled> Sponsors page</li>
</ul>

Preview Markdown in VS Code

You do not have to push to GitHub to see how your README looks. Open README.md in VS Code and press Ctrl + Shift + V (on a Mac, Cmd + Shift + V). A preview tab opens. To see the code and the preview side by side, press Ctrl + K, then let go and press V. The preview updates as you type.

VS Code’s preview is very close to GitHub’s, but not identical. A few GitHub features may look different in VS Code. Always have a quick look on GitHub after you push.

Real-Life Example: The README for college-fest-site

Asha creates README.md in the top folder of the project, next to index.html. She follows a simple plan that works for almost any project:

1. Title and description: what the project is, in one or two sentences.
2. Screenshot: one picture is worth many words. She saves it as images/screenshot.png in the repository.
3. Features: what the website can do.
4. How to run it: exact steps for someone new.
5. Built with: the technologies used.
6. Team: who did what, with links to their GitHub profiles.

# Utsav 2026: College Fest Website

The official website for **Utsav**, the annual fest of our college.
Students can see the events, check the schedule and register online.

![Screenshot of the Utsav home page](images/screenshot.png)

## Features

- Event list with dates, times and venues
- Registration form for each event
- Sponsors page
- Works well on mobile phones

## How to Run It

1. Clone the repository:

   ```bash
   git clone https://github.com/asha-utsav-demo/college-fest-site.git
   ```

2. Open the `college-fest-site` folder in VS Code.
3. Open `index.html` in your browser, or use the Live Server extension.

## Built With

- HTML
- CSS
- JavaScript

## Team

| Name        | Role                  | GitHub                                          |
|-------------|-----------------------|-------------------------------------------------|
| Asha Verma  | Project lead, design  | [@asha-utsav-demo](https://github.com/asha-utsav-demo)     |
| Ravi        | Events and forms      | [@ravi-utsav-demo](https://github.com/ravi-utsav-demo)         |
| Imran       | Sponsors and schedule | [@imran-utsav-demo](https://github.com/imran-utsav-demo) |

## To Do

- [x] Home page
- [x] Events page
- [ ] Photo gallery after the fest

Notice the code block inside step 1 of “How to Run It”: it is indented with three spaces so it stays part of the numbered list. She previews it in VS Code, then shares it:

# Save the README in Git and share it on GitHub
git add README.md
git commit -m "Add README with features, setup steps and team"
git push

You will see something like:

[main a1b2c3d] Add README with features, setup steps and team
 1 file changed, 42 insertions(+)
 create mode 100644 README.md
To https://github.com/asha-utsav-demo/college-fest-site.git
   e4f5a6b..a1b2c3d  main -> main

Now the repository page on GitHub shows a proper front page: a title, a screenshot, a features list, a table of the team and a to-do list with ticks.

Try these changes:

1. Add a “Fest Dates” section with a table of the three days.
2. Tick the “Photo gallery” task by changing [ ] to [x].
3. Add a link to the fest’s live website. You will publish it for free in the GitHub Pages lesson.

Badges (Optional)

Badges are small coloured labels at the top of a README, showing things like the technologies used or the project status. They are just images, often made by the free service shields.io, whose address follows the pattern badge/label-message-colour:

![HTML](https://img.shields.io/badge/HTML-5-orange)
![CSS](https://img.shields.io/badge/CSS-3-blue)
![Status](https://img.shields.io/badge/status-in%20progress-yellow)

Use two or three at most. A README with twenty badges is harder to read, not better.

Your Profile README

GitHub has a special trick for your profile page. If you create a public repository with exactly the same name as your username, its README appears at the top of your profile. Asha creates a repository called asha-utsav-demo (owned by asha-utsav-demo), ticks Add a README, and GitHub even shows a message that this is a special repository. She edits the README like this:

# Hi, I am Asha Verma

I am a second-year BCA student who loves building websites.

- Currently building: the website for Utsav, our college fest
- Learning: JavaScript and Git
- Reach me at: asha@example.com

## My Projects

- [college-fest-site](https://github.com/asha-utsav-demo/college-fest-site): website for our college fest

Keep it short and honest: who you are, what you are building, what you are learning, and links to your best projects.

Common Mistakes

• No space after #, and no empty lines. #Utsav may show as plain text, and a list right after a line of text may not show as a list in some viewers.
• The file has the wrong name or place. GitHub looks for README.md in the top folder of the repository. A readme.txt is shown only as plain text.
• Broken images. Paths are case-sensitive on GitHub: Images/Screenshot.PNG is not the same as images/screenshot.png. Also remember to commit the image file itself.
• Writing a README only for yourself. “My project” tells nobody anything. Write for a stranger who has never seen your code.

Here is the broken heading and list:

#Utsav 2026
Day 1:
- Dance
- Music

And the fixed version, with a space after # and empty lines around the list:

# Utsav 2026

Day 1:

- Dance
- Music

Practice Task: Write a README for Your Own Project

Pick any project of yours (your “About Me” page, or the practice-repo from earlier) and do this in VS Code and your terminal:

1. Create README.md in the top folder of the project.
2. Include a # title, a one-line description and an image line for a screenshot.
3. Add a “Features” bullet list and a numbered “How to Run It” list with one inline code word.
4. Add a small table and a task list with one ticked and one empty box.
5. Preview it with Ctrl + Shift + V, then commit and push, and check it on GitHub.
6. Bonus: create your profile README repository.

# In your own project folder (or the practice-repo from earlier lessons)

# 1. Create README.md in VS Code and write, for example:

# My Portfolio Site

A simple personal website where I share my projects.

![Screenshot](images/screenshot.png)

## Features

- About me section
- List of my projects
- Contact section

## How to Run It

1. Clone the repository
2. Open `index.html` in your browser

## Built With

| Technology | Used for  |
|------------|-----------|
| HTML       | Structure |
| CSS        | Design    |

## To Do

- [x] About section
- [ ] Projects section

# 2. Preview it: Ctrl + Shift + V (Cmd + Shift + V on Mac)

# 3. Commit and push
git add README.md
git commit -m "Add README"
git push

Key Takeaways

• A README is the front page of your repository. GitHub shows README.md under the file list, and recruiters read it first.
• Markdown basics: # headings, **bold**, *italic*, - and 1. lists, [link](url) and ![image](path).
• Use backticks for code, | for tables and - [ ] for task lists.
• A good README has a title, description, screenshot, features, how to run, technologies and team.
• Preview with Ctrl + Shift + V in VS Code. A repository named after your username gives you a profile README.