Markdown is a simple way to add formatting to plain-text files.

A Markdown file normally uses the file extension:

.md

For example:

README.md

Markdown files can contain headings, lists, links, bold text, code examples, and other formatting. However, the file itself remains plain text and can be opened in a basic text editor.

Why GitHub Uses Markdown

GitHub can recognize Markdown formatting and display it as a properly formatted web page.

This makes Markdown useful for:

• Project descriptions
• Setup instructions
• Documentation
• Notes
• Lists of tasks
• Code examples

Markdown is widely used on GitHub because it is easier to write than HTML but still produces clear, readable pages.

The README File

One of the most common Markdown files in a GitHub repository is:

README.md

A README file usually introduces the project. It may explain what the project does, what technology it uses, how to install it, and how to run it.

When GitHub finds a README file in the main folder of a repository, it normally displays the contents below the list of files and folders.

This means the README becomes a type of front page for the project.

README.txt Versus README.md

A plain-text README may be named:

README.txt

GitHub can display the text, but the formatting options are limited.

A Markdown README is named:

README.md

The Markdown version can include formatted headings, lists, links, and code blocks.

For most GitHub projects, README.md is the more useful choice.

A Simple Markdown Example

The following text could be placed inside a README.md file:

# The Title of My Project

A Flask-based platform for exploring social enterprise and social innovation.

## Technology

- Python
- Flask
- SQLite
- Tailwind CSS

## Project Status

The project is currently under development.

GitHub would display the lines beginning with # and ## as headings. The lines beginning with hyphens would appear as a list.

Creating a Markdown File

You can create a Markdown file in Visual Studio Code, Notepad, or another text editor.

Save the file with the .md extension, such as:

README.md

After committing and pushing the file to GitHub, GitHub will display the formatted version automatically.

Markdown Is Still Plain Text

Markdown may look formatted on GitHub, but the original file remains plain text.

This makes Markdown files easy to:

• Edit
• Search
• Store in Git
• Compare between versions
• Use on different computers

Markdown provides a useful balance between simple plain text and readable formatted documentation.