Skip to content

Instantly share code, notes, and snippets.

Last active April 3, 2024 17:19
Show Gist options
  • Star 17 You must be signed in to star a gist
  • Fork 6 You must be signed in to fork a gist
  • Save meg-gutshall/ac48ef47d9d7b750c354c990c90a2a8f to your computer and use it in GitHub Desktop.
Save meg-gutshall/ac48ef47d9d7b750c354c990c90a2a8f to your computer and use it in GitHub Desktop.
A template I created from a few different resources. It's a work in progress. ;) Please comment below with any suggestions for edits!

Project Title

Description: A few sentences about your project and/or overview that explains what your project is about.

Build Status and Code Style

Build status of continuous integration (travis, appveyor, etc.) and code style (xo, standard etc.). It's common to include status badges here so contributors and prospective end-users can see the status of your project at a glance. Just don't go too crazy or it will look like a mess.

Find status badges at the follow sites:

Table of Contents

Depending on how long the README is, add in a ToC or even abstract some sections away to different markdown files (i.e.,, etc.).


Include logo, demo, screenshot etc.


What makes your project stand out? What pain points does it solve for the prospective user? Compare it to competitor apps/tools to show how it is different/better.

Example Code

Show what your code does as concisely as possible. Users should be able to figure out how your project solves their problem by looking at the example. Also include the example code as a file in your repo (named example.js or in an example directory) so that users can run the code if they clone down the repository.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.


List which technologies the user needs to install the software and how to install these dependencies.

< Software Name >

Links to resources and installation instructions. Include code examples. Break instructions down by operating system if necessary.

For Mac Users
For Windows Users
For Linux Users


This section tells the user how to get a local environment running. Be sure to include specific step-by-step instructions for the installation process to accommodate coders of all levels. This section will vary greatly depending on the type of code the repository contains. For example, a Node package is usually installed by typing npm install <package-name> in the terminal, whereas other projects you may have to fork and clone down the repository. In both cases the user needs to have the requisite technology installed to run to code. Even with a Docker image, the user still needs to be able to run Docker on their machine. Keep this in mind when writing out the "Prerequisites" and "Installation" sections.

API Reference/Documentation

Depending on the size of the project, if it is small and simple enough the reference docs can be added to the README. For medium size to larger projects it is important to at least provide a link to where the API reference docs live.


Explain how to run the automated tests for this system.

End to End Tests

Explain what these tests test and why. Include code examples.

Coding Style Tests

Explain what these tests test and why. Include code examples.


Add additional notes about how to deploy this on a live system.


End with an example of getting some seed data out of the system or using it for a demo. Add screenshots, video links, and/or GIFs in this section to make your usage instructions as clear as possible to the user.

Built With

List of tech languages, frameworks/libraries, and tools used

  • [Language](link to language documentation)
  • [Framework](link to framework documentation)
  • [Database](link to database documentation)

The Why

A short description of the motivation behind the creation and maintenance of the project. This should explain why the project exists.


Add more detailed instructions for open-source projects. It's a good idea to include a code of conduct as well as resource links as to where absolute beginners can go to learn how to contribute to open source. Here's a great place to start. I personally like the Contributor Covenant and use the below statement as my default. I intend to expand on it once I create an open-source project truly worthy of others' contributions.

Issues and pull requests are welcome at . This project as well as all other content on my GitHub are intended to be safe, welcoming, and open for collaboration. Users are expected to adhere to the Contributor Covenant code of conduct and those that do not will be reported and blocked. I got no time for that nonsense.


Include your name and any links to your social media, contact info, or websites that you'd like. Don't forget to s/o your contributors here too!

Meg Gutshall

See also the list of contributors who participated in this project.


Add a list of contributors here. You may want to feature some who have really stood out.


  • Hat tip to anyone whose code was used
  • Inspiration
  • Anything else that seems useful


Include your license here. This is an absolute must as some users require that all services they include in their project have a license that matches their own. The MIT License is GitHub's recommendation and probably the most common one you'll see in repos, but there are other options available—copyleft, anybody?—and that's not even an exhaustive list, just the most popular licenses on GitHub.

This project is licensed under the MIT License - see the file for details.

My Example READMEs

Template Resources

Articles About Writing READMEs

README Templates that Won the Meg Stamp of Approval

Repository Licenses

Open Source

  • Open Source Guides: Open source software is made by people just like you. Learn how to launch and grow your project.
Copy link

Thank you, Meg. I forked this to use going forward.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment