Readme : the name itself, readme , indicates its purpose: to be read. The readme file is the first file that a developer should look at before embarking on a project, so knowing how to write a good readme file is also essential , so that all relevant information is presented in a compact form..
Readme files , often created as readme.txt or readme.md , often contain important information about the system, project, or software to which they refer. In order for users to easily find the file at a glance, it is recommended to locate it at the top level of the directory.
In general, the file name is written README in uppercase. This way, case-sensitive systems will list the file before all other files that start with lowercase..
The file also has different purposes for different types of users:
Depending on its purpose, a readme file can offer the following contents:
It is important to always write the readme in a language appropriate for the end user. Only then can most of the questions be clarified.
You can write and save a readme file in any text file format . Formats range from readme.txt to readme.doc and readme.1st. Depending on the platform on which the software is to be run , the file format is adapted to the system in question and to your text display program. This ensures that the text program can read the file..
Today, developers generally use the readme.md format , but what is an .md file? The file extension indicates that it is a readme file in Markdown format. Markdown converts text to HTML with the help of formatting characters. A properly formed and structured readme file provides users with a complete project summary.
Here we show you each of the structural elements of a readme.md file as well as the possibilities offered by the Markdown format. To enable collaboration around the world and avoid language barriers, the readme file should always be in English .
Readme example in Markdown format:
# Project name *** Short Description about the project.
With three asterisks (***) you can insert a horizontal separation line.
At the top of the readme file , there is a meaningful project name and a brief explanation of the project type. In Markdown, the pound sign ( # ) always introduces a heading. The number of pads determines the type of header:
# Headline H1 ## Headline H2 ### Headline H3 #### Headline H4 ##### Headline H5 ###### Headline H6
If the documentation is extensive, a clear index provides a good overview:
## Table of Contents 1. [General Info](#general-info) 2. [Technologies](#technologies) 3. [Installation](#installation) 4. [Collaboration](#collaboration) 5. [FAQs](#faqs)
The index of contents of readme.md can be easily structured with an ordered list. Just insert the number that corresponds to the beginning of the line to create the list.
GitHub automatically adds identifications to the readme file headers . The identifications are generated from the header name, and the hyphens (-) replace the spaces. They are great for content index anchor navigation. If the readme.md file is intended to be used on another platform that does not automatically assign identifications to headers, the anchor navigation can be generated using HTML:
## Table of Contents <a name="general-info"></a> ### General Info
The index is followed by the respective content blocks of the individual sections:
## General Info *** Write down the general informations of your project. It is worth to always put a project status in the Readme file. This is where you can add it. ### Screenshot 
The general information of the project is important to get an idea of it beyond the brief explanation. Markdown also allows you to insert graphics, screenshots, or other images into your documentation. For this, just write a descriptive word in brackets, followed by the URL of the image in brackets (without interleaved spaces). In front of it, put an exclamation point so Markdown interprets it as an image file.
## Technologies *** A list of technologies used within the project: * [Technologie name](https://example.com): Version 12.3 * [Technologie name](https://example.com): Version 2.34 * [Library name](https://example.com): Version 1234
The Markdown format allows you to bullet an unnumbered list with an asterisk (*) at the beginning of the line.
Links can be inserted anywhere in the readme.md file . The procedure is very similar to that of an image file, only without the exclamation point at the beginning of the line. Put the word to be linked in brackets, followed by the path to the website also in brackets (and without interleaved spaces).
The file must always be in the same repository. You can also use other publicly accessible files, but then you run the risk that the owner will delete them at some point, thus making your readme.md files disappear.
## Installation *** A little intro about the installation. ``` $ git clone https://example.com $ cd ../path/to/the/file $ npm install $ npm start ``` Side information: To use the application in a special environment use ```lorem ipsum``` to start
Since readme files are often used in the context of computer program development, it is helpful to include source code examples in the document . Markdown also has a format option for this purpose. You can format the code with three grave accents (`` '') at the beginning and at the end. You can also insert the code passages directly into the text.
## Collaboration *** Give instructions on how to collaborate with your project. > Maybe you want to write a quote in this part. > It should go over several rows? > This is how you do it.
A?>? at the beginning of the line converts the text into a quote.
## FAQs *** A list of frequently asked questions 1. **This is a question in bold** Answer of the first question with _italic words_. 2. __Second question in bold__ To answer this question we use an unordered list: * First point * Second Point * Third point 3. **Third question in bold** Answer of the third question with *italic words*. 4. **Fourth question in bold** | Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead | |:--------------|:-------------:|--------------:| | text-align left | text-align center | text-align right |
A combination of ordered and unordered lists can also be used in the readme.md file . To do this, you just have to continue the numbered list with the corresponding number.
As an example, we have integrated bold and italicized words and sections of text . You can italicize by placing a single asterisk (*) or an underscore (_) before or after the word or section of text in question. Double asterisks or underscores are used to mark in bold.
Here are the examples covered in the article again, this time summarized in the form of a readme file template :
## Table of Contents 1. [General Info](#general-info) 2. [Technologies](#technologies) 3. [Installation](#installation) 4. [Collaboration](#collaboration) 5. [FAQs](#faqs) ### General Info *** Write down the general informations of your project. It is worth to always put a project status in the Readme file. This is where you can add it. ### Screenshot  ## Technologies *** A list of technologies used within the project: * [Technologie name](https://example.com): Version 12.3 * [Technologie name](https://example.com): Version 2.34 * [Library name](https://example.com): Version 1234 ## Installation *** A little intro about the installation. ``` $ git clone https://example.com $ cd ../path/to/the/file $ npm install $ npm start ``` Side information: To use the application in a special environment use ```lorem ipsum``` to start ## Collaboration *** Give instructions on how to collaborate with your project. > Maybe you want to write a quote in this part. > It should go over several rows? > This is how you do it. ## FAQs *** A list of frequently asked questions 1. **This is a question in bold** Answer of the first question with _italic words_. 2. __Second question in bold__ To answer this question we use an unordered list: * First point * Second Point * Third point 3. **Third question in bold** Answer of the third question with *italic words*. 4. **Fourth question in bold** | Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead | |:--------------|:-------------:|--------------:| | text-align left | text-align center | text-align right |
Dillinger's WYSIWYG editor will allow you to easily create a readme.md file .
