If you are documenting your GitHub project, you don't have to rely on plain, uniform body text. With the partly in-house markdown, readme files and documentation can be laid out really well.
What is markdown
Markdown is basically a pretty simple thing, a markup language. Just like HTML: HTML used to be an "easy" way to design web pages - easy compared to programming languages. But in the end the HTML syntax is not suitable for longer running texts. There are always brackets, quotation marks and certain keywords waiting to be set to the exact character. For example, if you want to write the word "fat" in bold: <b> bold </b>
Markdown simplifies the matter significantly, a simple ** bold ** is displayed on Markdown-enabled pages just like the HTML variant. To be more precise: It is translated into the HTML version. The Markdown awards are much easier to remember and, above all, to type.
Now there is not just one form of Markdown, even if most of the elements are standardized. In any case, Github offers some special options, for example to be able to mention Github users with highlighted formatting or to clearly display code and commands..
In the following you can see which elements you use and how to create a nicely formatted readme file:
- headlines
- Text markup (bold, italic, strikethrough)
- Left
- pictures
- Lists (unordered, numbered, ToDo)
- Tables
- Emojis
References to users (@user) and pull requests are left out, as these do not work in normal files, but only in descriptions and comments of pull requests and issues.
Headings and Awards
When you create a project in GitHub, you also get a ready-made, empty file "README.md" - where the "md" stands for Markdown, of course. Open the editor for the file and start with the headings, for example, to structure the article:
# My project
## Installation
### Windows
### Linux
## Usage
### Examples
## Troubleshooting
## License
One rhombus stands for a first-order heading, two to six rhombuses for subordinate headings. To test it, you can immediately tap the "Preview" tab and you will see your first rendered markdown..
There is usually a bit of running text to describe it:
# My Project
In "My Project", text can be displayed in * italics * and ** bold ** as well as ~~ strikethrough ~~.
In this new paragraph, you can see an example of code: Type `echo hello`.
Here you can see several new awards, each of which has the effect that is written in the asterisk or tilde. A new paragraph is simply achieved with a blank line - as you know it from text editors. It is important to mark the code: `echo Hallo` is not a single quotation mark, but a grave accent, better known as accent grave or in programming as a backtick. What is meant is the rarely used character to the left of the [BACK] key on the keyboard, which is created using [SHIFT] + [´] + [SPACEBAR] - without a spacebar, the backtick would be set as accent grave over a letter.
You can put entire blocks of code in three backticks:
``
echo Hello
echo World
''
Alternatively, code blocks can also be indented with four spaces, which is borrowed from programming syntax. Ultimately, such a code block is just a special form of quotation. Normal quotations are even easier:
A famous scripter said, '
Hello world
Links and pictures
But what is nice text without links and pictures? Why do both coincide? Ultimately, images are just a special type of link. On the left you write in Markdown using a pair of brackets: The text is in square brackets, followed by the link in round brackets:
[A link to Wikipedia] (https://www.wikipedia.de)
Complete URLs such as https://www.wikipedia.de are also automatically converted into clickable links.
It is almost the same for images, but the text in front of the image in square brackets is the image's alt text and is preceded by an exclamation mark:
! [screenshot of wikipedia] (bilder / screenshot_wikipedia.png)
Pay attention to the content of the round brackets: This is a relative link to an image in the "images" directory. As you may know from the terminal, a link could also be made to a folder two levels above: "../../testfiles/myfile.txt".
Lists and tables
Often you will offer information as lists - which is pleasantly easy, for example in an ordered list:
1. Install the program
1. Under Linux:
1. Ubuntu:
1. Debian:
1. Under Windows
1. Use the program
1. Under Linux:
1. ...
You can actually "1." use, the numbering is set automatically. Use "-" or "*" for an unordered list.
Nevertheless, this is a bit tricky: The points must start exactly under the first letter of the higher-level point. And if you don't want to create a nested, but a to-do list.
Attention: In order for the following list entries to work for you, you have to remove the period (.) That we have put into them. This only serves to ensure that the entries are displayed here in Markdown format and do not automatically appear as a (ticked) to-do list.
- [.x] Create readme
- [.x] Learn first formatting
- [.] Complete readme
- [.] Publish readme
You may already have guessed it: Here boxes are set in front of the list entries that show the tasks as completed ([.x]) with a checkmark or as open ([.]) Without a checkmark.
The supreme discipline in HTML is the table - tables are always prone to errors. Markdown can do that much, much better! A simple example with column headings, two columns and three lines:
Program call | Function
-------------- | --------
foobar -v | Extended information
foobar -t | Just test the program
foobar -vt | Run the program with all options
The principle: Columns are separated by a pipe symbol, i.e. the vertical line. The headings are in the first line, the second line separates them from the actual table content. All table entries follow, again separated by pipes. In contrast to lists, these of course do not have to be in certain places, the length of each text in each cell is arbitrary.
Emojis and miscellaneous
Above all, there is a lot of communication on GitHub - and that is not possible nowadays without emojis, which you can set in a very trivial way using ": smile:", ": angry:" and so on. You can find the complete list here: https://www.webfx.com/tools/emoji-cheat-sheet/
As already mentioned, you can still set references to users and issues in some areas of GitHub - but not in a readme file. The syntax is again very simple:
@ nutzer_123 please have a look at issue # 33 - thanks: smile:
From "@ nutzer_123" and "# 33", more stylish formatting would be rendered.
So that you can now see the result of your work, here is the README.md created with all examples as a screenshot:
Of course, you can only see the overall layout here. You can view the created file here on GitHub .
