[DOCS] Adjust yaml snippets and misc adjustments (#855)

* [DOCS] Adjust yaml snippets

* use two spaces
* use yaml syntax highlighting
* other misc uniformity changes
* fix misc grammar
* add responsible disclosure link

Co-Authored-By: Amir Zarrinkafsh <nightah@me.com>

docs/configuration/access-control.md

@@ -92,40 +92,41 @@ configure Authelia accordingly.
 
 Here is a complete example of complex access control list that can be defined in Authelia.
 
-    access_control:
+```yaml
-        default_policy: deny
+access_control:
+  default_policy: deny
+  rules:
+    - domain: public.example.com
+      policy: bypass
 
-        rules:
+    - domain: secure.example.com
-        - domain: public.example.com
+      policy: one_factor
-          policy: bypass
+      networks:
+      - 192.168.1.0/24
 
-        - domain: secure.example.com
+    - domain: secure.example.com
-          policy: one_factor
+      policy: two_factor
-          networks:
-          - 192.168.1.0/24
 
-        - domain: secure.example.com
+    - domain: singlefactor.example.com
-          policy: two_factor
+      policy: one_factor
 
-        - domain: singlefactor.example.com
+    - domain: "mx2.mail.example.com"
-          policy: one_factor
+      subject: "group:admins"
+      policy: deny
 
-        - domain: "mx2.mail.example.com"
+    - domain: "*.example.com"
-          subject: "group:admins"
+      subject: "group:admins"
-          policy: deny
+      policy: two_factor
 
-        - domain: "*.example.com"
+    - domain: dev.example.com
-          subject: "group:admins"
+      resources:
-          policy: two_factor
+      - "^/groups/dev/.*$"
+      subject: "group:dev"
+      policy: two_factor
 
-        - domain: dev.example.com
+    - domain: dev.example.com
-          resources:
+      resources:
-          - "^/groups/dev/.*$"
+      - "^/users/john/.*$"
-          subject: "group:dev"
+      subject: "user:john"
-          policy: two_factor
+      policy: two_factor
-
+```
-        - domain: dev.example.com
-          resources:
-          - "^/users/john/.*$"
-          subject: "user:john"
-          policy: two_factor

docs/configuration/authentication/file.md

@@ -15,44 +15,46 @@ nav_order: 1
 Configuring Authelia to use a file is done by specifying the path to the
 file in the configuration file.
 
-    authentication_backend:
+```yaml
-        disable_reset_password: false
+authentication_backend:
-        file:
+  disable_reset_password: false
-            path: /var/lib/authelia/users.yml
+  file:
-            password:
+    path: /var/lib/authelia/users.yml
-                algorithm: argon2id
+    password:
-                iterations: 1
+      algorithm: argon2id
-                salt_length: 16
+      iterations: 1
-                parallelism: 8
+      salt_length: 16
-                memory: 1024
+      parallelism: 8
+      memory: 1024
+```
+
 
 
 ## Format
 
 The format of the users file is as follows.
 
-    users:
+```yaml
-        john:
+users:
-            password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
+  john:
-            email: john.doe@authelia.com
+    password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
-            groups:
+    email: john.doe@authelia.com
-                - admins
+    groups:
-                - dev
+      - admins
-
+      - dev
-        harry:
+  harry:
-            password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
+    password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
-            email: harry.potter@authelia.com
+    email: harry.potter@authelia.com
-            groups: []
+    groups: []
-
+  bob:
-        bob:
+    password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
-            password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
+    email: bob.dylan@authelia.com
-            email: bob.dylan@authelia.com
+    groups:
-            groups:
+      - dev
-                - dev
+  james:
-
+    password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
-        james:
+    email: james.dean@authelia.com
-            password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
+```
-            email: james.dean@authelia.com
 
 
 This file should be set with read/write permissions as it could be updated by users
@@ -73,7 +75,7 @@ always be valid for base64 decoding (characters a through z, A through Z, 0 thro
 For instance to generate a hash with the docker image just run:
 
     $ docker run authelia/authelia:latest authelia hash-password yourpassword
-    $ Password hash: $argon2id$v=19$m=65536$3oc26byQuSkQqksq$zM1QiTvVPrMfV6BVLs2t4gM+af5IN7euO0VB6+Q8ZFs
+    Password hash: $argon2id$v=19$m=65536$3oc26byQuSkQqksq$zM1QiTvVPrMfV6BVLs2t4gM+af5IN7euO0VB6+Q8ZFs
 
 Full CLI Help Documentation:
 
@@ -116,8 +118,10 @@ to creating the hash. This is due to how [Go](https://golang.org/) allocates mem
 generating an argon2id hash. Go periodically garbage collects the heap, however this doesn't remove
 the memory allocation, it keeps it allocated even though it's technically unused. Under memory
 pressure the unused allocated memory will be reclaimed by the operating system, you can test
-this on linux with 
+this on linux with: 
-`stress-ng --vm-bytes $(awk '/MemFree/{printf "%d\n", $2 * 0.9;}' < /proc/meminfo)k --vm-keep -m 1`.
+
+    $ stress-ng --vm-bytes $(awk '/MemFree/{printf "%d\n", $2 * 0.9;}' < /proc/meminfo)k --vm-keep -m 1
+    
 If this is not desirable we recommend investigating the following options in order of most to least secure:
   1. using the [LDAP authentication provider](./ldap.md)
   2. adjusting the [memory](#memory) parameter

docs/configuration/authentication/ldap.md

@@ -16,66 +16,66 @@ Configuration of the LDAP backend is done as follows
 
 ```yaml
 authentication_backend:
-    disable_reset_password: false
+  disable_reset_password: false
-    ldap:
+  ldap:
-        # The url to the ldap server. Scheme can be ldap:// or ldaps://
+    # The url to the ldap server. Scheme can be ldap:// or ldaps://
-        url: ldap://127.0.0.1
+    url: ldap://127.0.0.1
 
-        # Skip verifying the server certificate (to allow self-signed certificate).
+    # Skip verifying the server certificate (to allow self-signed certificate).
-        skip_verify: false
+    skip_verify: false
 
-        # The base dn for every entries
+    # The base dn for every entries
-        base_dn: dc=example,dc=com
+    base_dn: dc=example,dc=com
 
-        # The attribute holding the username of the user. This attribute is used to populate
+    # The attribute holding the username of the user. This attribute is used to populate
-        # the username in the session information. It was introduced due to #561 to handle case
+    # the username in the session information. It was introduced due to #561 to handle case
-        # insensitive search queries.
+    # insensitive search queries.
-        # For you information, Microsoft Active Directory usually uses 'sAMAccountName' and OpenLDAP
+    # For you information, Microsoft Active Directory usually uses 'sAMAccountName' and OpenLDAP
-        # usually uses 'uid'
+    # usually uses 'uid'
-        username_attribute: uid
+    username_attribute: uid
     
-        # An additional dn to define the scope to all users
+    # An additional dn to define the scope to all users
-        additional_users_dn: ou=users
+    additional_users_dn: ou=users
     
-        # The users filter used in search queries to find the user profile based on input filled in login form.
+    # The users filter used in search queries to find the user profile based on input filled in login form.
-        # Various placeholders are available to represent the user input and back reference other options of the configuration:
+    # Various placeholders are available to represent the user input and back reference other options of the configuration:
-        # - {input} is a placeholder replaced by what the user inputs in the login form. 
+    # - {input} is a placeholder replaced by what the user inputs in the login form. 
-        # - {username_attribute} is a placeholder replaced by what is configured in `username_attribute`.
+    # - {username_attribute} is a placeholder replaced by what is configured in `username_attribute`.
-        # - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
+    # - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
-        # - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later versions, so please don't use it.
+    # - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later versions, so please don't use it.
-        #
+    #
-        # Recommended settings are as follows:
+    # Recommended settings are as follows:
-        # - Microsoft Active Directory: (&({username_attribute}={input})(objectCategory=person)(objectClass=user))
+    # - Microsoft Active Directory: (&({username_attribute}={input})(objectCategory=person)(objectClass=user))
-        # - OpenLDAP: (&({username_attribute}={input})(objectClass=person))' or '(&({username_attribute}={input})(objectClass=inetOrgPerson))
+    # - OpenLDAP: (&({username_attribute}={input})(objectClass=person))' or '(&({username_attribute}={input})(objectClass=inetOrgPerson))
-        #
+    #
-        # To allow sign in both with username and email, one can use a filter like
+    # To allow sign in both with username and email, one can use a filter like
-        # (&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
+    # (&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
-        users_filter: (&({username_attribute}={input})(objectClass=person))
+    users_filter: (&({username_attribute}={input})(objectClass=person))
     
-        # An additional dn to define the scope of groups
+    # An additional dn to define the scope of groups
-        additional_groups_dn: ou=groups
+    additional_groups_dn: ou=groups
     
-        # The groups filter used in search queries to find the groups of the user.
+    # The groups filter used in search queries to find the groups of the user.
-        # - {input} is a placeholder replaced by what the user inputs in the login form.
+    # - {input} is a placeholder replaced by what the user inputs in the login form.
-        # - {username} is a placeholder replace by the username stored in LDAP (based on `username_attribute`).
+    # - {username} is a placeholder replace by the username stored in LDAP (based on `username_attribute`).
-        # - {dn} is a matcher replaced by the user distinguished name, aka, user DN.
+    # - {dn} is a matcher replaced by the user distinguished name, aka, user DN.
-        # - {username_attribute} is a placeholder replaced by what is configured in `username_attribute`.
+    # - {username_attribute} is a placeholder replaced by what is configured in `username_attribute`.
-        # - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
+    # - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
-        # - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later versions, so please don't use it.
+    # - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later versions, so please don't use it.
-        # - DON'T USE - {1} is an alias for {username} supported for backward compatibility but it will be deprecated in later version, so please don't use it.
+    # - DON'T USE - {1} is an alias for {username} supported for backward compatibility but it will be deprecated in later version, so please don't use it.
-        groups_filter: (&(member={dn})(objectclass=groupOfNames))
+    groups_filter: (&(member={dn})(objectclass=groupOfNames))
     
-        # The attribute holding the name of the group
+    # The attribute holding the name of the group
-        group_name_attribute: cn
+    group_name_attribute: cn
     
-        # The attribute holding the mail address of the user
+    # The attribute holding the mail address of the user
-        mail_attribute: mail
+    mail_attribute: mail
     
-        # The username and password of the admin user.
+    # The username and password of the admin user.
-        user: cn=admin,dc=example,dc=com
+    user: cn=admin,dc=example,dc=com
     
-        # This secret can also be set using the env variables AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD
+    # This secret can also be set using the env variables AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD
-        password: password
+    password: password
 ```
 
 The user must have an email address in order for Authelia to perform

docs/configuration/duo-push-notifications.md

@@ -15,11 +15,13 @@ to know how to set up push notifications in Authelia.
 ## Configuration
 
 The configuration is as follows:
+```yaml
+duo_api:
+  hostname: api-123456789.example.com
+  integration_key: ABCDEF
+  secret_key: 1234567890abcdefghifjkl
+```
 
-    duo_api:
-        hostname: api-123456789.example.com
-        integration_key: ABCDEF
-        secret_key: 1234567890abcdefghifjkl
 
 The secret key is shown as an example, you also have the option to set it using an environment
 variable as described [here](./secrets.md).

docs/configuration/google-analytics.md

@@ -10,4 +10,6 @@ nav_order: 4
 It is possible to provide a Google Analytics ID to Authelia in order
 to monitor the usage of the Sign-In portal.
 
-    google_analytics: UA-00000-01
+```yaml
+google_analytics: UA-00000-01
+```

docs/configuration/miscellaneous.md

@@ -15,8 +15,10 @@ Here are the main customizable options in Authelia.
 
 Defines the address and port to listen on.
 
-    host: 0.0.0.0
+```yaml
-    port: 9091
+host: 0.0.0.0
+port: 9091
+```
 
 ## TLS
 
@@ -25,9 +27,10 @@ Defines the address and port to listen on.
 Authelia can use TLS. Provide the certificate and the key with the
 following configuration options:
 
-    tls_key: /var/lib/authelia/ssl/key.pem
+```yaml
-    tls_cert: /var/lib/authelia/ssl/cert.pem
+tls_key: /var/lib/authelia/ssl/key.pem
-
+tls_cert: /var/lib/authelia/ssl/cert.pem
+```
 
 ## Log
 
@@ -38,7 +41,9 @@ following configuration options:
 Defines the level of logs used by Authelia. This level can be set to
 `trace`, `debug` or `info`.
 
-    log_level: debug
+```yaml
+log_level: debug
+```
 
 ### Log file path
 
@@ -47,7 +52,9 @@ Defines the level of logs used by Authelia. This level can be set to
 Logs can be stored in a file when file path is provided. Otherwise logs
 are written to standard output.
 
-    log_file_path: /var/log/authelia.log
+```yaml
+log_file_path: /var/log/authelia.log
+```
 
 
 ## JWT Secret
@@ -57,7 +64,9 @@ are written to standard output.
 Defines the secret used to craft JWT tokens leveraged by the identity
 verification process
 
-    jwt_secret: v3ry_important_s3cr3t
+```yaml
+jwt_secret: v3ry_important_s3cr3t
+```
 
 ## Default redirection URL
 

docs/configuration/notifier/filesystem.md

@@ -13,6 +13,6 @@ should only be used for testing purposes.
 
 ```yaml
 notifier:
-    filesystem:
+  filesystem:
-        filename: /tmp/authelia/notification.txt
+    filename: /tmp/authelia/notification.txt
 ```

docs/configuration/notifier/smtp.md

@@ -55,11 +55,11 @@ described [here](https://support.google.com/accounts/answer/185833?hl=en)
 
 ```yaml
 notifier:
-    smtp:
+  smtp:
-        username: myaccount@gmail.com
+    username: myaccount@gmail.com
-        # This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD
+    # This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD
-        password: yourapppassword
+    password: yourapppassword
-        sender: admin@example.com
+    sender: admin@example.com
-        host: smtp.gmail.com
+    host: smtp.gmail.com
-        port: 587
+    port: 587
 ```

docs/configuration/one-time-password.md

@@ -11,10 +11,13 @@ Authelia uses time based one-time passwords as the OTP method. You have
 the option to tune the settings of the TOTP generation and you can see a
 full example of TOTP configuration below, as well as sections describing them.
 
-    totp:
+```yaml
-        issuer: authelia.com
+totp:
-        period: 30
+  issuer: authelia.com
-        skew: 1
+  period: 30
+  skew: 1
+```
+
         
 ## Issuer
 

docs/configuration/regulation.md

@@ -14,18 +14,18 @@ authentication attempts. This helps prevent brute-force attacks.
 
 ```yaml
 regulation:
-    # The number of failed login attempts before user is banned.
+  # The number of failed login attempts before user is banned.
-    # Set it to 0 to disable regulation.
+  # Set it to 0 to disable regulation.
-    max_retries: 3
+  max_retries: 3
 
-    # The time range during which the user can attempt login before being banned.
+  # The time range during which the user can attempt login before being banned.
-    # The user is banned if the authentication failed `max_retries` times in a `find_time` seconds window.
+  # The user is banned if the authentication failed `max_retries` times in a `find_time` seconds window.
-    # Find Time accepts duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
+  # Find Time accepts duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
-    find_time: 2m
+  find_time: 2m
 
-    # The length of time before a banned user can sign in again.
+  # The length of time before a banned user can sign in again.
-    # Find Time accepts duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
+  # Find Time accepts duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
-    ban_time: 5m
+  ban_time: 5m
 ```
 
 ### Duration Notation

docs/configuration/storage/mariadb.md

@@ -10,11 +10,11 @@ nav_order: 1
 
 ```yaml
 storage:
-    mysql:
+  mysql:
-        host: 127.0.0.1
+    host: 127.0.0.1
-        port: 3306
+    port: 3306
-        database: authelia
+    database: authelia
-        username: authelia
+    username: authelia
-        # This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD
+    # This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD
-        password: mypassword
+    password: mypassword
 ```

docs/configuration/storage/mysql.md

@@ -10,11 +10,11 @@ nav_order: 2
 
 ```yaml
 storage:
-    mysql:
+  mysql:
-        host: 127.0.0.1
+    host: 127.0.0.1
-        port: 3306
+    port: 3306
-        database: authelia
+    database: authelia
-        username: authelia
+    username: authelia
-        # This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD
+    # This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD
-        password: mypassword
+    password: mypassword
 ```

docs/configuration/storage/postgres.md

@@ -10,11 +10,11 @@ nav_order: 3
 
 ```yaml
 storage:
-    postgres:
+  postgres:
-        host: 127.0.0.1
+    host: 127.0.0.1
-        port: 5432
+    port: 5432
-        database: authelia
+    database: authelia
-        username: authelia
+    username: authelia
-        # This secret can also be set using the env variables AUTHELIA_STORAGE_POSTGRES_PASSWORD
+    # This secret can also be set using the env variables AUTHELIA_STORAGE_POSTGRES_PASSWORD
-        password: mypassword
+    password: mypassword
 ```

docs/configuration/storage/sqlite.md

@@ -18,6 +18,6 @@ Just give the path to the sqlite database. It will be created if the file does n
 
 ```yaml
 storage:
-    local:
+  local:
-        path: /var/lib/authelia/db.sqlite3
+    path: /var/lib/authelia/db.sqlite3
 ```

docs/contributing/authelia-scripts.md

@@ -12,22 +12,22 @@ testing the code, etc...
 
 Those scripts becomes available after sourcing the bootstrap.sh script with
 
-    source bootstrap.sh
+    $ source bootstrap.sh
 
 Then, you can access the scripts usage by running the following command:
 
-    authelia-scripts --help
+    $ authelia-scripts --help
 
 For instance, you can build Authelia (Go binary and frontend) with:
 
-    authelia-scripts build
+    $ authelia-scripts build
 
 Or build the official Docker image with:
 
-    authelia-scripts docker build
+    $ authelia-scripts docker build
 
 Or start the *Standalone* suite with:
 
-    authelia-scripts suites setup Standalone
+    $ authelia-scripts suites setup Standalone
 
 You will find more information in the scripts usage helpers.

docs/contributing/suites.md

@@ -46,7 +46,7 @@ specific suite like *HighAvailability*, you can do so with the next command:
 
 Running all tests is easy. Make sure that no suite is already running and run:
 
-    authelia-scripts suites test
+    $ authelia-scripts suites test
 
 ### Run tests in headless mode
 

docs/features/password-reset.md

@@ -7,9 +7,10 @@ nav_order: 4
 
 # Password Reset
 
-**Authelia** provides workflow to let users reset their password when they lose it.
+**Authelia** provides a workflow to let users reset their password when they lose it.
+To disable reset password functionality please see the [configuration docs](../configuration/authentication/index.md#disabling-reset-password).
 
-A simple click on `Forgot password?` for starting the process. Note that resetting a
+A simple click on `Reset password?` for starting the process. Note that resetting a
 password requires a new identity verification using the e-mail of the user.
 
 <p align="center">
@@ -22,7 +23,7 @@ Give your username and receive an e-mail to verify your identity.
   <img src="../images/RESET-PASSWORD-STEP1.png" width="400">
 </p>
 
-Once your identity is verified, fill in the form to reset your password.
+Once your identity has been verified, fill in the form to reset your password.
 
 <p align="center">
   <img src="../images/RESET-PASSWORD-STEP2.png" width="400">

docs/security/index.md

@@ -7,9 +7,11 @@ has_children: true
 
 # Security
 
-Security is taken very seriously here, therefore we follow the rule of
+Authelia takes security very seriously. We follow the rule of 
-responsible disclosure and we encourage you to do so.
+[responsible disclosure](https://en.wikipedia.org/wiki/Responsible_disclosure), and we 
+encourage the community to as well.
 
-Would you like to report any vulnerability discovered in Authelia, please
+
-first contact **clems4ever** on [Matrix](https://riot.im/app/#/room/#authelia:matrix.org)
+If you discover a vulnerability in Authelia, please first contact **clems4ever** on 
-or by [email](mailto:clement.michaud34@gmail.com).
+[Matrix](https://riot.im/app/#/room/#authelia:matrix.org) or by
+[email](mailto:clement.michaud34@gmail.com).