README.md 2.68 KB
Newer Older
Josef Schlehofer's avatar
Josef Schlehofer committed
1
2
# Documentation for Turris routers

Michal Hrusecky's avatar
Michal Hrusecky committed
3
4
5
This documentation is written in English. It will walk you through the
first setup of your router and give you insights into main features available
in Turris OS.
Josef Schlehofer's avatar
Josef Schlehofer committed
6

Michal Hrusecky's avatar
Michal Hrusecky committed
7
8
We are using Markdown to document everything and `mkdocs` to handle the
presentation.
Josef Schlehofer's avatar
Josef Schlehofer committed
9
10
11
12


## Requirements:

Michal Hrusecky's avatar
Michal Hrusecky committed
13
To render this documentation, you need [mkdocs](https://www.mkdocs.org/).
Josef Schlehofer's avatar
Josef Schlehofer committed
14

Michal Hrusecky's avatar
Michal Hrusecky committed
15
It can be installed easily using `pip` running the following command
Josef Schlehofer's avatar
Josef Schlehofer committed
16
17

```
Michal Hrusecky's avatar
Michal Hrusecky committed
18
pip install --user -r requirements.txt
Josef Schlehofer's avatar
Josef Schlehofer committed
19
20
```

Michal Hrusecky's avatar
Michal Hrusecky committed
21
22
If you are all set, you can clone this repository via `git`.

Josef Schlehofer's avatar
Josef Schlehofer committed
23
```
Michal Hrusecky's avatar
Michal Hrusecky committed
24
git clone --recurse-submodules https://gitlab.labs.nic.cz/turris/user-docs.git
Josef Schlehofer's avatar
Josef Schlehofer committed
25
26
27
28
```

### Run mkdocs

Michal Hrusecky's avatar
Michal Hrusecky committed
29
30
31
32
Once you have a cloned out directory with documentation, you can either render
it locally or run a local server that will serve it. To do the later, you just
need to run in the root directory of the documentation the following command

Josef Schlehofer's avatar
Josef Schlehofer committed
33
34
35
36
```
mkdocs serve
```

Michal Hrusecky's avatar
Michal Hrusecky committed
37
If everything works well, you should see the documentation on <http://127.0.0.1:8000>.
Michal Hrusecky's avatar
Michal Hrusecky committed
38
39
40

## Tips for writing

41
42
43
44
45
46
47
48
49
50
51
### Headers

For header, please try to stick to markdown notation using the following syntax:

* ``# Header level 1``
* ``## Header level 2``
* ``### Header level 3``
* ...

It is more consistent once you get to more than three levels.

Michal Hrusecky's avatar
Michal Hrusecky committed
52
53
### Links

54
When writing links, use **relative path** and `.md` extension. So for example
55
56
`[README](README.md)` will create a link like so: [README](README.md). When
documentation is built, they get converted to working links (without `.md`).
57

58
59
60
61
62
63
64
65
66
67
68
### Images

When doing screenshots, crop the screenshot to cover only interesting areas and
stick to the whole elements (try to avoid cut out buttons/labels).

Use stock settings in your browser (preferably Firefox) and try to avoid any
contamination by system themes.

For highlighting the important part of the screenshot (if you need to, most of
the time not necessary) use rectangular shape and 3-pixel red line `rgb(255, 0, 0)`

69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
### Formating

#### Italic

Use `_italic_` whenever you are citing some label, like for example menu
in we UI.

#### Monospace

Use  `` `monospace` `` whenever talking about commands or files or citing some
code example.

#### **Bold**

Use `**bold**` to stress the important part. If you are describing some
complex process and there is one step that is more important or more easily
overlooked, you can stress it by making it bold. To stress importance even
more, it might make sesne to use admonition.
Michal Hrusecky's avatar
Michal Hrusecky committed
87
88
89

### Admonition

90
We have admonition extension, so you can use `note`, `tip`, `warning` and other
Michal Hrusecky's avatar
Michal Hrusecky committed
91
92
93
94
keywords for block-styled content. It needs to start with `!!!` or `???`.  More
details can be found in [Admonition
documentation](https://squidfunk.github.io/mkdocs-material/extensions/admonition/).