Skip to content
Snippets Groups Projects
Commit ad3f9e50 authored by Jan Siwiec's avatar Jan Siwiec
Browse files

Mkdocs 101

parent 78e90ec2
No related branches found
No related tags found
1 merge request!21Mkdocs 101
# MkDocs 101
This section describes the essentials of markup language allowing you to write a simple page.
Only the most basic elements are described here to give you a general idea of the workflow.
For more information, see [mkdocs-material][a].
## Headers
```
# Header 1
## Header 2
Up to #### Header 4
```
## Text
Formatting:
```
*italics*
**bold**
```
One `enter` acts as space, blank line breaks the text into paragraph.
## Lists
Indentation: 4 spaces
Bullets point symbols `*` or `–` for unordered list.
Ordered list start with number, can be the same number, MkDocs will translate it, e.g.:
```
1. entry1
1. entry2
1. entry3
```
Will automatically translate to
```
1. entry1
2. entry2
3. entry3
```
## Tables
```
| First Header | Second Header | Third Header |
| ------------ | ------------- | ------------ |
| Content Cell | Content Cell | Content Cell |
| Content Cell | Content Cell | Content Cell |
```
Aligning columns to left/center/right is done by placing `:` characters at the beginning and/or end of the divider:
```
| Left align | Center align | Right align |
| :----------- | :------------: | -----------: |
| Content | Content | Content |
```
## Code blocks
Starts and ends with three backticks `\``.
You can specify the environment/language (console in the example below) at the beginning. But not necessary.
\```console
Some code
In code block
\```
Word marked with single `\`` from both sides creates `code formatting` inline.
## Admonitions
Start with `!!!`. Text is indented with 4 spaces. Can add title of the admonition using `“`, for example:
!!! Note “Alternative text”
This is a note admonition.
Most often we use `Note`, `Tip`, `Important`, and `Warning` admonitions. (But less is more.)
## Links
Writing simply www.address.com translates as plaintext in MkDocs. So a reference is required.
For links, we use reference ID, for example:
`[www.address.com][a]` or `[see this section][1]`
And then put the reference link at the end of the file:
```
[a]: www.address.com
[1]: https://docs.it4i.cz/dice/
```
We usually use alphabet for links outside the docs and numerals for links inside the docs.
Links inside the docs can be relative.
## Images
We don’t use reference ID for images. So for example:
```
![](../img/image.png)
```
can be added in the text to show the respective image at that place.
Empty `[]` means there is no alternative text for the image.
[a]: https://squidfunk.github.io/mkdocs-material/reference/
......@@ -10,5 +10,6 @@ nav:
- Style Guide:
- Writing practices: ./contribute/style-guide/writing-practices.md
- Style guide: ./contribute/style-guide/style.md
- MkDocs 101: ./contribute/style-guide/mkdocs-101.md
- List of rules: ./contribute/style-guide/test-rules.md
- Technical Details: ./contribute/technical-details.md
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment