Documentation | Style Guide¶

For styling of documentation, we adhere to Markdown's unofficially recognized style guide. For more information you can take a look at: markdownguide.org

Additional Conventions¶

Additional conventions specific to these documents, not covered in the guide above, are outlined below.

In the following sections, the terms "documentation" and "docs" are used interchangeably, both referring to the current documentation: Falley B.V. Docs.

File Naming¶

Documentation directories should use lowercase letters, with hyphens - replacing any spaces.

- directory:
    - file.md
    - my-file.md
    - my-large-file.md

Headings¶

Headings should follow a logical hierarchy (e.g. H3 after H2). Avoid skipping heading levels to maintain readability and organization.

Standalone headings should be followed by a new line. If a heading is followed by content, add two new lines for clear separation.

# Heading 1

## Heading 2
Hello world, how are you doing?


### Heading 3

Links¶

Links should be formatted in one of the following ways:

Domain, TLD, and path:

Display only the domain, top-level domain (TLD), and the full path.

In this case, https://www.mydomain.com/mypage/hello should be simplified to mydomain.com/mypage/hello.
```
[mydomain.com/mypage/hello](https://www.mydomain.com/mypage/hello)
```
Last segment of the path:

Display only the last segment of the path.

In this case, https://www.mydomain.com/mypage/hello should be simplified to Hello.
```
[Hello](https://www.mydomain.com/mypage/hello)
```

Breaks and Escapes¶

Special Escapes¶

You can use a \ to escape special formatting characters, allowing you to use them as normal text. For all characters this applies to see: Characters You Can Escape

Line Breaks¶

A forced line break should be made by ending the sentence with a backslash \, followed by pressing Enter.

This is my first sentence\
This is my second sentence

Inline Code¶

Inline code should be written by using single backticks ` to enclose the relevant text.

Input:

"I `code` while I solve problems"

Result:

"I code while I solve problems"

Syntax Highlighting Inline Code¶

Syntax highlighting can be applied to inline code blocks by prefixing them with a shebang #+!, directly followed by the corresponding language shortcode (see Available Lexers).

Input:

The `#!python range()` function is used to generate a sequence of numbers.

Result:

The range() function is used to generate a sequence of numbers.

Code Blocks¶

Instead of using space or tab indents, code blocks should be defined by using Fenced Code Blocks.

These can be written by enclosing the code block in triple backticks `+`+`.

```
class Human {
   String name = "John Doe";
   int age = 25;
}
```

Highlighted Code Blocks¶

Enable syntax highlighting for code blocks by specifying the language lexer after the opening triple backticks. For a full list of available lexers, refer to: Available Lexers

```dart
class Human {
   String name = "John Doe";
   int age = 25;
}
```

Adding A Title¶

Add a title label to the code block by adding title="<title>" after the shortcode, e.g. to display the name of a file.

my_file.dart

```dart title="my_file.dart"
class Human {
   String name = "John Doe";
   int age = 25;
}
```

Adding Line Numbers¶

Line numbers can be added to a code block by using the linenums="<start>" option directly after the shortcode, where <start> represents the starting line number.

```dart linenums="1"
class Human {
   String name = "John Doe";
   int age = 25;
}
```

Highlighting Lines¶

Specific lines can be highlighted in a code block by passing the line numbers to the hl_lines argument placed after the language shortcode. Note that line count starts at 1, regardless of the starting line number specified as part of linenums.

Highlight LinesHighlight Line Range

```dart linenums="1" hl_lines="2 4"
class Human {
   String name = "John Doe";
   int age = 25;
}
```

```dart linenums="1" hl_lines="2-5"
class Human {
   String name = "John Doe";
   int age = 25;
}
```