Merge pull request #722 from hedgedoc/docs/various-fixes

docs/content/guides/auth/github.md

@@ -17,7 +17,7 @@
 
 6. Add the Client ID and Client Secret to your config.json file or pass them as environment variables
   - `config.json`:
-    ```js
+    ```json
     {
       "production": {
         "github": {
@@ -29,7 +29,7 @@
     ```
 
   - environment variables:
-    ```sh
+    ```shell
     CMD_GITHUB_CLIENTID=3747d30eaccXXXXXXXXX
     CMD_GITHUB_CLIENTSECRET=2a8e682948eee0c580XXXXXXXXXXXXXXXXXXXXXX
-    ````
+    ```

docs/content/guides/auth/gitlab-self-hosted.md

@@ -1,30 +1,31 @@
 # GitLab (self-hosted)
 
-*Note:* This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind :smile: thanks!
+**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind 😃 thanks!*
 
 1. Sign in to your GitLab
 2. Navigate to the application management page at `https://your.gitlab.domain/admin/applications` (admin permissions required)
 3. Click **New application** to create a new application and fill out the registration form:
 
-![New GitLab application](../../images/auth/gitlab-new-application.png)
+    ![New GitLab application](../../images/auth/gitlab-new-application.png)
 
 4. Click **Submit**
-5. In the list of applications select **HackMD**. Leave that site open to copy the application ID and secret in the next step.
+5. In the list of applications select **HackMD**. Leave that site open to copy the application ID and secret in the next
+   step.
 
-![Application: HackMD](../../images/auth/gitlab-application-details.png)
+   ![Application: HackMD](../../images/auth/gitlab-application-details.png)
 
 6. In the `docker-compose.yml` add the following environment variables to `app:` `environment:`
 
-```Dockerfile
+    ```yaml
-- CMD_DOMAIN=your.hedgedoc.domain
+    - CMD_DOMAIN=your.hedgedoc.domain
-- CMD_URL_ADDPORT=true
+    - CMD_URL_ADDPORT=true
-- CMD_PROTOCOL_USESSL=true
+    - CMD_PROTOCOL_USESSL=true
-- CMD_GITLAB_BASEURL=https://your.gitlab.domain
+    - CMD_GITLAB_BASEURL=https://your.gitlab.domain
-- CMD_GITLAB_CLIENTID=23462a34example99XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+    - CMD_GITLAB_CLIENTID=23462a34example99XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-- CMD_GITLAB_CLIENTSECRET=5532e9dexamplXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+    - CMD_GITLAB_CLIENTSECRET=5532e9dexamplXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-```
+    ```
 
 7. Run `docker-compose up -d` to apply your settings.
 8. Sign in to your HedgeDoc using your GitLab ID:
 
-![Sign in via GitLab](../../images/auth/gitlab-sign-in.png)
+   ![Sign in via GitLab](../../images/auth/gitlab-sign-in.png)

docs/content/guides/auth/keycloak.md

@@ -30,7 +30,7 @@ You may note that a separate realm is specified throughout this tutorial. It is
 
 5. In the `docker-compose.yml` add the following environment variables to `app:` `environment:`
 
-```Dockerfile
+```yaml
 CMD_OAUTH2_USER_PROFILE_URL=https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/userinfo
 CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=preferred_username
 CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=name

docs/content/guides/auth/ldap-ad.md

@@ -2,19 +2,22 @@
 
 To setup your HedgeDoc instance with Active Directory you need the following configs:
 
-```env
+```shell
 CMD_LDAP_URL=ldap://internal.example.com
 CMD_LDAP_BINDDN=cn=binduser,cn=Users,dc=internal,dc=example,dc=com
-CMD_LDAP_BINDCREDENTIALS=<super secret password>
+CMD_LDAP_BINDCREDENTIALS="<super secret password>"
 CMD_LDAP_SEARCHBASE=dc=internal,dc=example,dc=com
 CMD_LDAP_SEARCHFILTER=(&(objectcategory=person)(objectclass=user)(|(sAMAccountName={{username}})(mail={{username}})))
 CMD_LDAP_USERIDFIELD=sAMAccountName
-CMD_LDAP_PROVIDERNAME=Example Inc AD
+CMD_LDAP_PROVIDERNAME="Example Inc AD"
 ```
 
-`CMD_LDAP_BINDDN` is either the `distinguishedName` or the `userPrincipalName`. *This can cause "username/password is invalid" when either this value or the password from `CMD_LDAP_BINDCREDENTIALS` are incorrect.*
+`CMD_LDAP_BINDDN` is either the `distinguishedName` or the `userPrincipalName`.  
+*This can cause "username/password is invalid" when either this value or the password from `CMD_LDAP_BINDCREDENTIALS`
+are incorrect.*
 
-`CMD_LDAP_SEARCHFILTER` matches on all users and uses either the email address or the `sAMAccountName` (usually the login name you also use to login to Windows).
+`CMD_LDAP_SEARCHFILTER` matches on all users and uses either the email address or the `sAMAccountName` (usually the
+login name you also use to login to Windows).
 
 *Only using `sAMAccountName` looks like this:* `(&(objectcategory=person)(objectclass=user)(sAMAccountName={{username}}))`
 

docs/content/guides/auth/mattermost-self-hosted.md

@@ -24,7 +24,7 @@ This guide uses the generic OAuth2 module for compatibility with Mattermost vers
 
 7. Add the Client ID and Client Secret to your config.json file or pass them as environment variables
   - `config.json`:
-    ```javascript
+    ```json
     {
       "production": {
         "oauth2": {

docs/content/guides/auth/nextcloud.md

@@ -1,8 +1,13 @@
 # Authentication guide - Nextcloud (self-hosted)
 
-*This has been constructed using the [Nextcloud OAuth2 Documentation](https://docs.nextcloud.com/server/14/admin_manual/configuration_server/oauth2.html?highlight=oauth2) combined with [this issue comment on the nextcloud bugtracker](https://github.com/nextcloud/server/issues/5694#issuecomment-314761326).*
+*This has been constructed using
+the [Nextcloud OAuth2 Documentation](https://docs.nextcloud.com/server/14/admin_manual/configuration_server/oauth2.html?highlight=oauth2)
+combined
+with [this issue comment on the nextcloud bugtracker](https://github.com/nextcloud/server/issues/5694#issuecomment-314761326)
+.*
 
-This guide uses the generic OAuth2 module for compatibility with Nextcloud 13 and above (this guide has been tested successfully with Nextcloud 14).
+This guide uses the generic OAuth2 module for compatibility with Nextcloud 13 and above (this guide has been tested
+successfully with Nextcloud 14 and Nextcloud 20).
 
 1. Sign-in with an administrator account to your Nextcloud server
 
@@ -18,35 +23,39 @@ This guide uses the generic OAuth2 module for compatibility with Nextcloud 13 an
 4. You'll now see a line containing a *client identifier* and a *Secret*.
    ![Successfully added OAuth2-client](../../images/auth/nextcloud-oauth2-3-clientid-secret.png)
 
-5. That's it for Nextcloud, the rest is configured in your HedgeDoc `config.json` or via the `CMD_` environment variables!
+5. That's it for Nextcloud, the rest is configured in your HedgeDoc `config.json` or via the `CMD_` environment
+   variables!
 
-6. Add the Client ID and Client Secret to your `config.json` file or pass them as environment variables. Make sure you also replace `<your-nextcloud-domain>` with the right domain name.
+6. Add the Client ID and Client Secret to your `config.json` file or pass them as environment variables. Make sure you
+   also replace `<your-nextcloud-domain>` with the right domain name.
   - `config.json`:
-    ```javascript
+
+    ```json
     {
       "production": {
         "oauth2": {
-          "clientID": "ii4p1u3jz7dXXXXXXXXXXXXXXX",
+            "clientID": "ii4p1u3jz7dXXXXXXXXXXXXXXX",
-          "clientSecret": "mqzzx6fydbXXXXXXXXXXXXXXXX",
+            "clientSecret": "mqzzx6fydbXXXXXXXXXXXXXXXX",
-          "authorizationURL": "https://<your-nextcloud-domain>/apps/oauth2/authorize",
+            "authorizationURL": "https://<your-nextcloud-domain>/apps/oauth2/authorize",
-          "tokenURL": "https://<your-nextcloud-domain>/apps/oauth2/api/v1/token",
+            "tokenURL": "https://<your-nextcloud-domain>/apps/oauth2/api/v1/token",
-          "userProfileURL": "https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json",
+            "userProfileURL": "https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json",
-          "userProfileUsernameAttr": "ocs.data.id",
+            "userProfileUsernameAttr": "ocs.data.id",
-          "userProfileDisplayNameAttr": "ocs.data.display-name",
+            "userProfileDisplayNameAttr": "ocs.data.display-name",
-          "userProfileEmailAttr": "ocs.data.email"
+            "userProfileEmailAttr": "ocs.data.email"
         }
       }
     }
     ```
 
-    - environment variables:
+  - environment variables:
-      ```sh
+
-      CMD_OAUTH2_CLIENT_ID=ii4p1u3jz7dXXXXXXXXXXXXXXX
+    ```sh
-      CMD_OAUTH2_CLIENT_SECRET=mqzzx6fydbXXXXXXXXXXXXXXXX
+    CMD_OAUTH2_CLIENT_ID=ii4p1u3jz7dXXXXXXXXXXXXXXX
-      CMD_OAUTH2_AUTHORIZATION_URL=https://<your-nextcloud-domain>/apps/oauth2/authorize
+    CMD_OAUTH2_CLIENT_SECRET=mqzzx6fydbXXXXXXXXXXXXXXXX
-      CMD_OAUTH2_TOKEN_URL=https://<your-nextcloud-domain>/apps/oauth2/api/v1/token
+    CMD_OAUTH2_AUTHORIZATION_URL=https://<your-nextcloud-domain>/apps/oauth2/authorize
-      CMD_OAUTH2_USER_PROFILE_URL=https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json
+    CMD_OAUTH2_TOKEN_URL=https://<your-nextcloud-domain>/apps/oauth2/api/v1/token
-      CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=ocs.data.id
+    CMD_OAUTH2_USER_PROFILE_URL=https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json
-      CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=ocs.data.display-name
+    CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=ocs.data.id
-      CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=ocs.data.email
+    CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=ocs.data.display-name
-      ```
+    CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=ocs.data.email
+    ```

docs/content/guides/auth/saml-keycloak.md

@@ -107,7 +107,7 @@ The configured mappers should look like this:
 }
 ```
 It you configure HedgeDoc with enviroment variables, these are the ones you have to set:
-```bash
+```shell
 CMD_SAML_ATTRIBUTE_USERNAME=username
 CMD_SAML_ATTRIBUTE_EMAIL=email
 ```

docs/content/guides/auth/saml-onelogin.md

@@ -1,6 +1,6 @@
 # Authentication guide - SAML (OneLogin)
 
-**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind :smile: thanks!*
+**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind 😃 thanks!*
 
 1. Sign-in or sign-up for an OneLogin account. (available free trial for 2 weeks)
 
@@ -34,7 +34,7 @@
 8. In your HedgeDoc server, create IdP certificate file from (A)
 9. Add the IdP URL (B) and the Idp certificate file path to your config.json file or pass them as environment variables.
   - `config.json`:
-    ```javascript
+    ```json
     {
       "production": {
         "saml": {
@@ -46,7 +46,7 @@
     ```
 
     - environment variables
-      ```sh
+      ```shell
       CMD_SAML_IDPSSOURL=https://*******.onelogin.com/trust/saml2/http-post/sso/******
       CMD_SAML_IDPCERT=/path/to/idp_cert.pem
       ```

docs/content/guides/auth/saml.md

@@ -1,17 +1,19 @@
 # Authentication guide - SAML
 
-*Note:* This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind :smile: thanks!
+*Note:* This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind 😃 thanks!
 
-The basic procedure is the same as the case of OneLogin which is mentioned in [OneLogin-Guide](./saml-onelogin.md). If you want to match your IdP, you can use more configurations as below.
+The basic procedure is the same as the case of OneLogin which is mentioned in [OneLogin-Guide](./saml-onelogin.md). If
+you want to match your IdP, you can use more configurations as below.
 
-- If your IdP accepts metadata XML of the service provider to ease configuration, use this url to download metadata XML.
+- If your IdP accepts metadata XML of the service provider to ease configuration, use this url to download metadata XML:
-    - {{your-serverurl}}/auth/saml/metadata
+  `{{your-serverurl}}/auth/saml/metadata`  
-    - *Note:* If not accessible from IdP, download to local once and upload to IdP.
+  *Note:* If not accessible from IdP, download to local once and upload to IdP.
 
 - Change the value of `issuer`, `identifierFormat` to match your IdP.
   - `issuer`: A unique id to identify the application to the IdP, which is the base URL of your HedgeDoc as default
 
-  - `identifierFormat`: A format of unique id to identify the user of IdP, which is the format based on email address as default. It is recommend that you use as below.
+  - `identifierFormat`: A format of unique id to identify the user of IdP, which is the format based on email address as
+    default. It is recommend that you use as below.
     - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (default)
     - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
 
@@ -29,23 +31,24 @@ The basic procedure is the same as the case of OneLogin which is mentioned in [O
     ```
 
   - environment variables
-    ```env
+    ```shell
     CMD_SAML_ISSUER=myhedgedoc
     CMD_SAML_IDENTIFIERFORMAT=urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
     ```
 
 - Change mapping of attribute names to customize the displaying user name and email address to match your IdP.
   - `attribute`: A dictionary to map attribute names
-  
+
   - `attribute.id`: A primary key of user table for your HedgeDoc
-  
+
   - `attribute.username`: Attribute name of displaying user name on HedgeDoc
-  
+
   - `attribute.email`: Attribute name of email address, which will be also used for Gravatar
-    - *Note:* Default value of all attributes is NameID of SAML response, which is email address if `identifierFormat` is default.
+    - *Note:* Default value of all attributes is NameID of SAML response, which is email address if `identifierFormat`
+      is default.
 
   - `config.json`:
-    ```javascript
+    ```json
     {
       "production": {
         "saml": {
@@ -61,22 +64,25 @@ The basic procedure is the same as the case of OneLogin which is mentioned in [O
     ```
 
   - environment variables
-    ```sh
+    ```shell
     CMD_SAML_ATTRIBUTE_ID=sAMAccountName
     CMD_SAML_ATTRIBUTE_USERNAME=nickName
     CMD_SAML_ATTRIBUTE_EMAIL=mail
     ```
 
-- If you want to control permission by group membership, add group attribute name and required group (allowed) or external group (not allowed).
+- If you want to control permission by group membership, add group attribute name and required group (allowed) or
+  external group (not allowed).
   - `groupAttribute`: An attribute name of group membership
 
-  - `requiredGroups`: Group names array for allowed access to HedgeDoc. Use vertical bar to separate for environment variables.
+  - `requiredGroups`: Group names array for allowed access to HedgeDoc. Use vertical bar to separate for environment
+    variables.
 
-  - `externalGroups`: Group names array for not allowed access to HedgeDoc. Use vertical bar to separate for environment variables.
+  - `externalGroups`: Group names array for not allowed access to HedgeDoc. Use vertical bar to separate for environment
+    variables.
     - *Note:* Evaluates `externalGroups` first
 
   - `config.json`:
-    ```javascript
+    ```json
     {
       "production": {
         "saml": {
@@ -90,7 +96,7 @@ The basic procedure is the same as the case of OneLogin which is mentioned in [O
     ```
 
   - environment variables
-    ```sh
+    ```shell
     CMD_SAML_GROUPATTRIBUTE=memberOf
     CMD_SAML_REQUIREDGROUPS=hedgedoc-users|board-members
     CMD_SAML_EXTERNALGROUPS=temporary-staff

docs/content/guides/auth/twitter.md

@@ -1,6 +1,6 @@
 # Authentication guide - Twitter
 
-*Note:* This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind :smile: thanks!
+**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind 😃 thanks!*
 
 1. Sign-in or sign-up for a Twitter account
 
@@ -24,7 +24,7 @@
 
 7. Add your Consumer Key and Consumer Secret to your `config.json` file or pass them as environment variables:
   - `config.json`:
-    ```javascript
+    ```json
     {
       "production": {
         "twitter": {
@@ -36,7 +36,7 @@
     ```
 
   - environment variables:
-    ```sh
+    ```shell
     CMD_TWITTER_CONSUMERKEY=esTCJFXXXXXXXXXXXXXXXXXXX
     CMD_TWITTER_CONSUMERSECRET=zpCs4tU86pRVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
     ```

docs/content/guides/minio-image-upload.md

@@ -1,6 +1,6 @@
 # Minio Guide for HedgeDoc
 
-*Note:* This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind :smile: thanks!
+**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind 😃 thanks!*
 
 1. First of all you need to setup Minio itself.
 
@@ -91,4 +91,4 @@ You could use a convenience script located in `bin/migrate_from_fs_to_minio`.
 
 Be careful, read carefully what it does, it was not tested in all environments.
 
-Take it as an inspiration to make your own migration script.
+Take it as an inspiration to make your own migration script.

docs/content/guides/s3-image-upload.md

@@ -1,6 +1,6 @@
 # Guide - Setup HedgeDoc S3 image upload
 
-**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind :smile: thanks!*
+**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind 😃 thanks!*
 
 1. Go to [AWS S3 console](https://console.aws.amazon.com/s3/home) and create a new bucket.
    ![create-bucket](../images/s3-image-upload/create-bucket.png)

docs/mkdocs.yml

@@ -19,20 +19,20 @@ nav:
       - Authentication:
           - LDAP: guides/auth/ldap-ad.md
           - OAuth: guides/auth/oauth.md
-          - SAML : guides/auth/saml.md
+          - SAML: guides/auth/saml.md
-          - SAML Keycloak : guides/auth/saml-keycloak.md
+          - SAML Keycloak: guides/auth/saml-keycloak.md
-          - SAML Onelogin : guides/auth/saml-onelogin.md
+          - SAML OneLogin: guides/auth/saml-onelogin.md
           - GitHub: guides/auth/github.md
           - GitLab: guides/auth/gitlab-self-hosted.md
           - Keycloak: guides/auth/keycloak.md
-          - NextCloud: guides/auth/nextcloud.md
+          - Nextcloud: guides/auth/nextcloud.md
           - Twitter: guides/auth/twitter.md
+      - Media Backend:
+          - MinIO: guides/minio-image-upload.md
+          - S3: guides/s3-image-upload.md
       - Migrate from Etherpad: guides/migrate-etherpad.md
       - Breaking Changes: guides/migrations-and-breaking-changes.md
-      - Media Backend:
+      - Terms of Use Setup: guides/providing-terms.md
-          - Minion: guides/minio-image-upload.md
-          - S3: guides/s3-image-upload.md
-      - Setting Terms: guides/providing-terms.md
   - Configuration: configuration.md
   - Developer:
       - 'Getting Started': dev/getting-started.md
@@ -44,6 +44,9 @@ nav:
 markdown_extensions:
   - toc:
       permalink: true
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - mdx_truly_sane_lists
 theme:
   name: 'material'
   language: en

docs/requirements.txt

@@ -1,3 +1,4 @@
 mkdocs==1.1.2
 mkdocs-material==6.2.3
 pymdown-extensions==8.1
+mdx_truly_sane_lists==1.2