Articles

Markdown and README.md Files

.md files are Markdown documents that use basic symbols (like # for headings and * for lists) to create human-readable formatted text that can be converted to HTML.

The most common .md file you’ll encounter is the README.md file - the standard documentation file for software projects that explains what, why, and how of a project.

Let’s start by understanding what a README.md file is.

  • Free course

    Learn GitHub: Introduction

    Learn how to use GitHub, a service that allows you to host and share your code.
    • Beginner Friendly.
      1 hour
  • Skill path

    Software Engineering for Data Scientists

    Data Scientists often work with engineering teams. Learn the software engineering skills you need to bridge the gap between data science and
    • Includes 7 Courses
    • With Certificate
    • Intermediate.
      22 hours

What is a README.md file?

A README.md file is a plain text file explaining a project’s what, why, and how. It’s usually the first thing people see when they open a repository on GitHub, GitLab, or Bitbucket.

The name breaks down into two parts:

  • README: This is the traditional name for documentation files. It means “Read this first”.

  • .md: This is the md extension file that tells systems the file is written in markdown.

Because of its role, the README extension file becomes the core documentation hub for your project as it can save hours of confusion and repeated explanations.

Now that you know what a README file is, let’s understand the language used within it.

What is markdown?

Markdown is a lightweight formatting language that lets you style text using plain characters. It was created to be readable, without looking like a bunch of code, and when rendered, it looks clean and structured.

You’ll know you’re dealing with a Markdown file if the file ends with .md, like the README.md we just discussed. .md files are used everywhere from GitHub repos to static site generators, documentation tools, blog platforms, and more.

Markdown has a very basic syntax, for example:

  • # for a heading
  • * for a bullet point
  • `​`` for a code block

Let’s walk through basic Markdown syntax with examples you can use in your own README.md file.

Basic markdown syntax for .md file

Here’s a quick guide to the commonly used Markdown syntax, valid for any README extension file or Markdown file you’re putting together.

Headings

Use # symbols to create headings. The number of # symbols determines the level. 

# Project Title (H1)  
## Section Title (H2)  
### Subsection (H3)

This breaks your README file into different sections.

Bold and italic text

To add emphasis, use asterisks or underscores. 

*italic* or _italic_  
**bold** or __bold__  
***bold and italic***

These are used to highlight key points or commands.

Lists

To create unordered lists: 

- Item 1 
- Item 2 
  - Sub-item

For ordered lists: 

1. Step one 
2. Step two 
3. Step three

To insert a link to the file: 

[Link text](https://example.com)

To insert an image into the file: 

![Alt text](image.png)

Code snippets

To write the code in markdown, use the `​`` (backticks): 

```py 
def greet(name):  
  return f"Hello, {name}"
```

Blockquotes

Blockquotes help highlight tips or pull in citations in your md file. 

> This is a note or a quote.

Horizontal rule

Use this to break sections in your Markdown file. 

---

These fundamental elements structure a transparent, helpful README.md file.

But you might still have a question: what should go into your README.md file?

What should be included in a README.md file?

A good README.md file answers questions before they’re asked. Common questions are what it does and how to get started. Here’s what you should include in your README extension file:

1. Project title: Start strong by adding the name of your project as a top-level heading. Optionally, include a one-liner that sums it up. 

# Weather App  
A simple CLI tool to check the weather by city name.

2. Description: Explain what the project does and why it exists. Keep it short, but informative at the same time. 

This tool fetches live weather data using the OpenWeatherMap API. Built in Python, it’s meant for quick use in terminal environments.

3. Installation requirements: Explain to users how to install or set up the project using steps and code blocks. 

1. Clone the repo  
2. Install dependencies  
3. Run the app 


```bash 
git clone https://github.com/username/weather-app.git 
cd weather-app 
pip install -r requirements.txt
```

4. Usage: Show how the project works. Include commands, screenshots, or output examples. 

Run the following command:  


```bash  
python weather.py Mumbai 
```

5. Screenshots (if applicable): Sometimes a quick image says more than a paragraph.

You can use the image syntax we discussed earlier.

6. Contribution: If you allow contributions, add a short guide: 

Want to contribute? Fork the repo, make changes, and open a pull request. See CONTRIBUTING.md for more.

7. License: Be clear about how others can use your code. 

MIT License. See the LICENSE file for details.

8. Contact/credits: You can optionally add your name, email, or links to your portfolio. 

Created by [Your Name](https://yourwebsite.com)  
For support, contact [email protected]

You don’t need each of these in every .md file, but they cover the bases. Let’s combine it with a full sample README.md that you can use as a template.

Sample README.md file for a project

Here is a sample you can use for your project’s starting point. It uses simple Markdown syntax and follows the structure of a typical README extension file. 

# TaskTracker  
A minimal command-line app to track daily tasks, built in Python.  


## Features  
- Add, view, and complete tasks  
- Save task history between sessions  
- Lightweight and beginner-friendly  


## Installation  
Clone the repository and install the required packages:  


```bash  
git clone https://github.com/yourusername/tasktracker.git  
cd tasktracker  
pip install -r requirements.txt 
``` 


## Usage  


To add a task: 


```bash 
python tasktracker.py add "Write blog post" 
``` 


To view tasks: 


```bash 
python tasktracker.py list 
``` 


To mark a task as done: 


```bash 
python tasktracker.py done 1 
``` 


## Contributing  


Found a bug or have an idea? Fork the repo, make changes, and submit a pull request.  


Please read `CONTRIBUTING.md` for guidelines.  


## License  


This project is licensed under the MIT License.  
See the `LICENSE` file for details.  


## Contact  


Created by [Author name]([email protected])  
Feel free to reach out with questions or suggestions.

A well-written .md file like this turns your project from code-only to contributor-ready.

Conclusion

In this article, you learned what a README.md file is, how .md files work, and why they matter. You saw how to use basic Markdown syntax and what to include in a solid readme extension file. The sample README gives you a practical template to get started.

To take it a step further, explore Codecademy’s Learn GitHub: Introduction course.

Frequently asked questions

1. What is a README file used for?

To describe a project, mainly its purpose, setup, usage, and contribution guidelines.

2. What is .md in Git?

It stands for Markdown, a plain text format used for writing formatted documentation in Git repositories.

3. What is the difference between Markdown and markup?

Markdown is a lightweight markup language. Markup is a broader category that includes complex languages like HTML and XML.

4. Is Markdown better than HTML?

Yes, Markdown is better for documentation. It’s simpler and easier to read and write. However, HTML is more powerful for complete web design.

5. Does Google use Markdown?

Yes. Google uses Markdown in many of its open-source and internal documentation tools.

Codecademy Team

'The Codecademy Team, composed of experienced educators and tech experts, is dedicated to making tech skills accessible to all. We empower learners worldwide with expert-reviewed content that develops and enhances the technical skills needed to advance and succeed in their careers.'

Meet the full team

Related articles

Learn more on Codecademy

  • Free course

    Learn GitHub: Introduction

    Learn how to use GitHub, a service that allows you to host and share your code.
    • Beginner Friendly.
      1 hour
  • Skill path

    Software Engineering for Data Scientists

    Data Scientists often work with engineering teams. Learn the software engineering skills you need to bridge the gap between data science and
    • Includes 7 Courses
    • With Certificate
    • Intermediate.
      22 hours
  • Course

    Learn Intermediate Go: File Handling

    Learn about handling files and directories in this Intermediate Go course.
    • With Certificate
    • Intermediate.
      1 hour
Contents