[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,9 +92,9 @@ configure Authelia accordingly.
 
 Here is a complete example of complex access control list that can be defined in Authelia.
 
+```yaml
 access_control:
   default_policy: deny
-
   rules:
     - domain: public.example.com
       policy: bypass
@@ -129,3 +129,4 @@ Here is a complete example of complex access control list that can be defined in
       - "^/users/john/.*$"
       subject: "user:john"
       policy: two_factor
+```

docs/configuration/authentication/file.md

@@ -15,6 +15,7 @@ nav_order: 1
 Configuring Authelia to use a file is done by specifying the path to the
 file in the configuration file.
 
+```yaml
 authentication_backend:
   disable_reset_password: false
   file:
@@ -25,12 +26,15 @@ file in the configuration file.
       salt_length: 16
       parallelism: 8
       memory: 1024
+```
+
 
 
 ## Format
 
 The format of the users file is as follows.
 
+```yaml
 users:
   john:
     password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
@@ -38,21 +42,19 @@ The format of the users file is as follows.
     groups:
       - admins
       - dev
-
   harry:
     password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
     email: harry.potter@authelia.com
     groups: []
-
   bob:
     password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
     email: bob.dylan@authelia.com
     groups:
       - dev
-
   james:
     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 
-`stress-ng --vm-bytes $(awk '/MemFree/{printf "%d\n", $2 * 0.9;}' < /proc/meminfo)k --vm-keep -m 1`.
+this on linux with: 
+
+    $ 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/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
+```
+
 
 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.
 
+```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.
 
+```yaml
 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:
 
+```yaml
 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`.
 
+```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.
 
+```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
 
+```yaml
 jwt_secret: v3ry_important_s3cr3t
+```
 
 ## Default redirection URL
 

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.
 
+```yaml
 totp:
   issuer: authelia.com
   period: 30
   skew: 1
+```
+
         
 ## Issuer
 

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
-responsible disclosure and we encourage you to do so.
+Authelia takes security very seriously. We follow the rule of 
+[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)
-or by [email](mailto:clement.michaud34@gmail.com).
+
+If you discover a vulnerability in Authelia, please first contact **clems4ever** on 
+[Matrix](https://riot.im/app/#/room/#authelia:matrix.org) or by
+[email](mailto:clement.michaud34@gmail.com).