This is the Ultimate README Template for creating project READMEs. It is the README of README! If you want to create a README for your project, this is the place to start.
☝️ You can include badges at the top of your README to provide some quick information about your project. For instance, here are some badges from the FiftyOne project.
This is the place to describe your project. You can include any information that you think is relevant. Here are some questions to consider:
- What does it do?
- Why did you make it?
- What problem does it solve?
- What are the technologies you used?
- What are the features?
- What are the future features?
- What is the roadmap?
If you want to include a change log, this is the place to do it.
11/29/2023 - Project Launched 12/01/2023 - Added Feature X 12/03/2023 - Added Feature Y
If you want to include a roadmap, this is the place to do it.
- Feature X
- Feature Y
- Feature Z
This is the place to describe how to install your project. What are the steps? What are the requirements? What are the dependencies? What is the order of the steps? What are the commands?
Note: You may want to include an Installation.md file in your repository!
Versions, distros, etc.
What are the hardware requirements? What are the minimum requirements? What are the recommended requirements? What are the ideal requirements?
What are the environment variables? What are the default values? What are the recommended values? What are the required values? What are the optional values?
What are the steps? What are the commands? What are the options? What are the features?
If there's a simple way to get started, such as pip install or docker run, you can include a quick start section. This is a great way to get people to try out your project!
This is the place to describe how to use your project. What are the steps? What are the commands? What are the options? What are the features? What are the examples? What are the screenshots? What are the GIFs?
This is the place to describe how to contribute to your project. What are the guidelines? What are the expectations? What are the steps? What are the commands? What are the requirements? What are the reccomendations? What are the resources? What is the code of conduct?
You can also include a Contributing.md file in your repository!
It is also often helpful to include a listing of contributors in your README. You can do this manually, or you can use a tool like Contrib.rocks.
For instance, here is a list of contributors to the FiftyOne project:
This is the place to describe the license for your project. What are the terms? What are the limitations? What are the conditions? What are the permissions? What are the notices? What are the disclaimers? What are the badges?
Badges are a great way to add some color and information to your README. Here are some great resources for badges:
Badge Resources (click to expand)
Github has a number of badges that you can add to your README.
Here are some of the most popular:
You can add a badge to your README that shows the status of your build. This is a great way to show the status of your CI/CD pipeline.
Build: when you push to your repository, your CI/CD pipeline will run. If the build is successful, the badge will show a green checkmark. If the build fails, the badge will show a red X.
You can add a badge to your README that shows the code coverage of your tests. This is a great way to show the quality of your tests.
Code Coverage: when you push to your repository, your CI/CD pipeline will run your tests. If the code coverage is above a certain threshold, the badge will show a green checkmark. If the code coverage is below a certain threshold, the badge will show a red X.
You can add a badge to your README that shows the number of downloads of your project. This is a great way to show the popularity of your project.
Downloads: this badge will show the number of downloads of your project from PyPI.
You can add a badge to your README that shows the number of pulls of your Docker image. This is a great way to show the popularity of your project.
Docker Pulls: this badge will show the number of pulls of your Docker image from Docker Hub.
You can add a badge to your README that shows the license of your project. This is a great way to show the license of your project.
License: this badge will show the license of your project.
You can add a badge to your README that shows the number of views of your project. This is a great way to show the popularity of your project.
View Count: this badge will show the number of views of your project recorded that day.
☝️ This is for this repo, not the FiftyOne repo!
You can add badges to your README that link to your social media accounts. This is a great way to show your social media presence.
Here are some of the most popular:
GIFs are a great way to add some life to your README.
If you want to use an existing GIF, you can find some great options:
Alternatively, you may want to record your own GIF. Here are some great tools for recording GIFs:
GIF Recording Tools (click to expand)
- Giphy Capture
- LICEcap
- ScreenToGif
- Gifox Paid, but very good
Github allows you to embed GIFs in your README, but the maximum size is 10MB. If your GIF is larger than 10MB, you can use a tool like XConvert to compress it. You can also compress a GIF locally using ffmpeg.
To embed a GIF in your README, simply drag and drop the GIF into the README in edit mode. Github will automatically upload the GIF and embed it in the README.
Note: You technically can use the markdown syntax to embed a GIF, but then the file will add to the size of your repository. If you drag and drop the GIF, it will be uploaded to Github's servers and will not add to the size of your repository.
when you embed a GIF with the .gif extension in your README, you will need to press play to see the animation. If you want the GIF to animate automatically, you can encode it as an image with the .png extension. To do this, simply change the extension of the GIF from .gif to .png. This will cause the GIF to animate automatically!
Here's an example from the amazing Tuana Çelik!
You can add links to your README using the markdown syntax:
[Link Text](https://www.example.com)Alternatively, you can use HTML:
<a href="https://www.example.com">Link Text</a>You can also add relative links to your README using the syntax:
[Relative Link Text](./path/to/file)For instance, if you want to link to the data.csv file in your repository containing papers, you can use the syntax:
[data.csv](./automation/data.csv)You can add anchor links to your README using the syntax:
[Anchor Link Text](#anchor-name)For instance, if you want to link to the Usage section of your README, you can use the syntax:
[Usage](#usage)Note: If your section header has emojis or special characters, you will need to remove them from the anchor link. For instance, if you want to link to the Installation section of your README, you can would use the syntax:
[Installation](#-installation)You can add direct links to issues and pull requests using the syntax:
[Issue #num](https://github.com/user/repo/issues/num)To link to issue #1 in this repository, you can use the syntax:
[Issue #1](https://github.com/jacobmarks/ultimate-project-readme/issues/1)You can add code blocks to your README using the markdown syntax:
```
print("Hello World!")
```
👇
print("Hello World!")
You can also add syntax highlighting to your code blocks by specifying the language:
```python
print("Hello World!")
```
👇
print("Hello World!")```javascript
console.log("Hello World!")
```
👇
console.log("Hello World!")You can add tables to your README using the markdown syntax:
| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Row 1 | Row 1 | Row 1 |
| Row 2 | Row 2 | Row 2 |
| Row 3 | Row 3 | Row 3 |👇
| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Row 1 | Row 1 | Row 1 |
| Row 2 | Row 2 | Row 2 |
| Row 3 | Row 3 | Row 3 |
You can use tools like Tables Generator to generate these tables.
You can also use HTML to create tables:
<table>
<tr>
<th>Column 1</th>
<th>Column 2</th>
<th>Column 3</th>
</tr>
<tr>
<td>Row 1</td>
<td>Row 1</td>
<td>Row 1</td>
</tr>
<tr>
<td>Row 2</td>
<td>Row 2</td>
<td>Row 2</td>
</tr>
<tr>
<td>Row 3</td>
<td>Row 3</td>
<td>Row 3</td>
</tr>
</table>👇
| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Row 1 | Row 1 | Row 1 |
| Row 2 | Row 2 | Row 2 |
| Row 3 | Row 3 | Row 3 |
You can add multi-line cells to your tables using the syntax:
| Header 1 | Header 2 |
|----------|----------|
| Line 1<br>Line 2 | Text |👇
| Header 1 | Header 2 |
|---|---|
| Line 1 Line 2 |
Text |
You can align the text in your tables using the syntax:
| Left-aligned | Center-aligned | Right-aligned |
| :----------- | :------------: | ------------: |
| text | text | text |
👇
| Left-aligned | Center-aligned | Right-aligned |
|---|---|---|
| text | text | text |
Sometimes, you may have data that is changing frequently, and you want to display it in a table in your README. For instance, you may have a table of the latest version numbers of your project's dependencies. In this case, you may want to automate the generation of the table from a CSV file.
| Title | Dataset |
|---|---|
| MVImgNet: A Large-scale Dataset of Multi-view Images | MVImgNet |
| GeoNet: Benchmarking Unsupervised Adaptation across Geographies | GeoNet |
| Joint HDR Denoising and Fusion: A Real-World Mobile HDR Image Dataset | Mobile-HDR |
| Spring: A High-Resolution High-Detail Dataset and Benchmark for Scene Flow, Optical Flow and Stereo | Spring |
| ImageNet-E: Benchmarking Neural Network Robustness via Attribute Editing | ImageNet-E |
| ARKitTrack: A New Diverse Dataset for Tracking Using Mobile RGB-D Data | ARKitTrack |
| Diverse Embedding Expansion Network and Low-Light Cross-Modality Benchmark for Visible-Infrared Person Re-identification | LLCM |
| JRDB-Pose: A Large-scale Dataset for Multi-Person Pose Estimation and Tracking | JRDB-Pose |