Improve Markdown formatting

docs/reference/auth/dovecot_sasl.md

@@ -1,6 +1,6 @@
 # Dovecot SASL
 
-The 'auth.dovecot\_sasl' module implements the client side of the Dovecot
+The 'auth.dovecot_sasl' module implements the client side of the Dovecot
 authentication protocol, allowing maddy to use it as a credentials source.
 
 Currently SASL mechanisms support is limited to mechanisms supported by maddy
@@ -16,11 +16,11 @@ dovecot_sasl unix://socket_path
 
 ## Configuration directives
 
-**Syntax**: endpoint _schema://address_ <br>
-**Default**: not set
+### endpoint _schema://address_
+Default: not set
 
 Set the address to use to contact Dovecot SASL server in the standard endpoint
 format.
 
-tcp://10.0.0.1:2222 for TCP, unix:///var/lib/dovecot/auth.sock for Unix
+`tcp://10.0.0.1:2222` for TCP, `unix:///var/lib/dovecot/auth.sock` for Unix
 domain sockets.

docs/reference/auth/external.md

@@ -1,12 +1,12 @@
 # System command
 
 auth.external module for authentication using external helper binary. It looks for binary
-named maddy-auth-helper in $PATH and libexecdir and uses it for authentication
+named `maddy-auth-helper` in $PATH and libexecdir and uses it for authentication
 using username/password pair.
 
 The protocol is very simple:
 Program is launched for each authentication. Username and password are written
-to stdin, adding \\n to the end. If binary exits with 0 status code -
+to stdin, adding \n to the end. If binary exits with 0 status code -
 authentication is considered successful. If the status code is 1 -
 authentication is failed. If the status code is 2 - another unrelated error has
 happened. Additional information should be written to stderr.
@@ -21,19 +21,24 @@ auth.external {
 
 ## Configuration directives
 
-**Syntax**: helper _file\_path\_
+### helper _file_path_
 
-Location of the helper binary. **Required.**
+**Required.** <br>
+Location of the helper binary. 
 
-**Syntax**: perdomain _boolean_ <br>
-**Default**: no
+---
+
+### perdomain _boolean_
+Default: `no`
 
 Don't remove domain part of username when authenticating and require it to be
 present. Can be used if you want user@domain1 and user@domain2 to be different
 accounts.
 
-**Syntax**: domains _domains..._ <br>
-**Default**: not specified
+---
+
+### domains _domains..._
+Default: not specified
 
 Domains that should be allowed in username during authentication.
 
@@ -43,5 +48,5 @@ name in addition to just username.
 
 If used without 'perdomain', domain part will be removed from login before
 check with underlying auth. mechanism. If 'perdomain' is set, then
-domains must be also set and domain part WILL NOT be removed before check.
+domains must be also set and domain part **will not** be removed before check.
 

docs/reference/auth/ldap.md

@@ -8,7 +8,7 @@ directory search or template .
 
 Note that storage backends conventionally use email addresses, if you use
 non-email identifiers as usernames then you should map them onto
-emails on delivery by using auth\_map (see documentation page for used storage backend).
+emails on delivery by using `auth_map` (see documentation page for used storage backend).
 
 auth.ldap also can be a used as a table module. This way you can check
 whether the account exists. It works only if DN template is not used.
@@ -42,72 +42,89 @@ auth.ldap ldap://maddy.test.389 {
 
 ## Configuration directives
 
-**Syntax:** urls _servers...\_
+### urls _servers..._
 
-REQUIRED.
+**Required.**
 
 URLs of the directory servers to use. First available server
 is used - no load-balancing is done.
 
-URLs should use 'ldap://', 'ldaps://', 'ldapi://' schemes.
+URLs should use `ldap://`, `ldaps://`, `ldapi://` schemes.
 
-**Syntax:** bind off <br>
-bind unauth <br>
-bind external <br>
-bind plain _username_ _password_ <br>
-**Default:** off
+---
+
+### bind `off` | `unauth` | `external` | `plain` _username_ _password_
+
+Default: `off`
 
 Credentials to use for initial binding. Required if DN lookup is used.
 
-'unauth' performs unauthenticated bind. 'external' performs external binding
-which is useful for Unix socket connections (ldapi://) or TLS client certificate
-authentication (cert. is set using tls\_client directive). 'plain' performs a
+`unauth` performs unauthenticated bind. `external` performs external binding
+which is useful for Unix socket connections (`ldapi://`) or TLS client certificate
+authentication (cert. is set using tls_client directive). `plain` performs a
 simple bind using provided credentials.
 
-**Syntax:** dn\_template _template\_
+---
+
+### dn_template _template_
 
-DN template to use for binding. '{username}' is replaced with the
+DN template to use for binding. `{username}` is replaced with the
 username specified by the user.
 
-**Syntax:** base\_dn _dn\_
+---
+
+### base_dn _dn_
 
 Base DN to use for lookup.
 
-**Syntax:** filter _str\_
+---
+
+### filter _str_
 
-DN lookup filter. '{username}' is replaced with the username specified
+DN lookup filter. `{username}` is replaced with the username specified
 by the user.
 
 Example:
+
 ```
 (&(objectClass=posixAccount)(uid={username}))
 ```
 
 Example (using ActiveDirectory):
+
 ```
 (&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName={username})(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))
 ```
 
 Example:
+
 ```
 (&(objectClass=Person)(mail={username}))
 ```
 
-**Syntax:** starttls _bool_ <br>
-**Default:** off
+---
+
+### starttls _bool_
+Default: `off`
 
 Whether to upgrade connection to TLS using STARTTLS.
 
-**Syntax:** tls\_client { ... }
+---
+
+### tls_client { ... }
 
 Advanced TLS client configuration. See [TLS configuration / Client](/reference/tls/#client) for details.
 
-**Syntax:** connect\_timeout _duration_ <br>
-**Default:** 1m
+---
+
+### connect_timeout _duration_
+Default: `1m`
 
 Timeout for initial connection to the directory server.
 
-**Syntax:** request\_timeout _duration_ <br>
-**Default:** 1m
+---
+
+### request_timeout _duration_
+Default: `1m`
 
 Timeout for each request (binding, lookup).

docs/reference/auth/netauth.md

@@ -9,7 +9,7 @@ mail address.
 
 Note that storage backends conventionally use email addresses.  Since
 NetAuth recommends *nix compatible usernames, you will need to map the
-email identifiers to NetAuth Entity IDs using auth\_map (see
+email identifiers to NetAuth Entity IDs using `auth_map` (see
 documentation page for used storage backend).
 
 auth.netauth also can be used as a table module.  This way you can
@@ -33,15 +33,16 @@ auth.netauth {}
 
 ## Configuration directives
 
-**Syntax:** require\_group _group_
+### require_group _group_
 
-OPTIONAL.
+Optional.
 
 Group that entities must possess to be able to use maddy services.
 This can be used to provide email to just a subset of the entities
 present in NetAuth.
 
-**Syntax** debug off <br>
-debug on <br>
-debug off <br>
-**Default:** off
+---
+
+### debug `on` | `off`
+
+Default: `off`

docs/reference/auth/pam.md

@@ -4,7 +4,8 @@ auth.pam module implements authentication using libpam. Alternatively it can be
 use helper binary like auth.external module does.
 
 maddy should be built with libpam build tag to use this module without
-'use\_helper' directive.
+'use_helper' directive.
+
 ```
 go get -tags 'libpam' ...
 ```
@@ -18,25 +19,28 @@ auth.pam {
 
 ## Configuration directives
 
-**Syntax**: debug _boolean_ <br>
-**Default**: no
+### debug _boolean_ 
+Default: `no`
 
 Enable verbose logging for all modules. You don't need that unless you are
 reporting a bug.
 
-**Syntax**: use\_helper _boolean_ <br>
-**Default**: no
+---
+
+### use_helper _boolean_
+Default: `no`
 
-Use LibexecDirectory/maddy-pam-helper instead of directly calling libpam.
+Use `LibexecDirectory/maddy-pam-helper` instead of directly calling libpam.
 You need to use that if:
-1. maddy is not compiled with libpam, but maddy-pam-helper is built separately.
-2. maddy is running as an unprivileged user and used PAM configuration requires additional
-   privileges (e.g. when using system accounts).
 
-For 2, you need to make maddy-pam-helper binary setuid, see
+1. maddy is not compiled with libpam, but `maddy-pam-helper` is built separately.
+2. maddy is running as an unprivileged user and used PAM configuration requires additional privileges (e.g. when using system accounts).
+
+For 2, you need to make `maddy-pam-helper` binary setuid, see
 README.md in source tree for details.
 
 TL;DR (assuming you have the maddy group):
+
 ```
 chown root:maddy /usr/lib/maddy/maddy-pam-helper
 chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-pam-helper

docs/reference/auth/pass_table.md

@@ -3,7 +3,7 @@
 auth.pass_table module implements username:password authentication by looking up the
 password hash using a table module (maddy-tables(5)). It can be used
 to load user credentials from text file (via table.file module) or SQL query
-(via table.sql\_table module).
+(via table.sql_table module).
 
 
 Definition:
@@ -30,15 +30,15 @@ smtp tcp://0.0.0.0:587 {
 
 ## Password hashes
 
-pass\_table expects the used table to contain certain structured values with
+pass_table expects the used table to contain certain structured values with
 hash algorithm name, salt and other necessary parameters.
 
-You should use 'maddy hash' command to generate suitable values.
-See 'maddy hash --help' for details.
+You should use `maddy hash` command to generate suitable values.
+See `maddy hash --help` for details.
 
 ## maddy creds
 
 If the underlying table is a "mutable" table (see maddy-tables(5)) then
-the 'maddy creds' command can be used to modify the underlying tables
-via pass\_table module. It will act on a "local credentials store" and will write
+the `maddy creds` command can be used to modify the underlying tables
+via pass_table module. It will act on a "local credentials store" and will write
 appropriate hash values to the table.

docs/reference/auth/plain_separate.md

@@ -1,6 +1,6 @@
 # Separate username and password lookup
 
-auth.plain\_separate module implements authentication using username:password pairs but can
+auth.plain_separate module implements authentication using username:password pairs but can
 use zero or more "table modules" (maddy-tables(5)) and one or more
 authentication providers to verify credentials.
 
@@ -24,19 +24,22 @@ How it works:
 
 ## Configuration directives
 
-***Syntax:*** user _table module\_
+### user _table-module_
 
 Configuration block for any module from maddy-tables(5) can be used here.
 
 Example:
+
 ```
 user file /etc/maddy/allowed_users
 ```
 
-***Syntax:*** pass _auth provider\_
+---
+
+### pass _auth-provider_
 
 Configuration block for any auth. provider module can be used here, even
-'plain\_split' itself.
+'plain_split' itself.
 
 The used auth. provider must provide username:password pair-based
 authentication.

docs/reference/auth/shadow.md

@@ -12,23 +12,27 @@ auth.shadow {
 
 ## Configuration directives
 
-**Syntax**: debug _boolean_ <br>
-**Default**: no
+### debug _boolean_
+
+Default: `no`
 
 Enable verbose logging for all modules. You don't need that unless you are
 reporting a bug.
 
-**Syntax**: use\_helper _boolean_ <br>
-**Default**: no
+---
+
+### use_helper _boolean_
+Default: `no`
 
-Use LibexecDirectory/maddy-shadow-helper instead of directly reading /etc/shadow.
+Use `LibexecDirectory/maddy-shadow-helper` instead of directly reading `/etc/shadow`.
 You need to use that if maddy is running as an unprivileged user
 privileges (e.g. when using system accounts).
 
-You need to make maddy-shadow-helper binary setuid, see
+You need to make `maddy-shadow-helper` binary setuid, see
 cmd/maddy-shadow-helper/README.md in source tree for details.
 
 TL;DR (assuming you have maddy group):
+
 ```
 chown root:maddy /usr/lib/maddy/maddy-shadow-helper
 chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-shadow-helper

docs/reference/blob/fs.md

@@ -7,14 +7,15 @@ storage.blob.fs {
     root <directory>
 }
 ```
+
 ```
 storage.blob.fs <directory>
 ```
 
 ## Configuration directives
 
-**Syntax:** root _path_ <br>
-**Default:** not set
+### root _path_
+Default: not set
 
 Path to the FS directory. Must be readable and writable by the server process.
 If it does not exist - it will be created (parent directory should be writable