This documentation is written in English. It will walk you through the first setup of your router and give you insights into the main features available in Turris OS.

We are using Markdown to document everything and mkdocs to handle the presentation.

First of all clone this repository via git.

git clone https://gitlab.nic.cz/turris/user-docs.git

To render this documentation, you need MkDocs.

Run the following pip3 command in the cloned repository to install it easily.

pip3 install --user -r requirements.txt

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

mkdocs serve

If everything works well, you should see the documentation on http://127.0.0.1:8000.

File names should clearly describe what given files contain. Use only lowercase letter, digits, hyphens and dots. Don't use underscores. Each name should start with a letter and be trailed by an extension separated with a dot.

Some examples:

• openvpn-server.md
• setup.md
• haas-device.png
• turris-10.jpg

There are special cases where uppercase letters may be used. This applies to files like README.md, LICENSE or .DockerFile etc. which have conventional names.

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.

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

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. Switch your browser to English.

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)

All images on the page are grouped into the same lightbox by default. Grouping of images into lightboxes can also be done manually by specifying @{lightbox-name} right after the opening [ bracket of the image, e.g., ![@{my-lightbox-name}Here is my description](image.jpg) (or after [! if hiding the image... see below)

Hidden images (that appear in the lightbox gallery but not on the main page) can be added by adding a ! right after the opening [ bracket of the image. If adding a lightbox name using @{name} then the ! goes before the @.

# image with default lightbox name
![my description](image.jpg)

# hidden image
![!my description](image.jpg)

# specified lightbox name
![@{mylightbox}my description](image.jpg)

# hidden image with specified lightbox name
![!@{mylightbox}my description](image.jpg)

The metadata must be the first thing in the file and must take the form of a valid YAML set between triple-dashed lines. Here is a basic example:

---
board: mox
competency: expert
---

Between these triple-dashed lines, use predefined variables (see below for a reference).

In case you want to specify Turris device(s) in the article, use one or multiple options provided below.

• shield
• mox
• omnia
• 1.x

---
board: shield, mox, omnia, 1.x
---

In case you want to specify competency level choose one of the levels below.

• novice
• intermediate
• advanced
• expert

---
competency: expert
---

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

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

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.

We have admonition extension, so you can use note, tip, warning and other keywords for block-styled content. It needs to start with !!! or ???. More details can be found in Admonition documentation.

!!! tip
    Use admonitions to make your text more readable.

Specific cases are custom admonitions which need titles after keywords:

!!! cli-alt "Command line alternative"
    You can also use `opkg` for this purpose.

Multiple documentation pages can share content. One or more parts of the text in one page can be included to one or more other pages.

In the source page, a part that can be included is enveloped by a pair of special marks (replace NAME by the real name of this part):

<!--NAME-start-->

... content to be included ...

<!--NAME-end-->

It the destination page, insert an inclusion mark like this:

{%
  include-markdown "SOURCE.md"
  start="<!-NAME-start-->"
  end="<!--NAME-end-->"
%}

Replace NAME by the name meant above and SOURCE.md by the path to the source Markdown file.

It has more features than described here. See the include-markdown documentation for more information.