styleguide.md

# Styleguide

If not explicitly stated otherwise,
the following takes effect for all files:

- character encoding __utf-8__
- line endings with __lf__
- indentation with __4 spaces__
- final new line

!!! info
    There will be most likely a editorconfig present,
    please make sure your used IDE respects this.

!!! tip
    In general,
    it's a good idea to have a look into the yet existing code,
    to check how certain things were done up to now.

## Markdown

most important bullet points:

- leave always an empty line above and beneath of lists.
    It may render fine in normal markdown viewers,
    but not in the MkDocs Pages docs (like this)  

    ??? example inline end
        __bad:__
        ```markdown
        some text
        - bullet point
        - another item
        more normal text
        ```
        __good:__
        ```markdown
        some text

        - bullet point
        - another item

        more normal text
        ```

- if you insert a link,
    __always__ write the link to the bottom of the file with an alias,
    ordered alphabetically.  

    ??? example
        __bad:__
        ```markdown
        Look [here](https://www.coolsite.not/with/ultra/long/url) to read more about this.
        ```
        __good:__
        ```markdown
        Look [here][coolsite] to read more about this.

        [coolsite]: https://www.coolsite.not/with/ultra/long/url
        ```

- split long sentences on punctuation and connection words like `and` & `or`.  
    It will have the same appearance in viewers,
    but be much easier to maintain on code side.

    ??? example
        __bad__:
        ```markdown
        Some sentence that is very long, therefore it has punctuation and has absolutely no sense at all.
        ```
        > Some sentence that is very long, therefore it has punctuation and has absolutely no sense at all.

        __good:__
        ```markdown
        Some sentence that is very long,
        therefore it has punctuation
        and has absolutely no sense at all.
        ```

        > Some sentence that is very long,
        > therefore it has punctuation
        > and has absolutely no sense at all.

- tables have to be formatted in code

    ??? example
        __bad:__
        ```markdown
        ||column 1|
        |:-|:-|
        |__row 1__|cell 1|
        ```

        __good:__
        ```markdown
        |           | column 1 |
        | :-------- | :------- |
        | __row 1__ | cell 1   |
        ```