Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
A README.md 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

The What

A little info about your project and/or overview that explains what the project is about.

The Why

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

Build Status and Code Style

Build status of continuous integration (travis, appveyor, etc.) and code style (xo, standard etc.). This will help others who wish to contribute to your project. You can include badges here as well, just don't go too crazy or it looks like a mess.

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. CONTRIBUTING.md, USAGE.md, etc.).

Screenshots/Demo

Include logo, demo, screenshot etc.

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)

Features

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.

Prerequisites

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

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

Installation

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.

Tests

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.

Deployment

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

Usage

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.

Contributing

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.

Authors

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.

Contributors

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

Acknowledgments

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

License

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 LICENSE.md file for details.


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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment