diff --git a/docs/content/config/index.md b/docs/content/config/index.md index 500e5d2de..b1c700a26 100644 --- a/docs/content/config/index.md +++ b/docs/content/config/index.md @@ -1,3 +1,5 @@ +# Configuration + HedgeDoc can be configured via environment variables either directly or via an `.env` file. ## The `.env` file @@ -5,6 +7,7 @@ HedgeDoc can be configured via environment variables either directly or via an ` The `.env` file should be placed in the root of the project and contains key-value pairs of environment variables and their corresponding value. This can for example look like this: + ```ini HD_BASE_URL="http://localhost:8080" HD_SESSION_SECRET="change_me_in_production" @@ -13,9 +16,10 @@ HD_DATABASE_NAME="./hedgedoc.sqlite" HD_MEDIA_BACKEND="filesystem" HD_MEDIA_BACKEND_FILESYSTEM_UPLOAD_PATH="uploads/" ``` + -We also provide an `.env.example` file containing a minimal configuration in the root of the project. -This should help you to write your own configuration. +We also provide an `.env.example` file containing a minimal configuration +in the root of the project. This should help you to write your own configuration. !!! warning The minimal configuration provided in `.env.example` is exactly that: minimal. @@ -25,7 +29,7 @@ This should help you to write your own configuration. ## General | environment variable | default | example | description | -|--------------------------|------------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------------------ | ---------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `HD_BASE_URL` | - | `https://md.example.com` | The URL the HedgeDoc instance is accessed with, like it is entered in the browser | | `HD_BACKEND_PORT` | 3000 | | The port the backend process listens on. | | `HD_FRONTEND_PORT` | 3001 | | The port the frontend process listens on. | @@ -39,17 +43,17 @@ This should help you to write your own configuration. If the renderer is provided by another domain, it's way harder to manipulate HedgeDoc or steal credentials from the rendered note content, because renderer and editor are more isolated. -This increases the security of the software and greatly mitigates [XSS attacks](https://en.wikipedia.org/wiki/Cross-site_scripting). +This increases the security of the software and greatly mitigates [XSS attacks][xss]. However, you can run HedgeDoc without this extra security, but we recommend using it if possible. !!! note - When you want to use a separate domain for `HD_RENDERER_BASE_URL`, your reverse proxy config needs - to be adjusted to direct requests for this domain to the frontend. + When you want to use a separate domain for `HD_RENDERER_BASE_URL`, your reverse proxy + config needs to be adjusted to direct requests for this domain to the frontend. ## Notes | environment variable | default | example | description | -|-----------------------------------|---------|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| --------------------------------- | ------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `HD_FORBIDDEN_NOTE_IDS` | - | `notAllowed, alsoNotAllowed` | A list of note ids (separated by `,`), that are not allowed to be created or requested by anyone. | | `HD_MAX_DOCUMENT_LENGTH` | 100000 | | The maximum length of any one document. Changes to this will impact performance for your users. | | `HD_GUEST_ACCESS` | `write` | `deny`, `read`, `write`, `create` | Defines the maximum access level for guest users to the instance. If guest access is set lower than the "everyone" permission of a note then the note permission will be overridden. | @@ -64,12 +68,12 @@ However, you can run HedgeDoc without this extra security, but we recommend usin ### Local -HedgeDoc provides local accounts, handled internally. This feature only provides basic functionality, -so for most environments we recommend using an external authentication mechanism, which also enable -more secure authentication like 2FA or WebAuthn. +HedgeDoc provides local accounts, handled internally. This feature only provides basic +functionality, so for most environments we recommend using an external authentication mechanism, +which also enable more secure authentication like 2FA or WebAuthn. | environment variable | default | example | description | -|-------------------------------------------|---------|-------------------------|---------------------------------------------------------------------------------------| +| ----------------------------------------- | ------- | ----------------------- | ------------------------------------------------------------------------------------- | | `HD_AUTH_LOCAL_ENABLE_LOGIN` | `false` | `true`, `false` | This makes it possible to use the local accounts in HedgeDoc. | | `HD_AUTH_LOCAL_ENABLE_REGISTER` | `false` | `true`, `false` | This makes it possible to register new local accounts in HedgeDoc. | | `HD_AUTH_LOCAL_MINIMAL_PASSWORD_STRENGTH` | `2` | `0`, `1`, `2`, `3`, `4` | The minimum [zxcvbn-ts][zxcvbn-ts-score] password score, that passwords need to have. | @@ -79,7 +83,7 @@ more secure authentication like 2FA or WebAuthn. The password score is calculated with [zxcvbn-ts][zxcvbn-ts-score]. | score | meaning | minimum number of guesses required (approximated) | -|:-----:|-------------------------------------------------------------------|---------------------------------------------------| +| :---: | ----------------------------------------------------------------- | ------------------------------------------------- | | 0 | All passwords are allowed | - | | 1 | Only `too guessable` passwords are disallowed | 1.000 | | 2 | `too guessable` and `very guessable` passwords are disallowed | 1.000.000 | @@ -88,11 +92,16 @@ The password score is calculated with [zxcvbn-ts][zxcvbn-ts-score]. ### LDAP -HedgeDoc can use one or multiple LDAP servers to authenticate users. To do this, you first need to tell HedgeDoc the names of servers you want to use (`HD_AUTH_LDAPS`), and then you need to provide the configuration for those LDAP servers depending on how you want to use them. -Each of those variables will contain the given name for this LDAP server. For example if you named your LDAP server `MY_LDAP` all variables for this server will start with `HD_AUTH_LDAP_MY_LDAP`. +HedgeDoc can use one or multiple LDAP servers to authenticate users. To do this, +you first need to tell HedgeDoc the names of servers you want to use (`HD_AUTH_LDAPS`), +and then you need to provide the configuration for those LDAP servers +depending on how you want to use them. +Each of those variables will contain the given name for this LDAP server. +For example if you named your LDAP server `MY_LDAP` all variables for this server +will start with `HD_AUTH_LDAP_MY_LDAP`. | environment variable | default | example | description | -|--------------------------------------------|----------------------|----------------------------------------------------|---------------------------------------------------------------------------------------------------------------| +| ------------------------------------------ | -------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `HD_AUTH_LDAPS` | - | `MY_LDAP` | A comma-seperated list of names of LDAP servers HedgeDoc should use. | | `HD_AUTH_LDAP_$NAME_PROVIDER_NAME` | `LDAP` | `My LDAP` | The display name for the LDAP server, that is shown in the UI of HegdeDoc. | | `HD_AUTH_LDAP_$NAME_URL` | - | `ldaps://ldap.example.com` | The url with which the LDAP server can be accessed. | @@ -110,42 +119,47 @@ Each of those variables will contain the given name for this LDAP server. For ex ## Customization -HedgeDoc allows you to set a name or logo for your organization. How this looks and where this is used, can be seen below. You can also provide a privacy policy, terms of use or an imprint url for your HedgeDoc instance. +HedgeDoc allows you to set a name or logo for your organization. +How this looks and where this is used, can be seen below. +You can also provide a privacy policy, terms of use or an imprint url +for your HedgeDoc instance. -| environment variable | default | example | description | -|-----------------------|---------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `HD_CUSTOM_NAME` | - | `DEMO Corp` | The text will be shown in the top right corner in the editor and on the intro page. If you also configure a custom logo, this will be used as the alt text of the logo. | -| `HD_CUSTOM_LOGO` | - | `https://md.example.com/logo.png` | The logo will be shown in the top right corner in the editor and on the intro page. | -| `HD_PRIVACY_URL` | - | `https://md.example.com/privacy` | The URL that should be linked as the privacy notice in the footer. | -| `HD_TERMS_OF_USE_URL` | - | `https://md.example.com/terms` | The URL that should be linked as the terms of user in the footer. | -| `HD_IMPRINT_URL` | - | `https://md.example.com/imprint` | The URL that should be linked as the imprint in the footer. | +| environment variable | default | example | description | +| --------------------- | ------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `HD_CUSTOM_NAME` | - | `DEMO Corp` | The text will be shown in the top right corner in the editor and on the intro page. If you also configure a custom logo, this will be used as the alt text of the logo. | +| `HD_CUSTOM_LOGO` | - | `https://md.example.com/logo.png` | The logo will be shown in the top right corner in the editor and on the intro page. | +| `HD_PRIVACY_URL` | - | `https://md.example.com/privacy` | The URL that should be linked as the privacy notice in the footer. | +| `HD_TERMS_OF_USE_URL` | - | `https://md.example.com/terms` | The URL that should be linked as the terms of user in the footer. | +| `HD_IMPRINT_URL` | - | `https://md.example.com/imprint` | The URL that should be linked as the imprint in the footer. | ### Example #### Links -![links frontpage](../images/customization/links.png) +![Links on the Frontpage][links-frontpage] *links for the privacy policy, terms of use and imprint on the front page* #### Logo For this demo we use this image: -![demo logo](../images/customization/demo_logo.png) +![The demo logo][demo-logo] -![logo front page](../images/customization/logo/frontpage.png) +![The demo logo on the Frontpage][logo-front-page] *logo used on the front page* -![logo editor light](../images/customization/logo/editor_light.png)![logo editor dark](../images/customization/logo/editor_dark.png) +![The demo logo in the editor (light)][logo-editor-light] +![The demo logo in the editor (dark)][logo-editor-dark] *logo used in the editor* #### Name For this demo we use the name `DEMO Corp` -![name front page](../images/customization/name/frontpage.png) +![The name on the Frontpage][name-front-page] *name used on the front page* -![name editor light](../images/customization/name/editor_light.png)![name editor dark](../images/customization/name/editor_dark.png) +![The name in the editor (light)][name-editor-light] +![The name in the editor (dark)][name-editor-dark] *name used in the editor* ## Database @@ -156,21 +170,21 @@ We officially support and test these databases: - PostgreSQL - MariaDB -| environment variable | default | example | description | -|-----------------------|---------|---------------------|--------------------------------------------------------------------------------------------| -| `HD_DATABASE_TYPE` | - | `postgres` | The database type you want to use. This can be `postgres`, `mysql`, `mariadb` or `sqlite`. | -| `HD_DATABASE_NAME` | - | `hedgedoc` | The name of the database to use. When using SQLite, this is the path to the database file. | -| `HD_DATABASE_HOST` | - | `db.example.com` | The host, where the database runs. *Only if you're **not** using `sqlite`.* | -| `HD_DATABASE_PORT` | - | `5432` | The port, where the database runs. *Only if you're **not** using `sqlite`.* | -| `HD_DATABASE_USER` | - | `hedgedoc` | The user that logs in the database. *Only if you're **not** using `sqlite`.* | -| `HD_DATABASE_PASS` | - | `password` | The password to log into the database. *Only if you're **not** using `sqlite`.* | +| environment variable | default | example | description | +| -------------------- | ------- | ---------------- | ------------------------------------------------------------------------------------------ | +| `HD_DATABASE_TYPE` | - | `postgres` | The database type you want to use. This can be `postgres`, `mysql`, `mariadb` or `sqlite`. | +| `HD_DATABASE_NAME` | - | `HedgeDoc` | The name of the database to use. When using SQLite, this is the path to the database file. | +| `HD_DATABASE_HOST` | - | `db.example.com` | The host, where the database runs. *Only if you're **not** using `sqlite`.* | +| `HD_DATABASE_PORT` | - | `5432` | The port, where the database runs. *Only if you're **not** using `sqlite`.* | +| `HD_DATABASE_USER` | - | `HedgeDoc` | The user that logs in the database. *Only if you're **not** using `sqlite`.* | +| `HD_DATABASE_PASS` | - | `password` | The password to log into the database. *Only if you're **not** using `sqlite`.* | ## External services -| environment variable | default | example | description | -|------------------------|---------|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| -| `HD_PLANTUML_SERVER` | - | `https://www.plantuml.com/plantuml` | The PlantUML server that HedgeDoc uses to render PlantUML diagrams. If this is not configured, PlantUML diagrams won't be rendered. | -| `HD_IMAGE_PROXY` | - | `https://image-proxy.example.com` | **ToDo:** Add description | +| environment variable | default | example | description | +| -------------------- | ------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `HD_PLANTUML_SERVER` | - | `https://www.plantuml.com/plantuml` | The PlantUML server that HedgeDoc uses to render PlantUML diagrams. If this is not configured, PlantUML diagrams won't be rendered. | +| `HD_IMAGE_PROXY` | - | `https://image-proxy.example.com` | **ToDo:** Add description | ## Media @@ -182,5 +196,13 @@ There are a couple of different backends that can be used to host your images fo - [S3-compatible](media/s3.md) - [WebDAV](media/webdav.md) - [zxcvbn-ts-score]: https://zxcvbn-ts.github.io/zxcvbn/guide/getting-started/#output +[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting +[links-frontpage]: ../images/customization/links.png +[demo-logo]: ../images/customization/demo_logo.png +[logo-front-page]: ../images/customization/logo/frontpage.png +[logo-editor-light]: ../images/customization/logo/editor_light.png +[logo-editor-dark]: ../images/customization/logo/editor_dark.png +[name-front-page]: ../images/customization/name/frontpage.png +[name-editor-light]: ../images/customization/name/editor_light.png +[name-editor-dark]: ../images/customization/name/editor_dark.png diff --git a/docs/content/config/media/azure.md b/docs/content/config/media/azure.md index de946f8e7..e4667cd0c 100644 --- a/docs/content/config/media/azure.md +++ b/docs/content/config/media/azure.md @@ -1,21 +1,30 @@ # Azure Blob Storage -You can use [Microsoft Azure Blob Storage](https://azure.microsoft.com/services/storage/blobs/) to handle your image uploads in HedgeDoc. +You can use [Microsoft Azure Blob Storage][azure] to handle your image uploads in HedgeDoc. -All you need to do is to get the [connection string](https://docs.microsoft.com/azure/storage/common/storage-account-keys-manage) for your storage account and create a storage container with public access set to 'blob'. +All you need to do is to get the [connection string][connection-string] for your storage account +and create a storage container with public access set to 'blob'. -It's possible to create the container with the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli), using your connection string, with the following command: +It's possible to create the container with the [Azure CLI][azure-cli], using your connection string, +with the following command: + +```sh +az storage container create --name --public-access blob--connection-string "" ``` -az storage container create --name --public-access blob --connection-string "" -``` + You can of course also create the container in the Azure portal if you prefer. Then you just add the following lines to your configuration: -(with the appropriate substitution for `` and `` of course) -``` +(with the appropriate substitution for `` and `` of course) + +```dotenv HD_MEDIA_BACKEND="azure" HD_MEDIA_BACKEND_AZURE_CONNECTION_STRING="" HD_MEDIA_BACKEND_AZURE_CONTAINER="" ``` + +[azure]: https://azure.microsoft.com/services/storage/blobs/ +[connection-string]: https://docs.microsoft.com/azure/storage/common/storage-account-keys-manage +[azure-cli]: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli diff --git a/docs/content/config/media/filesystem.md b/docs/content/config/media/filesystem.md index 2a84e2bcf..4eb1dc736 100644 --- a/docs/content/config/media/filesystem.md +++ b/docs/content/config/media/filesystem.md @@ -3,10 +3,11 @@ You can use your local filesystem to handle your image uploads in HedgeDoc. You just add the following lines to your configuration: -(with the appropriate substitution for `` of course) -``` +(with the appropriate substitution for `` of course) + +```dotenv HD_MEDIA_BACKEND="filesystem" HD_MEDIA_BACKEND_FILESYSTEM_UPLOAD_PATH="" ``` -Please make sure that the user that runs HedgeDoc is able to write to the `uploads` directory. +Please make sure that the user that runs HedgeDoc is able to write to the `uploads` directory. diff --git a/docs/content/config/media/imgur.md b/docs/content/config/media/imgur.md index 11f6246df..6a964fe0c 100644 --- a/docs/content/config/media/imgur.md +++ b/docs/content/config/media/imgur.md @@ -1,23 +1,31 @@ # Imgur !!! warning "Imgur saves anonymous images for only 6 month" - Imgur will delete images not associated with any account 6 month after the last access. This means that if you use imgur as your image backend, you may lose images uploaded by you or your users. - See this [FAQ entry](https://help.imgur.com/hc/en-us/articles/14415587638029-Imgur-Terms-of-Service-Update-April-19-2023-) + Imgur will delete images not associated with any account 6 month after the last access. + This means that if you use imgur as your image backend, you may lose images + uploaded by you or your users. See this [FAQ entry][faq-entry] -You can use [Imgur](https://imgur.com) to handle your image uploads in HedgeDoc. +You can use [Imgur][imgur] to handle your image uploads in HedgeDoc. All you need for that is to register an application with Imgur and get a client id: 1. Create an account on imgur.com and log in. 2. Go to -3. Fill out the form and choose "Anonymous usage without user authorization" as the authorization type. +3. Fill out the form and choose "Anonymous usage without user authorization" + as the authorization type. 4. Imgur will then show you your client id. Then you just add the following lines to your configuration: -(with the appropriate substitution for `` of course) -``` +(with the appropriate substitution for `` of course) + +```dotenv HD_MEDIA_BACKEND="imgur" HD_MEDIA_BACKEND_IMGUR_CLIENT_ID="" ``` -All uploads are saved in the `media_uploads` database table and contain the deletion token ([see here](https://apidocs.imgur.com/#949d6cb0-5e55-45f7-8853-8c44a108399c)) in the column `backendData`. +All uploads are saved in the `media_uploads` database table and contain the deletion token +([see here][deletion-token]) in the column `backendData`. + +[faq-entry]: https://help.imgur.com/hc/en-us/articles/14415587638029-Imgur-Terms-of-Service-Update-April-19-2023 +[imgur]: https://imgur.com +[deletion-token]: https://apidocs.imgur.com/#949d6cb0-5e55-45f7-8853-8c44a108399c diff --git a/docs/content/config/media/s3.md b/docs/content/config/media/s3.md index 6c67ccb91..d44132c98 100644 --- a/docs/content/config/media/s3.md +++ b/docs/content/config/media/s3.md @@ -1,12 +1,15 @@ # S3-compatible -You can use [Amazon S3](https://aws.amazon.com/s3/) or any other S3-compatible storage (like [MinIO](https://min.io) or [Ceph Object Gateway](https://docs.ceph.com/en/latest/radosgw/)) to handle your image uploads in HedgeDoc. +You can use [Amazon S3][s3] or any other S3-compatible storage (like [MinIO][minIO] +or [Ceph Object Gateway][ceph]) to handle your image uploads in HedgeDoc. Your S3 bucket must be configured to be writeable. You just add the following lines to your configuration: -(with the appropriate substitution for ``, ``, ``, and `` of course) -``` +(with the appropriate substitution for ``, ``, +``, and `` of course) + +```dotenv HD_MEDIA_BACKEND="s3" HD_MEDIA_BACKEND_S3_ACCESS_KEY="" HD_MEDIA_BACKEND_S3_SECRET_KEY="" @@ -17,5 +20,11 @@ HD_MEDIA_BACKEND_S3_ENDPOINT="" `` should be an URL and contain the protocol, the domain and if necessary the port. For example: `https://s3.example.org` or `http://s3.example.org:9000` -If you use Amazon S3, `` should contain your [Amazon Region](https://docs.aws.amazon.com/general/latest/gr/s3.html). -For example: If your Amazon Region is `us-east-2`, your endpoint `` should be `https://s3.us-east-2.amazonaws.com`. +If you use Amazon S3, `` should contain your [Amazon Region][amazon-region]. +For example: If your Amazon Region is `us-east-2`,your endpoint `` +should be `https://s3.us-east-2.amazonaws.com`. + +[s3]: https://aws.amazon.com/s3/ +[minIO]: https://min.io +[ceph]: https://docs.ceph.com/en/latest/radosgw/ +[amazon-region]: (https://docs.aws.amazon.com/general/latest/gr/s3.html) diff --git a/docs/content/config/media/webdav.md b/docs/content/config/media/webdav.md index 706067ce2..c39921584 100644 --- a/docs/content/config/media/webdav.md +++ b/docs/content/config/media/webdav.md @@ -1,23 +1,30 @@ # WebDAV -You can use any [WebDAV](https://en.wikipedia.org/wiki/WebDAV) server to handle your image uploads in HedgeDoc. +You can use any [WebDAV][webdav] server to handle your image uploads in HedgeDoc. The WebDAV server must host the files in a way that allows HedgeDoc to request and receive them. You just add the following lines to your configuration: -(with the appropriate substitution for ``, ``, and `` of course) -``` +(with the appropriate substitution for ``, +``, and `` of course) + +```dotemv HD_MEDIA_BACKEND="webdav" HD_MEDIA_BACKEND_WEBDAV_CONNECTION_STRING="" HD_MEDIA_BACKEND_WEBDAV_UPLOAD_DIR="" HD_MEDIA_BACKEND_WEBDAV_PUBLIC_URL="" ``` -The `` should include the username and password (if needed) in the familiar way of `schema://user:password@url`. +The `` should include the username and password (if needed) +in the familiar way of `schema://user:password@url`. -With `` you can specify a folder you want to upload to, but you can also omit this (just don't spcify this value at all), if you prefer to upload directly to the root of the WebDAV server. +With `` you can specify a folder you want to upload to, +but you can also omit this (just don't spcify this value at all), +if you prefer to upload directly to the root of the WebDAV server. -Finally, `` specifies with which url HedgeDoc can access the upload. For this purpose the filename will be appended to ``. So the file `test.png` with `` `https://dav.example.com` should be accessible via `https://dav.example.com/test.png`. +Finally, `` specifies with which url HedgeDoc can access the upload. For this purpose +the filename will be appended to ``. So the file `test.png` with `` +`https://dav.example.com` should be accessible via `https://dav.example.com/test.png`. ## Using Nextcloud @@ -25,22 +32,43 @@ If you want to use Nextcloud as a WebDAV server, follow the following instructio This guide was written using Nextcloud 21 in April 2021. -Because the username and app password will be included in the config, we suggest using a dedicated Nextcloud user for the uploads. +Because the username and app password will be included in the config, we suggest using +a dedicated Nextcloud user for the uploads. In this example the username will be `TestUser`. -1. Create an app password by going to `Settings` > `Security`. Nextcloud will generate a password for you. Let's assume it's `passw0rd`. -2. In the Files app [create a new folder](https://docs.nextcloud.com/server/latest/user_manual/en/files/access_webgui.html#creating-or-uploading-files-and-directories) that will hold your uploads (e.g `HedgeDoc`). -3. [Share](https://docs.nextcloud.com/server/latest/user_manual/en/files/sharing.html#public-link-shares) the newly created folder. The folder should (per default) be configured with the option `Read Only` (which we will assume in this guide), but `Allow upload and editing` should be fine, too. -4. Get the public link of the share. It should be in your clipboard after creation. If not you can copy it by clicking the clipboard icon at the end of the line of `Share link`. We'll assume it is `https://cloud.example.com/s/some-id` in the following. -5. Append `/download?path=%2F&files=` to this URL. To continue with our example the url should now be `https://cloud.example.com/s/some-id/download?path=%2F&files=`. -6. Get the [WebDAV url of you Nextcloud server](https://docs.nextcloud.com/server/latest/user_manual/en/files/access_webdav.html). It should be located in the Files app in the bottom left corner under `Settings` > `WebDAV`. We'll assume it is `https://cloud.example.com/remote.php/dav/files/TestUser/` in the following. -7. Add your login information to the link. This is done by adding `username:password@` in between the url schema (typically `https://`) and the rest of the url (`cloud.example.com/remote.php/dav/files/TestUser/` in our example). The WebDAV url in our example should now look like this `https://TestUser:passw0rd@cloud.example.com/remote.php/dav/files/TestUser/`. -8. Configure HedgeDoc: -``` +1. Create an app password by going to `Settings` > `Security`. Nextcloud will generate a password + for you. Let's assume it's `passw0rd`. +2. In the Files app [create a new folder][nextcloud-folder] that will hold + your uploads (e.g `HedgeDoc`). +3. [Share][nextcloud-share] the newly created folder. The folder should (per default) be configured + with the option `Read Only` (which we will assume in this guide), but + `Allow upload and editing` should be fine, too. +4. Get the public link of the share. It should be in your clipboard after creation. If not you + can copy it by clicking the clipboard icon at the end of the line of `Share link`. We'll assume + it is `https://cloud.example.com/s/some-id` in the following. +5. Append `/download?path=%2F&files=` to this URL. To continue with our example + the url should now be `https://cloud.example.com/s/some-id/download?path=%2F&files=`. +6. Get the [WebDAV url of you Nextcloud server][nextcloud-webdav]. It should be located in the + Files app in the bottom left corner under `Settings` > `WebDAV`. We'll assume it is + `https://cloud.example.com/remote.php/dav/files/TestUser/` in the following. +7. Add your login information to the link. This is done by adding `username:password@` in between + the url schema (typically `https://`) and the rest of the url + (`cloud.example.com/remote.php/dav/files/TestUser/` in our example). The WebDAV url in our + example should now look like this + `https://TestUser:passw0rd@cloud.example.com/remote.php/dav/files/TestUser/`. +8. Configure HedgeDoc: + +```dotenv HD_MEDIA_BACKEND="webdav" HD_MEDIA_BACKEND_WEBDAV_CONNECTION_STRING="https://TestUser:passw0rd@cloud.example.com/remote.php/dav/files/TestUser/" HD_MEDIA_BACKEND_WEBDAV_UPLOAD_DIR="HedgeDoc" HD_MEDIA_BACKEND_WEBDAV_PUBLIC_URL="https://cloud.example.com/s/some-id/download?path=%2F&files=" ``` + Start using image uploads backed by Nextclouds WebDAV server. + +[webdav]: https://en.wikipedia.org/wiki/WebDAV +[nextcloud-folder]: https://docs.nextcloud.com/server/latest/user_manual/en/files/access_webgui.html#creating-or-uploading-files-and-directories +[nextcloud-share]: https://docs.nextcloud.com/server/latest/user_manual/en/files/sharing.html#public-link-shares +[nextcloud-webdav]: https://docs.nextcloud.com/server/latest/user_manual/en/files/access_webdav.html diff --git a/docs/content/dev/auth/ldap.md b/docs/content/dev/auth/ldap.md index 8b1d0ee0e..379db3180 100644 --- a/docs/content/dev/auth/ldap.md +++ b/docs/content/dev/auth/ldap.md @@ -1,6 +1,7 @@ # LDAP -LDAP authentication can be tested with the [`test-openldap`](https://github.com/rroemhild/docker-test-openldap) docker image from [rroemhild](https://github.com/rroemhild). +LDAP authentication can be tested with the [`test-openldap`][docker-image] +docker image from [rroemhild][rroemhild]. Simply run @@ -10,7 +11,7 @@ docker run --rm -p 10389:10389 -p 10636:10636 rroemhild/test-openldap and add the following to the `.env` file before starting the backend. -``` +```dotenv HD_AUTH_LDAPS="FUTURAMA" HD_AUTH_LDAP_FUTURAMA_PROVIDER_NAME="Futurama LDAP" HD_AUTH_LDAP_FUTURAMA_URL="ldap://localhost:10389" @@ -32,3 +33,5 @@ You should then be able to log in with either of these logins (`username` : `pas - `bender` : `bender` - `amy` : `amy` +[docker-image]: https://github.com/rroemhild/docker-test-openldap +[rroemhild]: https://github.com/rroemhild diff --git a/docs/content/dev/design_docs/api_auth.md b/docs/content/dev/design_docs/api_auth.md index b040e3ac0..cdef607f3 100644 --- a/docs/content/dev/design_docs/api_auth.md +++ b/docs/content/dev/design_docs/api_auth.md @@ -6,7 +6,7 @@ feature. It is not a user guide and may or may not be fully implemented. ## Public API -All requests to the public API require authentication using a [bearer token](https://datatracker.ietf.org/doc/html/rfc6750). +All requests to the public API require authentication using a [bearer token][bearer-token]. This token can be generated using the profile page in the frontend (which in turn uses the private API to generate the token). @@ -14,27 +14,28 @@ This token can be generated using the profile page in the frontend ### Token generation When a new token is requested via the private API, the backend generates a 64 bytes-long secret of -cryptographically secure data and returns it as a base64url-encoded string, along with an identifier. -That string can then be used by clients as a bearer token. +cryptographically secure data and returns it as a base64url-encoded string, +along with an identifier. That string can then be used by clients as a bearer token. -A SHA-512 hash of the secret is stored in the database. To validate tokens, the backend computes the hash of the provided -secret and checks it against the stored hash for the provided identifier. +A SHA-512 hash of the secret is stored in the database. To validate tokens, the backend computes +the hash of the providedsecret and checks it against the stored hash for the provided identifier. #### Choosing a hash function Unfortunately, there does not seem to be any explicit documentation about our exact use-case. Most docs describe classic password-saving scenarios and recommend bcrypt, scrypt or argon2. -These hashing functions are slow to stop brute-force or dictionary attacks, which would expose the original, -user-provided password, that may have been reused across multiple services. +These hashing functions are slow to stop brute-force or dictionary attacks, which would expose +the original, user-provided password, that may have been reused across multiple services. We have a very different scenario: Our API tokens are 64 bytes of cryptographically strong pseudorandom data. -Brute-force or dictionary attacks are therefore virtually impossible, and tokens are not reused across multiple services. +Brute-force or dictionary attacks are therefore virtually impossible, and tokens are not +reused across multiple services. We therefore need to only guard against one scenario: -An attacker gains read-only access to the database. Saving only hashes in the database prevents the attacker -from authenticating themselves as a user. The hash-function does not need to be very slow, -as the randomness of the original token prevents inverting the hash. The function actually needs to be reasonably fast, -as the hash must be computed on every request to the public API. +An attacker gains read-only access to the database. Saving only hashes in the database prevents the +attacker from authenticating themselves as a user. The hash-function does not need to be very slow, +as the randomness of the original token prevents inverting the hash. The function actually needs to +be reasonably fast, as the hash must be computed on every request to the public API. SHA-512 (or alternatively SHA3) fits this use-case. ## Private API @@ -57,4 +58,7 @@ using one of the supported authentication methods: - Google The `SessionGuard`, which is added to each (appropriate) controller method of the private API, -checks if the provided session is still valid and provides the controller method with the correct user. +checks if the provided session is still valid and provides the controller method +with the correct user. + +[bearer-token]: https://datatracker.ietf.org/doc/html/rfc6750 diff --git a/docs/content/dev/design_docs/config.md b/docs/content/dev/design_docs/config.md index 0fe6949c0..0c699fa70 100644 --- a/docs/content/dev/design_docs/config.md +++ b/docs/content/dev/design_docs/config.md @@ -6,7 +6,8 @@ The configuration of HedgeDoc 2 is handled entirely by environment variables. Most of these variables are prefixed with `HD_` (for HedgeDoc). -NestJS - the framework we use - is reading the variables from the environment and also from the `.env` file in the root of the project. +NestJS - the framework we use - is reading the variables from the environment and also from +the `.env` file in the root of the project. ## How the config code works @@ -47,19 +48,25 @@ Each of those files (except `auth.config.ts` which is discussed later) consists ### Interface -The interface just describes which options the configuration has and how the rest of HedgeDoc can use them. All enums that are used in here are put in their own files with the extension `.enum.ts`. +The interface just describes which options the configuration has and how the rest of HedgeDoc can +use them. All enums that are used in here are put in their own files with the extension `.enum.ts`. ### Joi Schema -We use [Joi][joi] to validate each provided configuration to make sure the configuration of the user is sound and provides helpful error messages otherwise. +We use [Joi][joi] to validate each provided configuration to make sure the configuration of the user +is sound and provides helpful error messages otherwise. -The most important part here is that each value ends with `.label()`. This names the environment variable that corresponds to each config option. It's very important that each config option is assigned the correct label to have meaningful error messages that benefit the user. +The most important part here is that each value ends with `.label()`. This names the +environment variable that corresponds to each config option. It's very important that each config +option is assigned the correct label to have meaningful error messages that benefit the user. -Everything else about how Joi works and how you should write schemas can be read in [their documentation][joi-doc]. +Everything else about how Joi works and how you should write schemas can +be read in [their documentation][joi-doc]. ### A default export -The default exports are used by NestJS to provide the values to the rest of the application. We mostly do four things here: +The default exports are used by NestJS to provide the values to the rest of the application. +We mostly do four things here: 1. Populate the config interface with environment variables, creating the config object. 2. Validate the config object against the Joi schema. @@ -68,15 +75,25 @@ The default exports are used by NestJS to provide the values to the rest of the ## How `auth.config.ts` works -Because it's possible to configure some authentication providers multiple times (e.g. multiple LDAPs or GitLabs), we use user defined environment variable names. With the user defined names it's not possible to put the correct labels in the schema or build the config objects as we do in every other file. +Because it's possible to configure some authentication providers multiple times +(e.g. multiple LDAPs or GitLabs), we use user defined environment variable names. +With the user defined names it's not possible to put the correct labels in the schema +or build the config objects as we do in every other file. Therefore, we have two big extra steps in the default export: -1. To populate the config object we have some code at the top of the default export to gather all configured variables into arrays. -2. The error messages are piped into the util method `replaceAuthErrorsWithEnvironmentVariables`. This replaces the error messages of the form `gitlab[0].providerName` with `HD_AUTH_GITLAB__PROVIDER_NAME`. For this the util function gets the error, the name of the config option (e.g `'gitlab'`), the approriate prefix (e.g. `'HD_AUTH_GITLAB_'`), and an array of the user defined names. + +1. To populate the config object we have some code at the top of the default export to gather all + configured variables into arrays. +2. The error messages are piped into the util method `replaceAuthErrorsWithEnvironmentVariables`. + This replaces the error messages of the form `gitlab[0].providerName` + with `HD_AUTH_GITLAB__PROVIDER_NAME`. For this the util function gets + the error, the name of the config option (e.g `'gitlab'`), the approriate prefix + (e.g. `'HD_AUTH_GITLAB_'`), and an array of the user defined names. ## Mocks -Some config files also have a `.mock.ts` file which defines the configuration for the e2e tests. Those files just contain the default export and return the mock config object. +Some config files also have a `.mock.ts` file which defines the configuration for the e2e tests. +Those files just contain the default export and return the mock config object. [csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP [hsts]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security diff --git a/docs/content/dev/design_docs/events.md b/docs/content/dev/design_docs/events.md index 781aca560..31839dc26 100644 --- a/docs/content/dev/design_docs/events.md +++ b/docs/content/dev/design_docs/events.md @@ -1,17 +1,18 @@ # Events !!! info "Design Document" -This is a design document, explaining the design and vision for a HedgeDoc 2 -feature. It is not a user guide and may or may not be fully implemented. + This is a design document, explaining the design and vision for a HedgeDoc 2 + feature. It is not a user guide and may or may not be fully implemented. In HedgeDoc 2, we use an event system based on [EventEmitter2][eventemitter2]. -It's used to reduce circular dependencies between different services and inform these services about changes. +It's used to reduce circular dependencies between different services and inform these services +about changes. HedgeDoc's system is basically [the system NestJS offers][nestjs/eventemitter]. -The config for the `EventEmitterModule` is stored in `events.ts` and exported as `eventModuleConfig`. -In the same file enums for the event keys are defined. Each of these events is expected to be sent with an additional value. +The config for the `EventEmitterModule` is stored in `events.ts` and +exported as `eventModuleConfig`. In the same file enums for the event keys are defined. +Each of these events is expected to be sent with an additional value. In the enum definition a comment should tell you what exactly this value should be. [eventemitter2]: https://github.com/EventEmitter2/EventEmitter2 [nestjs/eventemitter]: https://docs.nestjs.com/techniques/events - diff --git a/docs/content/dev/design_docs/notes.md b/docs/content/dev/design_docs/notes.md index fc253f871..8485afa49 100644 --- a/docs/content/dev/design_docs/notes.md +++ b/docs/content/dev/design_docs/notes.md @@ -7,7 +7,7 @@ Each note in HedgeDoc 2 contains the following information: - publicId (`b604x5885k9k01bq7tsmawvnp0`) -- a list of aliases (`[hedgedoc-2, hedgedoc-next]`) +- a list of aliases (`[HedgeDoc-2, HedgeDoc-next]`) - groupPermissions - userPermissions - viewCount (`0`) @@ -20,61 +20,88 @@ Each note in HedgeDoc 2 contains the following information: - tags (`[features, cool, update]`) - version -The `publicId` is the default possibility of identifying a note. It will be a randomly generated 128-bit value encoded with [base32-encode](https://www.npmjs.com/package/base32-encode) using the crockford variant and converted to lowercase. This variant of base32 is used, because that results in ids that only use one case of alpha-numeric characters and other url safe characters. We convert the id to lowercase, because we want to minimize case confusion. +The `publicId` is the default possibility of identifying a note. It will be a randomly generated +128-bit value encoded with [base32-encode][base32-encode] using the crockford variant and converted +to lowercase. This variant of base32 is used, because that results in ids that only use one case of +alpha-numeric characters and other url safe characters. We convert the id to lowercase, because we +want to minimize case confusion. -`aliases` are the other way of identifying a note. There can be any number of them, and the owner of the note is able to add or remove them. All aliases are just strings (especially to accommodate the old identifier from HedgeDoc 1 [see below](#conversion-of-hedgedoc-1-notes)), but new aliases added with HedgeDoc 2 will only allow characters matching this regex: `[a-z0-9\-_]`. This is done to once again prevent case confusion. One of the aliases can be set as the primary alias, which will be used as the identifier for the history entry. +`aliases` are the other way of identifying a note. There can be any number of them, and the owner +of the note is able to add or remove them. All aliases are just strings (especially to accommodate +the old identifier from HedgeDoc 1 [see below](#conversion-of-hedgedoc-1-notes)), but new aliases +added with HedgeDoc 2 will only allow characters matching this regex: `[a-z0-9\-_]`. This is done to +once again prevent case confusion. One of the aliases can be set as the primary alias, which will be +used as the identifier for the history entry. `groupPermissions` and `userPermissions` each hold a list of the appropriate permissions. -Each permission holds a reference to a note and a user/group and specify what the user/group is allowed to do. -Each permission is additive, that means a user that has only the right to read a note via a group, but the right to write via a different group or directly for his user, is able to write in the note. +Each permission holds a reference to a note and a user/group and specify what the user/group +is allowed to do. +Each permission is additive, that means a user that has only the right to read a note via a group, +but the right to write via a different group or directly for his user, is able to write in the note. -The `viewCount` is a simple counter that holds how often the read-only view of the note in question was requested. +The `viewCount` is a simple counter that holds how often the read-only view of the note in question +was requested. -`owner` is the user that created the note or later got ownership of the note. The current owner is able to change the owner of the note to someone else. The owner of a note is the only person that can perform the following actions: +`owner` is the user that created the note or later got ownership of the note. The current owner is +able to change the owner of the note to someone else. The owner of a note is the only person that +can perform the following actions: - delete the note - modify `aliases` - remove all `revisions` -The `revisions` hold all revisions of the note. These are the changes to the note content and by whom they were performed. +The `revisions` hold all revisions of the note. These are the changes to the note content and by +whom they were performed. -The `authorColors` each specify for the tuple user and note which color should be used to highlight them. +The `authorColors` each specify for the tuple user and note which color should be used +to highlight them. -The `historyEntries` hold the history entries this note is referenced in. They are mainly here for the purpose of deleting the history entries on note deletion. +The `historyEntries` hold the history entries this note is referenced in. They are mainly here +for the purpose of deleting the history entries on note deletion. -`description`, `tags` and `title` are each information specified in the [frontmatter][frontmatter] of the note. They are extracted and saved in the database to allow the history page to show them and do a search for tags without having to do a full-text search or having to parse the tags of each note on search. +`description`, `tags` and `title` are each information specified in the [frontmatter][frontmatter] +of the note. They are extracted and saved in the database to allow the history page to show them and +do a search for tags without having to do a full-text search or having to parse the tags of +each note on search. While `description` and `tags` are only specified by the [frontmatter][frontmatter], the title is - the content of the *title* field of the [frontmatter][frontmatter] of the note -- **OR** the content of the *title* field in the *opengraph* field of the [frontmatter][frontmatter] of the note -- **OR** the first level 1 heading of the note - +- **OR** the content of the *title* field in the *opengraph* field of the [frontmatter][frontmatter] + of the note +- **OR** the first level 1 heading of the note + which ever of these is the first to not be unspecified. All mentioned fields are extracted from the note content by the backend on save or update. - -`version` specifies if a note is an old HedgeDoc 1 note, or a new HedgeDoc 2 note. This is mainly used to redirect old notes form to . + +`version` specifies if a note is an old HedgeDoc 1 note, or a new HedgeDoc 2 note. +This is mainly used to redirect old notes form +to . ## Deleting Notes - The owner of a note may delete it. - - By default, this also removes all revisions and all files that were uploaded to that note. - - The owner may choose to skip deleting associated uploads, leaving them without a note. - - The frontend should show a list of all uploads that will be affected - and provide a method of skipping deletion. + - By default, this also removes all revisions and all files that were uploaded to that note. + - The owner may choose to skip deleting associated uploads, leaving them without a note. + - The frontend should show a list of all uploads that will be affected + and provide a method of skipping deletion. - The owner of a note may delete all revisions. This effectively purges the edit history of a note. - ## Conversion of HedgeDoc 1 notes First we want to define some terms of the HedgeDoc 1 notes: -- **noteId**: This refers to the auto-generated id for new notes. (https://demo.hedgedoc.org/Q_Iz5T_lQWGYxne0sbMtwg) +- **noteId**: This refers to the auto-generated id for new notes. + () -- **shortId**: This refers to the auto-generated short id which is used for "published" notes and slide presentation mode. (https://demo.hedgedoc.org/s/61ZHI6HGE) +- **shortId**: This refers to the auto-generated short id which is used for "published" notes and + slide presentation mode. () -- **alias**: This refers to user-defined URLs for notes on instances with Free-URL mode enabled. (https://md.kif.rocks/lowercase) +- **alias**: This refers to user-defined URLs for notes on instances with Free-URL mode enabled. + () -The noteId, shortId and alias of each HedgeDoc 1 note are saved as HedgeDoc 2 aliases. Each note gets a newly generated publicId. +The noteId, shortId and alias of each HedgeDoc 1 note are saved as HedgeDoc 2 aliases. +Each note gets a newly generated publicId. [frontmatter]: https://jekyllrb.com/docs/front-matter/ +[base32-encode]: https://www.npmjs.com/package/base32-encode diff --git a/docs/content/dev/design_docs/user_profiles.md b/docs/content/dev/design_docs/user_profiles.md index 6385359c6..5a6d6f089 100644 --- a/docs/content/dev/design_docs/user_profiles.md +++ b/docs/content/dev/design_docs/user_profiles.md @@ -12,7 +12,7 @@ which contains the following information: - email address, optional (`janedoe@example.com`) - profile picture, optional - the date the user was created -- the date the profile was last updated +- the date the profile was last updated HedgeDoc 2 supports multiple authentication methods per user. These are called *identities* and each identity is backed by an @@ -23,7 +23,7 @@ This identity is used to automatically update profile attributes like the display name or profile picture on every login. If a sync source exists, the user can not manually edit their profile information. If an external provider was used to create the account, -it is automatically used as sync source. +it is automatically used as sync source. The administrator may globally set one or more auth providers as sync source, e.g. to enforce that all profile information comes from the corporate @@ -36,7 +36,7 @@ This effectively pins the account to this provider. ## Example: Corporate LDAP The administrator wants to allow users to log in via the corporate LDAP -and Google. Login must only be possible for users present in LDAP and +and Google. Login must only be possible for users present in LDAP and all users must be displayed as they are in the LDAP. The admin therefore sets up two login providers: @@ -57,16 +57,18 @@ Google account and use it to login afterwards. HedgeDoc is configured with two auth providers. - A user logs in using auth provider A. -- The backend receives the profile information from provider A and notices that the username in the profile - already exists in the database, but no identity for this provider-username combination exists. +- The backend receives the profile information from provider A and notices that the username + in the profile already exists in the database, but no identity for this provider-username + combination exists. - The backend creates a new user with another username to solve the username conflict. -- The frontend warns the user that the username provided by the auth provider is already taken and that another - username has been generated. It also offers to instead link the new auth provider (in this case A) with the - existing auth provider (in this case B). -- If the user chooses the latter option, the frontend sends a request to delete the newly created user to the backend. -- The user can then log in with auth provider B and link provider A using the "link auth provider" feature in - the profile page. - +- The frontend warns the user that the username provided by the auth provider is already taken + and that another username has been generated. It also offers to instead link the new auth provider + (in this case A) with the existing auth provider (in this case B). +- If the user chooses the latter option, the frontend sends a request to delete the newly created + user to the backend. +- The user can then log in with auth provider B and link provider A using the "link auth provider" + feature in the profile page. + ### Handling of sync sources and username conflicts #### Global sync sources @@ -77,19 +79,21 @@ the backend cannot automatically create a user with another username. This is because: - Creating new accounts is only possible with a sync source auth provider. -- Setting an auth provider as sync-source entails that profile information the auth provider provides must be - saved into the local HedgeDoc database. -- As the username the auth provider provides already exists in the database, a new user cannot be created with - that username. - -In this case, the frontend should show the use a notice that they should contact an admin to resolve the issue. +- Setting an auth provider as sync-source entails that profile information the auth provider + provides must be saved into the local HedgeDoc database. +- As the username the auth provider provides already exists in the database, a new user cannot + be created with that username. + +In this case, the frontend should show the use a notice that they should contact an admin +to resolve the issue. !!! warning - Admins must ensure that usernames are unique across all auth providers set as a global sync source. - Otherwise, if e.g. in both LDAPs configured as sync source a user `johndoe` exists, - only the first that logs in can use HedgeDoc. +Admins must ensure that usernames are unique across all auth providers set as a global sync source. + Otherwise, if e.g. in both LDAPs configured as sync source a user `johndoe` exists, +only the first that logs in can use HedgeDoc. #### Local sync sources -If auth provider A is configured as a sync source by the user, syncing is automatically disabled, and a notice is shown. -Re-enabling the sync source is not possible until the username conflict is resolved, e.g. by changing the username -in the auth provider. + +If auth provider A is configured as a sync source by the user, syncing is automatically disabled, +and a notice is shown. Re-enabling the sync source is not possible until the username conflict is +resolved, e.g. by changing the username in the auth provider. diff --git a/docs/content/dev/dev_notes.md b/docs/content/dev/dev_notes.md index 6a48f9a97..7cbd55ef0 100644 --- a/docs/content/dev/dev_notes.md +++ b/docs/content/dev/dev_notes.md @@ -16,17 +16,17 @@ We intend to officially support and test these databases: The software provides two special groups which have no explicit users: -- `everyone` (Describing that everyone who wants to access a note can do if it is enabled in the config.) +- `everyone` (Describing that everyone who wants to access a note can do if it is + enabled in the config.) - `loggedIn` (Describing all users which are logged in) ## Entity `create` methods -Because we need to have empty constructors in our entity classes for TypeORM to work, the actual constructor is a separate `create` method. These methods should adhere to these guidelines: +Because we need to have empty constructors in our entity classes for TypeORM to work, the actual +constructor is a separate `create` method. These methods should adhere to these guidelines: - Only require the non-optional properties of the corresponding entity - Have no optional parameters - Have no lists which can be empty (so probably most of them) - Should either return a complete and fully useable instance or return a Pick/Omit type. - Exceptions to these rules are allowed, if they are mentioned in the method documentation - - diff --git a/docs/content/dev/docker.md b/docs/content/dev/docker.md index 227a397c6..acbcdb651 100644 --- a/docs/content/dev/docker.md +++ b/docs/content/dev/docker.md @@ -1,19 +1,18 @@ # Building Docker images To build docker images of the backend or frontend use the following commands. -Make sure that you have installed the [Docker BuildKit Plugin](https://docs.docker.com/build/install-buildx/) and +Make sure that you have installed the [Docker BuildKit Plugin][buildkit] and execute the commands from the root level of the project. Otherwise, the build process may fail. ```sh -docker buildx build -f backend/docker/Dockerfile -t hedgedoc-backend . +docker buildx build -f backend/docker/Dockerfile -t HedgeDoc-backend . ``` or ```sh -docker buildx build -f frontend/docker/Dockerfile -t hedgedoc-frontend . +docker buildx build -f frontend/docker/Dockerfile -t HedgeDoc-frontend . ``` - - +[buildkit]: https://docs.docker.com/build/install-buildx/ diff --git a/docs/content/dev/documentation.md b/docs/content/dev/documentation.md index 106f26b07..91f6e3ebb 100644 --- a/docs/content/dev/documentation.md +++ b/docs/content/dev/documentation.md @@ -5,26 +5,30 @@ Our documentation is build with [mkdocs][mkdocs]. ## Writing All documentation files are found in the `docs/content` directory of -the [hedgedoc/hedgedoc repo](https://github.com/hedgedoc/hedgedoc). These files are just normal markdown files with -nothing special about them. +the [HedgeDoc/HedgeDoc repo](https://github.com/hedgedoc/hedgedoc). These files are just normal +markdown files with nothing special about them. -The configuration for mkdocs lies in the `docs` folder in a file called `mkdocs.yml`. With that file the theme and menu - among others - can be configured. - **Please note:** Any new files need to be linked to by other files or put in the navigation, otherwise the files will be very hard to find on the documentation website. +The configuration for mkdocs lies in the `docs` folder in a file called `mkdocs.yml`. With that file +the theme and menu - among others - can be configured. +**Please note:** Any new files need to be linked to by other files or put in the navigation, +otherwise the files will be very hard to find on the documentation website. ## Building To build the documentation locally you need to perform the following steps: -0. Make sure you have python3 installed. -1. Go into the `docs` folder. -2. Install all the dependencies (E.g. with a [venv](https://docs.python.org/3/library/venv.html)) +1. Make sure you have python3 installed. +2. Go into the `docs` folder. +3. Install all the dependencies (E.g. with a [venv](https://docs.python.org/3/library/venv.html)) with `pip install -r requirements.txt` -3. Start the mkdocs dev server (`mkdocs serve`) or build the documentation (`mkdocs build`). +4. Start the mkdocs dev server (`mkdocs serve`) or build the documentation (`mkdocs build`). ## Deployment The documentation is deployed with [mkdocs][mkdocs]. -The repository [docs.hedgedoc.org](https://github.com/hedgedoc/docs.hedgedoc.org) is used to deploy the actual website to github.io. Currently only the `master` branch is deployed as it contains the latest release. +The repository [docs.HedgeDoc.org][docs.HedgeDoc.org] is used to deploy the actual website +to github.io. Currently only the `master` branch is deployed as it contains the latest release. [mkdocs]: https://www.mkdocs.org +[docs.HedgeDoc.org]: https://github.com/hedgedoc/docs.hedgedoc.org diff --git a/docs/content/dev/getting-started.md b/docs/content/dev/getting-started.md index 86cc903f1..83586cc97 100644 --- a/docs/content/dev/getting-started.md +++ b/docs/content/dev/getting-started.md @@ -2,35 +2,44 @@ To run HedgeDoc 2.0 you need three components: the backend, the frontend and the reverse proxy. -Backend and Frontend are included in the [HedgeDoc repo](https://github.com/hedgedoc/hedgedoc). The reverse proxy can be chosen by preference. For development, we -recommend caddy and the provided configuration. +Backend and Frontend are included in the [HedgeDoc repo][hedgedoc-repo]. +The reverse proxy can be chosen by preference. For development, we recommend caddy +and the provided configuration. ## Quick guide for development setup -This describes the easiest way to start a local development environment. For other deployments follow the description -below. +This describes the easiest way to start a local development environment. For other deployments +follow the description below. To run HedgeDoc 2.0 you need three components: the backend, the frontend and the reverse proxy. -Backend and Frontend are included in the [HegdeDoc repo](https://github.com/hedgedoc/hedgedoc). The reverse proxy can be chosen by preference. For development, we -recommend caddy and the provided configuration. +Backend and Frontend are included in the [HegdeDoc repo](https://github.com/hedgedoc/hedgedoc). +The reverse proxy can be chosen by preference. For development, we recommend caddy +and the provided configuration. + +1. Clone [our repository][hedgedoc-repo] and go into its directory -1. Clone [our repository](https://github.com/hedgedoc/hedgedoc.git) and go into its directory ```shell git clone https://github.com/hedgedoc/hedgedoc.git - cd hedgedoc + cd HedgeDoc ``` + 2. Install Node.js. You need at least Node 16, but we recommend Node 20. -3. Install [Yarn](https://yarnpkg.com/getting-started/install) +3. Install [Yarn][yarn] 4. Install Caddy (select one of the two options) - - [Download](https://caddyserver.com/) and place the `caddy` binary in `dev-reverse-proxy`. Ensure it is executable with `chmod +x caddy`. Users of macOS may need to run `xattr -d com.apple.quarantine ./caddy` to lift the quarantine for executables from the internet. + - [Download][caddy] and place the `caddy` binary in `dev-reverse-proxy`. + Ensure it is executable with `chmod +x caddy`. Users of macOS may need to run + `xattr -d com.apple.quarantine ./caddy` to lift the quarantine for executables + from the internet. - Install Caddy using your package manager 5. Install the dependencies in repo root directory with `yarn install` 6. Create the `.env` config file by copying the example: `cp .env.example .env` 7. Run `yarn start:dev` - > This will execute the backend, frontend and reverse proxy at once -8. Use your browser to go to . This may take a while because everything is compiled on the fly. + > This will execute the backend, frontend and reverse proxy at once +8. Use your browser to go to . This may take a while because everything is + compiled on the fly. ## More detailed development setup + The following sections describe a more detailed setup of all components. ## Preconditions @@ -38,35 +47,38 @@ The following sections describe a more detailed setup of all components. If you want to run HedgeDoc in dev mode some preconditions have to be met. 1. Make sure that Node.js is installed. You need at least Node 16, but we recommend Node 18. -2. Make sure that [Yarn](https://yarnpkg.com/) is installed. -3. Clone this repo (e.g. `git clone https://github.com/hedgedoc/hedgedoc.git hedgedoc`) +2. Make sure that [Yarn][yarn] is installed. +3. Clone this repo (e.g. `git clone https://github.com/hedgedoc/hedgedoc.git HedgeDoc`) 4. Go into the cloned directory ## Installing the dependencies -Because we use Yarn workspaces, Yarn collects the dependencies of all packages automatically in one central top-level -`node_modules` folder. +Because we use Yarn workspaces, Yarn collects the dependencies of all packages automatically in one +central top-level `node_modules` folder. To install the dependencies execute `yarn install` at the top level of the cloned repository. Execute this command ONLY there. There is no need to execute the install-command for every package. -It's important to use [Yarn](https://yarnpkg.com/). We don't support `npm` or any other package manager and using anything -else than Yarn won't work. +It's important to use [Yarn][yarn]. We don't support `npm` or any other package +manager and using anything else than Yarn won't work. ## Create the configuration + HedgeDoc 2 is configured using environment variables. For development, we recommend creating an `.env` file. 1. Create an `.env` file. We recommend to use the example file by running `cp .env.example .env` - You can modify this file according to the [configuration documentation](../config/index.md). -2. Make sure that you've set `HD_SESSION_SECRET` in your `.env` file. Otherwise, the backend won't start. - > In dev mode you don't need a secure secret. So use any value. If you want to generate a secure session secret you - can use e.g. `openssl rand -hex 16 | sed -E 's/(.*)/HD_SESSION_SECRET=\1/' >> .env`. -3. Make sure that `HD_BASE_URL` in `.env` is set to the base url where HedgeDoc should be available. In local dev - environment this is most likely `http://localhost:8080`. + You can modify this file according to the [configuration documentation][config-docs]. +2. Make sure that you've set `HD_SESSION_SECRET` in your `.env` file. Otherwise, the backend + won't start. + > In dev mode you don't need a secure secret. So use any value. If you want to generate a secure + > session secret you can use + > e.g. `openssl rand -hex 16 | sed -E 's/(.*)/HD_SESSION_SECRET=\1/' >> .env`. +3. Make sure that `HD_BASE_URL` in `.env` is set to the base url where HedgeDoc should be available. + In local dev environment this is most likely `http://localhost:8080`. ## Build the `commons` package -Some code is shared by backend and frontend. This code lives in the `commons package and needs to be built so -frontend and backend can import it. +Some code is shared by backend and frontend. This code lives in the `commons package and needs +to be built so frontend and backend can import it. This only needs to be done once, except if you've changed code in the commons package. 1. Go into the `commons` directory. @@ -74,25 +86,28 @@ This only needs to be done once, except if you've changed code in the commons pa ## Setting up the Backend -**Note:** The backend can be mocked instead of starting it for real. This is useful, if you just want to work on the frontend. See the "Mocked backend" section below. +**Note:** The backend can be mocked instead of starting it for real. This is useful, +if you just want to work on the frontend. See the "Mocked backend" section below. 1. Go into the `backend` directory. 2. Start the backend by running `yarn start:dev` for dev mode or `yarn start` for production. ## Setting up the frontend -The frontend can be run in four different ways. The development mode compiles everything on demand. So the first time -you open a page in the browser it may take some time. -See [here](setup/frontend.md) for a more detailed description of the environment variables for the frontend. -A special configuration isn't necessary but keep in mind that you execute all commands from within the `frontend` directory. +The frontend can be run in four different ways. The development mode compiles everything on demand. +So the first time you open a page in the browser it may take some time. +[See here][frontend-setup] for a more detailed description of the environment variables +for the frontend. A special configuration isn't necessary but keep in mind that you execute +all commands from within the `frontend` directory. ### Mocked backend -This task will run the frontend in mock-mode, meaning instead of running a real backend, the frontend mocks the backend. -This way you can work on frontend functionality without starting up the full development environment. -The downside of this method is that you can't save notes and that realtime collaboration features are not available. -To start the development mode, run `yarn start:dev:mock`. -The app should run now and be available under [http://localhost:3001](http://localhost:3001) in your browser. +This task will run the frontend in mock-mode, meaning instead of running a real backend, the +frontend mocks the backend. This way you can work on frontend functionality without starting up the +full development environment. The downside of this method is that you can't save notes and that +realtime collaboration features are not available. To start the development mode, +run `yarn start:dev:mock`. The app should run now and be available under + in your browser. ### With local backend @@ -101,31 +116,43 @@ This task will automatically set `HD_BASE_URL` to `http://localhost:8080`. ### Production mode -Use `yarn build` to build the app in production mode and save it into the `.next` folder. The production build is -minimized and optimized for best performance. Don't edit the generated files in the `.next` folder in any way! +Use `yarn build` to build the app in production mode and save it into the `.next` folder. +The production build is minimized and optimized for best performance. Don't edit the generated +files in the `.next` folder in any way! You can run the production build using the built-in server with `yarn start`. -You MUST provide the environment variable `HD_BASE_URL` with protocol, domain and (if needed) subdirectory path ( -e.g. `http://localhost:3001/`) so the app knows under which URL the frontend is available in the browser. +You MUST provide the environment variable `HD_BASE_URL` with protocol, domain and (if needed) +subdirectory path (e.g. `http://localhost:3001/`) so the app knows under which URL the frontend +is available in the browser. -If you use the production build then make sure that you set the environment variable `HD_BASE_URL` to the same -value as `HD_BASE_URL` in the backend. +If you use the production build then make sure that you set the environment variable `HD_BASE_URL` +to the same value as `HD_BASE_URL` in the backend. ### Production mock build -It is also possible to create a production build that uses the emulated backend by using `yarn build:mock`. This is -usually not needed except for demonstration purposes like `https://hedgedoc.dev`. +It is also possible to create a production build that uses the emulated backend by using +`yarn build:mock`. This is usually not needed except for demonstration purposes like +`https://hedgedoc.dev`. ## Running backend and frontend together -To use backend and frontend together in development mode you'll need a local reverse proxy that combines both services -under one URL origin. -We recommend to use our pre-configured [Caddy](https://caddyserver.com/) configuration. +To use backend and frontend together in development mode you'll need a local reverse proxy that +combines both services under one URL origin. +We recommend to use our pre-configured [Caddy][caddy] configuration. ### Running the reverse proxy -1. Download the latest version of Caddy from [the Caddy website](https://caddyserver.com/) or alternatively install it - using your package manager. You don't need any plugin. Place the downloaded binary in the - directory `dev-reverse-proxy`. Don't forget to mark the file as executable using `chmod +x caddy`. Users of macOS may need to run `xattr -d com.apple.quarantine ./caddy` to lift the quarantine for executables from the internet. -2. Start Caddy using `./caddy run` (if you downloaded the binary manually) or `caddy run` (if you installed Caddy via a package manager). -3. Open your browser on http://localhost:8080 +1. Download the latest version of Caddy from [the Caddy website][caddy] or alternatively install + it using your package manager. You don't need any plugin. Place the downloaded binary in + the directory `dev-reverse-proxy`. Don't forget to mark the file as executable using + `chmod +x caddy`. Users of macOS may need to run `xattr -d com.apple.quarantine ./caddy` + to lift the quarantine for executables from the internet. +2. Start Caddy using `./caddy run` (if you downloaded the binary manually) or `caddy run` + (if you installed Caddy via a package manager). +3. Open your browser on + +[hedgedoc-repo]: https://github.com/hedgedoc/hedgedoc +[yarn]: https://yarnpkg.com/getting-started/install +[caddy]: https://caddyserver.com/ +[config-docs]: ../config/index.md +[frontend-setup]: ./setup/frontend.md diff --git a/docs/content/dev/setup/frontend.md b/docs/content/dev/setup/frontend.md index ea80e1200..a075c6d34 100644 --- a/docs/content/dev/setup/frontend.md +++ b/docs/content/dev/setup/frontend.md @@ -1,31 +1,26 @@ - - +# Frontend ## Environment Variables The following environment variables are recognized by the frontend process. | Name | Possible Values | Description | -|--------------------------|----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HD_BASE_URL | Any URL with protocol, domain and optionally directory and port. Must end with a trailing slash. (e.g. `http://localhost:3001/`) | The URL under which the frontend is expected. Setting this is mandatory so the server side rendering can generate assets URLs. You only need to set this yourself if you use the production mode. | -| HD_RENDERER_BASE_URL | Same as `HD_BASE_URL` | You can provide this variable if the renderer should use another domain than the editor. This is recommended for security reasons but not mandatory. This variable is optional and will fallback to `HD_BASE_URL` | +| HD_RENDERER_BASE_URL | Same as `HD_BASE_URL` | You can provide this variable if the renderer should use another domain than the editor. This is recommended for security reasons but not mandatory. This variable is optional and will fallback to `HD_BASE_URL` | | NEXT_PUBLIC_USE_MOCK_API | `true`, `false` | Will activate the mocked backend | | NEXT_PUBLIC_TEST_MODE | `true`, `false` | Will activate additional HTML attributes that are used to identify elements for test suits. | -Variables that start with `NEXT_PUBLIC_` will be compiled into the build. You can't change them at after compilation. -You shouldn't need to set them yourself. Use the designated npm tasks instead. +Variables that start with `NEXT_PUBLIC_` will be compiled into the build. You can't change them at +after compilation. You shouldn't need to set them yourself. Use the designated npm tasks instead. ## UI Test -Curious about the new look and feel? We provide a demo of the new UI on [hedgedoc.dev](https://hedgedoc.dev). This -version uses mocked data and has no data persistence. +Curious about the new look and feel? We provide a demo of the new UI on +[HedgeDoc.dev][hedgedoc-dev]. This version uses mocked data and has no data persistence. -The UI test is hosted by [netlify](https://netlify.com). Please check -their [privacy policy](https://netlify.com/privacy) as well as [ours](https://hedgedoc.org/privacy-policy). +The UI test is hosted by [netlify][netlify]. Please check their [privacy policy][netlify-privacy] +as well as [ours][privacy]. ## Running Tests @@ -37,10 +32,10 @@ Unit testing is done via jest. ### End2End -We use [cypress](https://cypress.io) for e2e tests. +We use [cypress][cypress] for e2e tests. -1. Start the frontend with `yarn start:dev:test` (or use a test build using `yarn build:test` which you can start - using `yarn start`). The usage of `:test` is mandatory! +1. Start the frontend with `yarn start:dev:test` (or use a test build using `yarn build:test` + which you can start using `yarn start`). The usage of `:test` is mandatory! 2. Run `yarn cy:open` to open the cypress test loader 3. Choose your browser and start a test suite @@ -55,9 +50,16 @@ You can inspect the generated production-bundle files to look for optimization i ## Enable Debug Logging in Production -The debug logger can be enabled in production by setting `debugLogging` in the browser's local storage to `true`. -This can be done e.g. by executing this JavaScript command in the browser's console. +The debug logger can be enabled in production by setting `debugLogging` in the browser's +local storage to `true`. This can be done e.g. by executing this JavaScript command +in the browser's console. ```javascript -window.localStorage.setItem("debugLogging", 'true'); +window.localStorage.setItem("debugLogging", "true"); ``` + +[hedgedoc-dev]: https://hedgedoc.dev +[netlify]: https://netlify.com +[netlify-privacy]: https://netlify.com/privacy +[privacy]: https://hedgedoc.org/privacy-policy +[cypress]: https://cypress.io diff --git a/docs/content/index.md b/docs/content/index.md index 72ac38b6c..875b6ed03 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -1,11 +1,13 @@ # Welcome to the HedgeDoc 2 Documentation + HedgeDoc Logo HedgeDoc Logo + ๐Ÿšงโš ๏ธ๐Ÿšง **HedgeDoc 2.0 is still in development!** You are probably looking for the 1.x docs. -Find them in the `master` branch and on [docs.hedgedoc.org](https://docs.hedgedoc.org). +Find them in the `master` branch and on [docs.HedgeDoc.org](https://docs.hedgedoc.org). If you want to help us to develop HedgeDoc 2, join us on [Matrix][matrix.org-url]! diff --git a/docs/content/interface/toolbar.md b/docs/content/interface/toolbar.md index 9ae2c07fd..24e692252 100644 --- a/docs/content/interface/toolbar.md +++ b/docs/content/interface/toolbar.md @@ -14,8 +14,9 @@ The Toolbar is found above the editor and is split into five sections: ![Emphasis toolbar](../images/interface/toolbar/emphasis.png) -These buttons are able to either surround selected text with the necessary symbols to emphasize it or insert the symbols -without any content between them to be filled out by you. The icons on the buttons should be rather easy to identify. +These buttons are able to either surround selected text with the necessary symbols to emphasize it +or insert the symbols without any content between them to be filled out by you. The icons on +the buttons should be rather easy to identify. Nonetheless, here is their functionality: 1. bold e.g `**text**` @@ -32,25 +33,26 @@ Nonetheless, here is their functionality: These buttons all work a bit different so, we will describe each on separately: 1. **Heading** - Adds `# ` in front of the line. If the line is already starting with a `#` adds just `#`. + Adds `#` in front of the line. If the line is already starting with a `#` adds just `#`. 2. **Code Blocks** - Adds ` ``` ` around the selected text or if no text is selected just adds two lines with ` ``` ` and an empty line - between them. + Adds ` ``` ` around the selected text or if no text is selected just adds two lines with ` ``` ` + and an empty line between them. 3. **Quote** - Adds `> ` in front of the line. + Adds `>` in front of the line. 4. **Unordered List** - Ads `- ` in front of the line. + Ads `-` in front of the line. 5. **Ordered List** - Adds `1. ` in front of the line. + Adds `1.` in front of the line. 6. **ToDo List** - Adds `- [ ] ` in front of the line. + Adds `- [ ]` in front of the line. ## Links & Images ![Links & Images toolbar](../images/interface/toolbar/links.png) These buttons add the corresponding syntax at the current cursor position. -If some text is selected it will either put that as the link, if it thinks that the selected text is a link, or as the alt text. +If some text is selected it will either put that as the link, if it thinks that the selected text +is a link, or as the alt text. 1. **Link** Adds the link template `[](https://)` (For more information @@ -66,8 +68,9 @@ If some text is selected it will either put that as the link, if it thinks that ![larger blocks & emojis toolbar](../images/interface/toolbar/large_blocks.png) 1. **Table** - This button opens an overlay, which lets you choose the size of your table up to 10 columns and 8 rows. By clicking - on any of the squares a table with the corresponding size will be added to the note at the position of your cursor. + This button opens an overlay, which lets you choose the size of your table up to 10 columns + and 8 rows. By clicking on any of the squares a table with the corresponding size will be added + to the note at the position of your cursor. ![Table overlay](../images/interface/toolbar/table_overlay.png) A larger table can be created by clicking the 'Custom Size' button. ![Table modal](../images/interface/toolbar/table_modal.png) @@ -77,15 +80,16 @@ If some text is selected it will either put that as the link, if it thinks that 3. **Collapsable Block** This button adds a template for a Collapsable Block like this: - ``` - :::spoiler Toggle label - Toggled content - ::: - ``` + ```markdown + :::spoiler Toggle label + Toggled content + ::: + ``` 4. **Comment** - This button adds `> []` at the beginning of the line. You can either specify a name for your comment by - inserting `name=$YourName`, a time by inserting `time=$time` or a color by inserting `color=#FFFFFF` in the `[]`. + This button adds `> []` at the beginning of the line. You can either specify a name + for your comment by inserting `name=$YourName`, a time by inserting `time=$time` + or a color by inserting `color=#FFFFFF` in the `[]`. Please note that you can only specify one of those per `[]`, but you can use multiple `[]`. 5. **Emoji Picker** This button opens the emoji picker, where you can choose an emoji to insert into your note. diff --git a/docs/content/references/hfm.md b/docs/content/references/hfm.md index 12f321375..46d4dc472 100644 --- a/docs/content/references/hfm.md +++ b/docs/content/references/hfm.md @@ -7,37 +7,37 @@ These tables tell you what exactly we support in HedgeDoc 1.x (HFM 1) and HedgeD ## Typography -| Feature | HFM 1 | HFM 2 | CommonMark | GFM | -| ------------- | :---: | :---: | :---------------: | :---------------: | -| bold | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| italic | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| underline | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | (โ˜‘๏ธ with ``) | -| strikethrough | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | โ˜‘๏ธ | -| subscript | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | (โ˜‘๏ธ with ``) | -| superscript | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | (โ˜‘๏ธ with ``) | -| marked | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | (โ˜‘๏ธ with ``) | +| Feature | HFM 1 | HFM 2 | CommonMark | GFM | +| ------------- | :---: | :---: | :----------------: | :----------------: | +| bold | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| italic | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| underline | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | (โ˜‘๏ธ with ``) | +| strikethrough | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | โ˜‘๏ธ | +| subscript | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | (โ˜‘๏ธ with ``) | +| superscript | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | (โ˜‘๏ธ with ``) | +| marked | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | (โ˜‘๏ธ with ``) | ## Extended typography features -| Feature | HFM 1 | HFM 2 | CommonMark | GFM | -| ------------------------------------------- | :----------------------: | :----------------------: | :--------: | :---: | -| heading | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| inline code | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| indented code blocks | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| code block with language[^highlight] | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| code block with extra features[^extra-code] | โ˜‘๏ธ | โ˜‘๏ธ | | | -| block quote | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| name tag (`[name=...]`) | (โ˜‘๏ธ)[^in-bq-list] | โ˜‘๏ธ | | | -| time tag (`[time=...]`) | (โ˜‘๏ธ)[^in-bq-list] | โ˜‘๏ธ | | | -| color tag (`[color=...]`) | (โ˜‘๏ธ)[^in-bq-list] | โ˜‘๏ธ | | | -| unorderd list | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| ordered list | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| task list | โ˜‘๏ธ | โ˜‘๏ธ | | โ˜‘๏ธ | -| defition list | โ˜‘๏ธ | โ˜‘๏ธ | | | -| emoji | [Unicode 6.1][unicode-6] | [Unicode 13][unicode-13] | | | -| [ForkAwesome][fa] | โ˜‘๏ธ with `` | removed | | | -| [Bootstrap Icons][bootstrap-icons] | | โ˜‘๏ธ with shortcodes | | | -| LaTeX | โ˜‘๏ธ[^mj] | โ˜‘๏ธ[^kt] | | | +| Feature | HFM 1 | HFM 2 | CommonMark | GFM | +| ------------------------------------------- | :----------------------: | :----------------------: | :--------: | :-: | +| heading | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| inline code | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| indented code blocks | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| code block with language[^highlight] | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| code block with extra features[^extra-code] | โ˜‘๏ธ | โ˜‘๏ธ | | | +| block quote | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| name tag (`[name=...]`) | (โ˜‘๏ธ)[^in-bq-list] | โ˜‘๏ธ | | | +| time tag (`[time=...]`) | (โ˜‘๏ธ)[^in-bq-list] | โ˜‘๏ธ | | | +| color tag (`[color=...]`) | (โ˜‘๏ธ)[^in-bq-list] | โ˜‘๏ธ | | | +| unorderd list | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| ordered list | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| task list | โ˜‘๏ธ | โ˜‘๏ธ | | โ˜‘๏ธ | +| defition list | โ˜‘๏ธ | โ˜‘๏ธ | | | +| emoji | [Unicode 6.1][unicode-6] | [Unicode 13][unicode-13] | | | +| [ForkAwesome][fa] | โ˜‘๏ธ with `` | removed | | | +| [Bootstrap Icons][bootstrap-icons] | | โ˜‘๏ธ with shortcodes | | | +| LaTeX | โ˜‘๏ธ[^mj] | โ˜‘๏ธ[^kt] | | | [^highlight]: Code blocks with a given language are rendered using syntax highlighting. [^extra-code]: Several special "language" keywords can be used for rendering diagrams, charts, etc. @@ -47,83 +47,73 @@ These tables tell you what exactly we support in HedgeDoc 1.x (HFM 1) and HedgeD ## Links & Images -| Feature | HFM 1 | HFM 2 | CommonMark | GFM | -| --------------------- | :---: | :---: | :--------------: | :--------------: | -| link | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| link reference | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| link title | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| autolink with `<>` | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| autolink without `<>` | โ˜‘๏ธ | โ˜‘๏ธ | | โ˜‘๏ธ | -| footnotes | โ˜‘๏ธ | โ˜‘๏ธ | | | -| image | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| image with given size | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | (โ˜‘๏ธ with ``) | -| table of contents | โ˜‘๏ธ | โ˜‘๏ธ | | | +| Feature | HFM 1 | HFM 2 | CommonMark | GFM | +| --------------------- | :---: | :---: | :---------------: | :---------------: | +| link | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| link reference | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| link title | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| autolink with `<>` | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| autolink without `<>` | โ˜‘๏ธ | โ˜‘๏ธ | | โ˜‘๏ธ | +| footnotes | โ˜‘๏ธ | โ˜‘๏ธ | | | +| image | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| image with given size | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | (โ˜‘๏ธ with ``) | +| table of contents | โ˜‘๏ธ | โ˜‘๏ธ | | | ## Structural elements -| Feature | HFM 1 | HFM 2 | CommonMark | GFM | -| ----------------- | :------------------: | :---: | :------------------: | :------------------: | -| table | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with ``) | โ˜‘๏ธ | -| horizontal line | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | -| collapsable block | (โ˜‘๏ธ with `
`) | โ˜‘๏ธ | (โ˜‘๏ธ with `
`) | (โ˜‘๏ธ with `
`) | -| Alerts | โ˜‘๏ธ | โ˜‘๏ธ | | | +| Feature | HFM 1 | HFM 2 | CommonMark | GFM | +| ----------------- | :-------------------: | :---: | :-------------------: | :-------------------: | +| table | โ˜‘๏ธ | โ˜‘๏ธ | (โ˜‘๏ธ with `
`) | โ˜‘๏ธ | +| horizontal line | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | +| collapsable block | (โ˜‘๏ธ with `
`) | โ˜‘๏ธ | (โ˜‘๏ธ with `
`) | (โ˜‘๏ธ with `
`) | +| Alerts | โ˜‘๏ธ | โ˜‘๏ธ | | | ## Embeddings -HFM 1 includes support for certain embeddings of external content by using the `{%keyword parameter %}` syntax. To -increase the readability of the markdown code we decided that HFM 2 should just use plain links if possible. +HFM 1 includes support for certain embeddings of external content by using the +`{%keyword parameter %}` syntax. To increase the readability of the markdown code +we decided that HFM 2 should just use plain links if possible. -| Feature | HFM 1 | HFM 2 | CommonMark | GFM | -| --------------------------------------------------- | :---: | :---------------------: | :--------: | :---: | -| PDF (`{%pdf ... %}`) | โ˜‘๏ธ | removed | | | -| [YouTube][youtube] (`{%youtube ... %}`) | โ˜‘๏ธ | with plain link[^embed] | | | -| [Vimeo][vimeo] (`{%vimeo ... %}`) | โ˜‘๏ธ | with plain link[^embed] | | | -| [Slideshare][slideshare] (`{%slideshare ... %}`) | โ˜‘๏ธ | removed | | | -| [Speakerdeck][speakerdeck] (`{%speakerdeck ... %}`) | โ˜‘๏ธ | removed | | | -| [GitHub Gist][gist] (`{%gist ... %}`) | โ˜‘๏ธ | with plain link[^embed] | | | +| Feature | HFM 1 | HFM 2 | CommonMark | GFM | +| --------------------------------------------------- | :---: | :---------------------: | :--------: | :-: | +| PDF (`{%pdf ... %}`) | โ˜‘๏ธ | removed | | | +| [YouTube][youtube] (`{%youtube ... %}`) | โ˜‘๏ธ | with plain link[^embed] | | | +| [Vimeo][vimeo] (`{%vimeo ... %}`) | โ˜‘๏ธ | with plain link[^embed] | | | +| [Slideshare][slideshare] (`{%slideshare ... %}`) | โ˜‘๏ธ | removed | | | +| [Speakerdeck][speakerdeck] (`{%speakerdeck ... %}`) | โ˜‘๏ธ | removed | | | +| [GitHub Gist][gist] (`{%gist ... %}`) | โ˜‘๏ธ | with plain link[^embed] | | | -[^embed]: The special syntax from HFM 1 is deprecated, but will still work in HFM 2. However, a plain link to the -content should be used. +[^embed]: + The special syntax from HFM 1 is deprecated, but will still work in HFM 2. However, a plain link to the + content should be used. ## HTML -Besides the basic HTML typography elements (`

`, ``, ``, ``, ``) the following more special HTML -elements are supported by some specification. +Besides the basic HTML typography elements (`

`, ``, ``, ``, ``) +the following more special HTML elements are supported by some specification. -| Feature | HedgeDocMark 1 | HedgeDocMark 2 | CommonMark | GFM | -| :-----------: | :------------: | :------------: | :--------: | :---: | -| `` | | | โ˜‘๏ธ | | -| `<textarea>` | | โ˜‘๏ธ | โ˜‘๏ธ | | -| `<style>` | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | | -| `<xmp>` | | | โ˜‘๏ธ | | -| `<iframe>` | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | | -| `<noembed>` | โ˜‘๏ธ | | โ˜‘๏ธ | | -| `<noframes>` | โ˜‘๏ธ | | โ˜‘๏ธ | | -| `<script>` | | | โ˜‘๏ธ | | -| `<plaintext>` | | โ˜‘๏ธ | โ˜‘๏ธ | | +| Feature | HedgeDocMark 1 | HedgeDocMark 2 | CommonMark | GFM | +| :-----------: | :------------: | :------------: | :--------: | :-: | +| `<title>` | | | โ˜‘๏ธ | | +| `<textarea>` | | โ˜‘๏ธ | โ˜‘๏ธ | | +| `<style>` | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | | +| `<xmp>` | | | โ˜‘๏ธ | | +| `<iframe>` | โ˜‘๏ธ | โ˜‘๏ธ | โ˜‘๏ธ | | +| `<noembed>` | โ˜‘๏ธ | | โ˜‘๏ธ | | +| `<noframes>` | โ˜‘๏ธ | | โ˜‘๏ธ | | +| `<script>` | | | โ˜‘๏ธ | | +| `<plaintext>` | | โ˜‘๏ธ | โ˜‘๏ธ | | [fa]: https://forkaweso.me/ - [bootstrap-icons]: https://icons.getbootstrap.com/ - [youtube]: https://www.youtube.com/ - [vimeo]: https://vimeo.com/ - [slideshare]: https://www.slideshare.net/ - [speakerdeck]: https://speakerdeck.com/ - [gist]: https://gist.github.com/ - [mathjax]: https://www.mathjax.org/ - [katex]: https://katex.org/ - [gfm]: https://github.github.com/gfm/ - [commonmark]: https://spec.commonmark.org/ - [unicode-6]: https://unicode.org/versions/Unicode6.1.0/ - [unicode-13]: https://unicode.org/versions/Unicode13.0.0/ diff --git a/docs/content/setup/getting_started.md b/docs/content/setup/getting_started.md index fbf79295f..f46953c61 100644 --- a/docs/content/setup/getting_started.md +++ b/docs/content/setup/getting_started.md @@ -1,4 +1,6 @@ -HedgeDoc 2 currently supports deployment using [Docker Compose](https://docs.docker.com/compose/install/). +# Setup + +HedgeDoc 2 currently supports deployment using [Docker Compose][docker-compose]. The `docker` folder in the root of our repo contains all files required to get started, deploying HedgeDoc 2, a PostgreSQL database and a Caddy reverse proxy. @@ -6,8 +8,8 @@ HedgeDoc 2, a PostgreSQL database and a Caddy reverse proxy. ## Development or local testing To run HedgeDoc 2 locally, you do not need to change anything. -Caddy will automatically generate a TLS certificate for `hedgedoc2.localhost` using its internal CA. -After running `docker compose up`, visit [https://hedgedoc2.localhost](https://hedgedoc2.localhost). +Caddy will automatically generate a TLS certificate for `hedgedoc2.localhost` using its internal CA. +After running `docker compose up`, visit <https://hedgedoc2.localhost>. You will have to accept the TLS warning in your browser the first time the page is opened. ## Production setup @@ -15,7 +17,7 @@ You will have to accept the TLS warning in your browser the first time the page !!! danger "HedgeDoc 2 is not yet production ready!" This section explains how a production deployment of HedgeDoc 2 on a publicly accessible domain might look in the future. - HedgeDoc 2 itself is not production ready yet, so only use these instructions to set up an + HedgeDoc 2 itself is not production ready yet, so only use these instructions to set up an instance for testing with your friends. For a production setup, first set a unique session secret with @@ -23,13 +25,16 @@ For a production setup, first set a unique session secret with Then open the `.env` file and edit `HD_BASE_URL`. It needs to contain the full URL of your instance, like it will be entered in the browser. If you enter a URL starting with `https://`, Caddy will -automatically gather certificates via *Let's Encrypt* (or its internal CA in case of `.localhost` domains). +automatically gather certificates via *Let's Encrypt* +(or its internal CA in case of `.localhost` domains). Make sure your host is accessible under the domain from `HD_BASE_URL`, otherwise Let's Encrypt validation will fail. Optionally, you can also change - -- `HD_MEDIA_BACKEND`: If you do not want HedgeDoc to handle media uploads itself, configure another backend - here. For more information, [see the media backend docs](/config/#media). + +- `HD_MEDIA_BACKEND`: If you do not want HedgeDoc to handle media uploads itself, configure + another backend here. For more information, [see the media backend docs](/config/#media). - `HD_AUTH_*`: If you do not want to use the integrated auth system, you can [consult the authentication docs](/config/#authentication) for details. + +[docker-compose]: https://docs.docker.com/compose/install/