Markdown and README.md Files

Codecademy Team
This article covers what a README.md file is and how its contents are written using a language called Markdown.

Imagine you’re working on a project and a friend of yours would like to contribute to the project. Wonderful! You’d likely set up a chat with them to explain what the project is, how its contents are structured, and the right ways to contribute. But, what if ten friends express interest? What if the project is open source, and it’s actually a multitude of strangers over the internet? Chatting with everyone individually would take far too much time. It would be much more time-efficient to write down that overview and make it available as part of the project.

Writing down an overview for a project has become standard practice for virtually all software projects – especially those that have been open sourced. Software developers have standardized placing project overviews in README, or “read me” files. At the very least, a typical README includes:

  • The name of the project
  • What the project does
  • How to get started contributing to the project
  • Links to other relevant documentation, such as architecture overviews

Popular online source code hosting websites such as GitHub will display the contents of a README file at the project link. For example, if we visit github.com/Codecademy/docs and scroll down past the list of files, we’ll see the README.md, which contains an overview of that Docs project, including what it is, who is maintaining it, and how to contribute The contents should be readable to all, not just programmers!

Introducing Markdown

Codecademy Docs and many other projects store their README with an “.md” file extension, which means the file is written in a markup language called Markdown. Using Markdown, writers can specify text formatting with characters such as asterisks and underscores, as well as limited amounts of HTML (the programming language used for websites).

For example, the following markdown code would make a list with some bold text in each element:

- **Apple**: Malus domestica
- **Banana**: Musa acuminata
- **Cherry**: Prunus cerasus

Websites such as GitHub would render that markdown code roughly like so:

  • Apple: Malus domestica
  • Banana: Musa acuminata
  • Cherry: Prunus cerasus

Markdown is popular with open source projects because it allows rich text formatting that can properly display bits of code. Other alternatives such as HTML tend to have more powerful text formatting options but are much more effort to code and much less readable.

History of Markdown

Markdown was first created in 2004 by the developers Aaron Swartz and John Gruber. There are now Markdown renderers in many programming languages and platforms such as Discord, GitHub, Reddit, and Slack. Although Markdown generally works similarly in all of those renderers, there were some variants across platforms at first The creators of Markdown wanted it to be flexible enough that platforms could customize it as they needed.

The downside, however, was that writers of Markdown would need to change their text based on which Markdown variant it was to be rendered in. That isn’t always possible when a single “.md” file such as a README.md is meant to be used for all platforms.

CommonMark, spearheaded by engineers at Markdown-hosting platforms, was created in 2014 to specifies a general standard of how Markdown should be written.

GitHub Flavored Markdown

GitHub’s slight variant of CommonMark is one you’re likely to come across often on your open source journey. It builds on CommonMark by adding GitHub-specific features:

  • Striking through text using two tildas, ~~, on each side of the text:
    Before ~~strikethrough text~~ after
  • Linking to issues and pull requests on GitHub within a repository with a hashtag before their number:
    #123
  • Task list items, which are checklists that use - [ ] to indicate unchecked items and - [x] to indicate checked items:
    - [ ] Unchecked
    - [x] Checked
  • Tables specified using | and - characters to draw rows and columns:
    | foo | bar |
    | --- | --- |
    | baz | bim |
    GitHub Flavored Markdown also trims out most HTML from Markdown documents. This will strip out any potentially unsafe content such as JavaScript scripts that could inject malicious code to the page. Limited HTML constructs such as <table> tags and some style attributes such as align="center" are allowed.

All .md files on GitHub can be viewed as their GitHub Flavored Markdown output by visiting the file in GitHub’s file viewer, such as the Codecademy Docs README.md. You can also see the raw input file with the Raw link on that page:

https://raw.githubusercontent.com/Codecademy/docs/main/README.md. 

After writing a few README.md and other .md files, you’ll get the hang of Markdown! It’s extremely powerful and lets you clearly present your coding work.