A while ago, I wrote about what you could include in a README file for a project. Based on this post and a few practical examples of READMEs, I created and published a template that I will use in my own projects going forward.
It is available on GitHub: https://github.com/matthiasott/README-template
The template might certainly change a bit over time. But as it is now, I think it includes the most important sections I might need in most projects. Because not every project is created equal, the idea is to just use what you need and delete the rest of the template. So in case you want to use it as a starting point, feel free to modify it – and also notify me about any improvements that could be made.
An Automatically Generated TOC
Depending on the size of your README, it might also make sense to also include a TOC, a Table of Contents, at the start of the file. You could create such a TOC manually, but I also found a neat little package called DocToc, that automatically creates such a TOC for you, including anchor links to the respective sections of your file. Actually, you can use DocToc to generate a table of contents not only for a README but for any kind of markdown file inside a local git repository.
You install the package globally via npm (so Node.js and npm are a requirement):
npm install -g doctoc
You can then generate or update table of contents for all markdown files including all subfolders with the command
doctoc .
If you only want to generate or update a TOC in an individual file, you add the file name to the command:
doctoc README.md
By default, DocToc will create a TOC including anchor links using the GitHub markdown parser. But you can also tell it to create compatible links in the style of Bitbucket, Gitlab, or Ghost, for example, by using a flag:
doctoc README.md --bitbucket
If you want to specify where in your README DocToc adds the table of contents, you can place two lines of comments in your files and DocToc will place (and update) your TOC at this position:
<!-- START doctoc -->
<!-- END doctoc -->
You can even specify a title for the TOC with the --title option:
doctoc --title '**Table of Contents**'
So, in my case, I used this command to automatically generate the table of contents for my README template:
doctoc README.md --title '## Table of Contents'
Now, every time I need to update the TOC, I run DocToc and it will automatically update all items, titles, and links. Nice!
A README editor
Just a quick addition: While doing a bit more research for a good README structure, I also stumbled upon a handy editor made by Katherine Oelsner. Readme.so lets you create an individual README by adding sections from a list of snippets. You just select the sections you want to include in your README, rearrange them via drag and drop if needed, adjust the text, and download your template. A nice and easy way to create your README as well, especially if none of your projects is like the other and a rigid template structure therefore wouldn’t make much sense.
~
