diff --git a/.github/workflows/docs-netlify-deploy.yml b/.github/workflows/docs-netlify-deploy.yml new file mode 100644 index 000000000..1841e38e3 --- /dev/null +++ b/.github/workflows/docs-netlify-deploy.yml @@ -0,0 +1,55 @@ +# SPDX-FileCopyrightText: 2023 The HedgeDoc developers (see AUTHORS file) +# +# SPDX-License-Identifier: AGPL-3.0-only + +name: Deploy HD2 docs to Netlify + +on: + push: + branches: [ develop ] + paths: ['docs/**'] + +env: + NETLIFY_VERSION: 13.2.2 + NODEJS_VERSION: 20 + PYTHON_VERSION: 3.11 + +defaults: + run: + working-directory: docs + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }}-${{ github.job }} + cancel-in-progress: true + +jobs: + deploy: + runs-on: ubuntu-latest + name: Deploys to netlify + steps: + - name: Checkout repository + uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3 + + - name: Setup node + uses: ./.github/actions/setup-node + with: + NODEJS_VERSION: ${{ env.NODEJS_VERSION }} + + - name: Set up Python + uses: actions/setup-python@v1 + with: + python-version: ${{ env.PYTHON_VERSION }} + + - name: Install dependencies + run: pip install -r requirements.txt + + - name: Build docs + run: mkdocs build + + - name: Install netlify CLI + run: "yarn add --dev netlify-cli@${{ env.NETLIFY_VERSION }}" + + - name: Run netlify CLI deployment + env: + NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} + run: "netlify deploy --build --prod --message \"${{ github.event.head_commit.id }}\"" diff --git a/.reuse/dep5 b/.reuse/dep5 index 7effb87e0..97ab25bd7 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -35,11 +35,11 @@ Files: docs/**/*.png Copyright: 2021 The HedgeDoc developers (see AUTHORS file) License: CC-BY-SA-4.0 -Files: docs/content/dev/db-schema.plantuml +Files: docs/content/old/dev/db-schema.plantuml Copyright: 2021 The HedgeDoc developers (see AUTHORS file) License: CC-BY-SA-4.0 -Files: docs/content/dev/*api.yml +Files: docs/content/old/dev/*api.yml Copyright: 2021 The HedgeDoc developers (see AUTHORS file) License: CC-BY-SA-4.0 @@ -55,6 +55,26 @@ Files: docs/content/theme/styles/Roboto/* Copyright: 2011 Christian Robertson License: Apache-2.0 +Files: docs/content/files/setup-docker/config.env +Copyright: 2023 The HedgeDoc developers (see AUTHORS file) +License: CC0-1.0 + +Files: docs/content/files/setup-docker/docker-compose.yml +Copyright: 2023 The HedgeDoc developers (see AUTHORS file) +License: CC0-1.0 + +Files: docs/content/files/setup-docker/Caddyfile +Copyright: 2023 The HedgeDoc developers (see AUTHORS file) +License: CC0-1.0 + +Files: docs/netlify.toml +Copyright: 2021 The HedgeDoc developers (see AUTHORS file) +License: CC0-1.0 + +Files: docs/.netlify/* +Copyright: 2021 The HedgeDoc developers (see AUTHORS file) +License: CC0-1.0 + Files: backend/public/*.md Copyright: 2021 The HedgeDoc developers (see AUTHORS file) License: CC0-1.0 diff --git a/docs/.markdownlint.json b/docs/.markdownlint.json index 8b7578c19..9bfc32ae3 100644 --- a/docs/.markdownlint.json +++ b/docs/.markdownlint.json @@ -25,7 +25,7 @@ "style": "---" }, "MD044": { - "names": ["HedgeDoc"] + "names": ["HedgeDoc", "Docker"] }, "MD046": { "style": "fenced" diff --git a/docs/.netlify/state.json b/docs/.netlify/state.json new file mode 100644 index 000000000..63cd58deb --- /dev/null +++ b/docs/.netlify/state.json @@ -0,0 +1,3 @@ +{ + "siteId": "3cb86ea9-e257-40f3-ab9c-7b9eb08423c4" +} \ No newline at end of file diff --git a/docs/content/dev/design_docs/api_auth.md b/docs/content/concepts/api-auth.md similarity index 94% rename from docs/content/dev/design_docs/api_auth.md rename to docs/content/concepts/api-auth.md index cdef607f3..47c456060 100644 --- a/docs/content/dev/design_docs/api_auth.md +++ b/docs/content/concepts/api-auth.md @@ -1,8 +1,8 @@ # API Authentication !!! 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. ## Public API diff --git a/docs/content/dev/design_docs/config.md b/docs/content/concepts/config.md similarity index 100% rename from docs/content/dev/design_docs/config.md rename to docs/content/concepts/config.md diff --git a/docs/content/dev/design_docs/events.md b/docs/content/concepts/events.md similarity index 100% rename from docs/content/dev/design_docs/events.md rename to docs/content/concepts/events.md diff --git a/docs/content/concepts/index.md b/docs/content/concepts/index.md new file mode 100644 index 000000000..b98221ceb --- /dev/null +++ b/docs/content/concepts/index.md @@ -0,0 +1,39 @@ +# Core concepts + +Core concepts explain the internal structure of HedgeDoc by providing +background information and explanations. They are especially useful for contributing to HedgeDoc. + + +
+ +
+ ๐Ÿ“ + Notes +
+ + +
+ ๐Ÿ™Ž + User Profiles +
+ + +
+ ๐Ÿ› ๏ธ + Config +
+ + +
+ ๐Ÿค–๏ธ + API Auth +
+ + +
+ ๐ŸŽฉ + Events +
+ +
+ diff --git a/docs/content/dev/design_docs/notes.md b/docs/content/concepts/notes.md similarity index 100% rename from docs/content/dev/design_docs/notes.md rename to docs/content/concepts/notes.md diff --git a/docs/content/dev/design_docs/user_profiles.md b/docs/content/concepts/user-profiles.md similarity index 94% rename from docs/content/dev/design_docs/user_profiles.md rename to docs/content/concepts/user-profiles.md index 5a6d6f089..341da9fcf 100644 --- a/docs/content/dev/design_docs/user_profiles.md +++ b/docs/content/concepts/user-profiles.md @@ -88,9 +88,9 @@ In this case, the frontend should show the use a notice that they should contact 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 diff --git a/docs/content/config/index.md b/docs/content/config/index.md deleted file mode 100644 index 70df3e586..000000000 --- a/docs/content/config/index.md +++ /dev/null @@ -1,208 +0,0 @@ -# Configuration - -HedgeDoc can be configured via environment variables either directly or via an `.env` file. - -## The `.env` file - -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" -HD_DATABASE_TYPE="sqlite" -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. - -!!! warning - The minimal configuration provided in `.env.example` is exactly that: minimal. - It will let you start HedgeDoc for local development, - but it is **not** meant to be used in production without prior changes. - -## 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. | -| `HD_RENDERER_BASE_URL` | Content of HD_BASE_URL | | The URL the renderer runs on. If omitted this will be the same as `HD_BASE_URL`. | -| `HD_LOGLEVEL` | warn | | The loglevel that should be used. Options are `error`, `warn`, `info`, `debug` or `trace`. | -| `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_PERSIST_INTERVAL` | 10 | `0`, `5`, `10`, `20` | The time interval in **minutes** for the periodic note revision creation during realtime editing. `0` deactivates the periodic note revision creation. | - -### Why should I want to run my renderer on a different (sub-)domain? - -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][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. - -## 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. | -| `HD_PERMISSION_DEFAULT_LOGGED_IN` | `write` | `none`, `read`, `write` | The default permission for the "logged-in" group that is set on new notes. | -| `HD_PERMISSION_DEFAULT_EVERYONE` | `read` | `none`, `read`, `write` | The default permission for the "everyone" group (logged-in & guest users), that is set on new notes created by logged-in users. Notes created by guests always set this to "write". | - -## Authentication - -!!! info - HedgeDoc 2 does not yet support all authentication backends from HedgeDoc 1. - You can follow [this issue](https://github.com/hedgedoc/hedgedoc/issues/1006) for details. - -### 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. - -| 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. | - -#### Password score - -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 | -| 3 | `safely unguessable` and `very unguessable` passwords are allowed | 100.000.000 | -| 4 | Only `very unguessable` passwords are allowed | 10.000.000.000 | - -### 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_LDAP_SERVERS`), -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_LDAP_SERVERS` | - | `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. | -| `HD_AUTH_LDAP_$NAME_SEARCH_BASE` | - | `ou=users,dc=LDAP,dc=example,dc=com` | The LDAP search base which contains the user accounts on the LDAP server. | -| `HD_AUTH_LDAP_$NAME_SEARCH_FILTER` | `(uid={{username}})` | `(&(uid={{username}})(objectClass=inetOrgPerson))` | A LDAP search filter that filters the users that should have access. | -| `HD_AUTH_LDAP_$NAME_SEARCH_ATTRIBUTES` | - | `username,cn` | A comma-seperated list of attributes that the search filter from the LDAP server should access. | -| `HD_AUTH_LDAP_$NAME_USERID_FIELD` | `uid` | `uid`, `uidNumber`, `sAMAccountName` | The attribute of the user account which should be used as an id for the user. | -| `HD_AUTH_LDAP_$NAME_DISPLAY_NAME_FIELD` | `displayName` | `displayName`, `name`, `cn` | The attribute of the user account which should be used as the display name for the user. | -| `HD_AUTH_LDAP_$NAME_PROFILE_PICTURE_FIELD` | `jpegPhoto` | `jpegPhoto`, `thumbnailPhoto` | The attribute of the user account which should be used as the user image for the user. | -| `HD_AUTH_LDAP_$NAME_BIND_DN` | - | `cn=admin,dc=LDAP,dc=example,dc=com` | The dn which is used to perform the user search. If this is omitted then HedgeDoc will use an anonymous bind. | -| `HD_AUTH_LDAP_$NAME_BIND_CREDENTIALS` | - | `MyLdapPassword` | The credential to access the LDAP server. | -| `HD_AUTH_LDAP_$NAME_TLS_CERT_PATHS` | - | `LDAP-ca.pem` | A comma-seperated list of paths to TLS certificates for the LDAP server. | - -**ToDo:** Add other authentication methods. - -## 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. - -| 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 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: -![The demo logo][demo-logo] - -![The demo logo on the Frontpage][logo-front-page] -*logo used on the front page* - -![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` - -![The name on the Frontpage][name-front-page] -*name used on the front page* - -![The name in the editor (light)][name-editor-light] -![The name in the editor (dark)][name-editor-dark] -*name used in the editor* - -## Database - -We officially support and test these databases: - -- SQLite (for development and smaller instances) -- 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`.* | - -## 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 | - -## Media - -There are a couple of different backends that can be used to host your images for HedgeDoc. - -- [Azure](media/azure.md) -- [Local filesystem](media/filesystem.md) -- [Imgur](media/imgur.md) -- [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/faq/index.md b/docs/content/faq/index.md new file mode 100644 index 000000000..acd9c31f9 --- /dev/null +++ b/docs/content/faq/index.md @@ -0,0 +1,99 @@ +# Frequently Asked Questions + +This page collects Frequently Asked Questions of the community. +If you have any questions that aren't answered here, feel free to ask on our +[community forums][hedgedoc-community] or in out [Matrix chat][matrix.org-url]. + +[matrix.org-url]: https://chat.hedgedoc.org +[hedgedoc-community]: https://community.hedgedoc.org + +## Why did you switch from MathJax to KaTeX? + +The new react frontend, that was introduced with HedgeDoc 2.0 switched from MathJax 2 +to [KaTeX][katex], because: + +- [KaTeX is much faster than MathJax](https://www.intmath.com/cg5/katex-mathjax-comparison.php?processor=MathJax ) +- [The MathJax React Component is not maintained and doesn't support MathJax 3](https://github.com/wko27/react-mathjax) +- [KaTeX supports every command you'll need for math expressions](https://katex.org/docs/supported.html) + +[katex]: https://katex.org/ + +## Why are code-blocks with 'sequence' as language deprecated? + +Starting with HedgeDoc 2.0, mermaid is used for rendering sequence-diagrams. +The [syntax][mermaid-syntax] doesn't change. To remove the deprecation warning, simply change the +codeblock-"language" from `sequence` to `mermaid` and insert a single line with `sequenceDiagram` +just before your diagram content. + +**Deprecated**: + +```sequence +Alice->>John: Hello John, how are you? +John-->>Alice: Great! +``` + +**New**: + +```mermaid +sequenceDiagram +Alice->>John: Hello John, how are you? +John-->>Alice: Great! +``` + +[mermaid-syntax]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram + +## Why do tags in headings don't work anymore? + +Starting with HedgeDoc 2.0, we don't support tag headings in the note anymore. + +```markdown +#### tags: `tag1`, `tag2` +``` + +Instead, please use the [frontmatter metadata][frontmatter] to specify tags. + +[frontmatter]: https://demo.hedgedoc.org/yaml-metadata#tags + +## Why is the comma separated definition of tags in the YAML-metadata deprecated? + +[YAML already has a definition for lists](https://yaml.org/spec/1.2/spec.html#id2759963). +Therefore, we don't see any reason to maintain another way to define a list. + + +**Deprecated** + + +```yaml +tags: tag1, tag2 +``` + + +**New** + + +```yaml +tags: + - tag1 + - tag2 +``` + + +*or* + + +```yaml +tags: ['tag1', 'tag2'] +``` + +## Why should I want to run my renderer on a different (sub-)domain? + +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][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. + +[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting diff --git a/docs/content/files/setup-docker/Caddyfile b/docs/content/files/setup-docker/Caddyfile new file mode 100644 index 000000000..ae82699c1 --- /dev/null +++ b/docs/content/files/setup-docker/Caddyfile @@ -0,0 +1,14 @@ +{$HD_BASE_URL} + +log { + output stdout + level WARN + format console +} + +reverse_proxy /realtime http://backend:3000 +reverse_proxy /api/* http://backend:3000 +reverse_proxy /public/* http://backend:3000 +reverse_proxy /uploads/* http://backend:3000 +reverse_proxy /apidoc/* http://backend:3000 +reverse_proxy /* http://frontend:3001 \ No newline at end of file diff --git a/docs/content/files/setup-docker/config.env b/docs/content/files/setup-docker/config.env new file mode 100644 index 000000000..edd4e9c36 --- /dev/null +++ b/docs/content/files/setup-docker/config.env @@ -0,0 +1,19 @@ +# General settings +HD_BASE_URL="https://md.example.com" +HD_SESSION_SECRET="change_me_in_production" + +# Database settings +HD_DATABASE_TYPE="postgres" +HD_DATABASE_HOST="db" +HD_DATABASE_PORT="5432" +HD_DATABASE_NAME="hedgedoc" +HD_DATABASE_USER="hedgedoc" +HD_DATABASE_PASS="password" + +# Uploads +HD_MEDIA_BACKEND="filesystem" +HD_MEDIA_BACKEND_FILESYSTEM_UPLOAD_PATH="uploads/" + +# Auth +HD_AUTH_LOCAL_ENABLE_LOGIN="true" +HD_AUTH_LOCAL_ENABLE_REGISTER="true" \ No newline at end of file diff --git a/docs/content/files/setup-docker/docker-compose.yml b/docs/content/files/setup-docker/docker-compose.yml new file mode 100644 index 000000000..0daf06bfa --- /dev/null +++ b/docs/content/files/setup-docker/docker-compose.yml @@ -0,0 +1,38 @@ +services: + backend: + image: ghcr.io/hedgedoc/hedgedoc/backend:2.0-alpha + volumes: + - $PWD/.env:/usr/src/app/backend/.env + - hedgedoc_uploads:/usr/src/app/backend/uploads + + frontend: + image: ghcr.io/hedgedoc/hedgedoc/frontend:2.0-alpha + environment: + HD_BASE_URL: "${HD_BASE_URL}" + + db: + image: postgres:15 + environment: + POSTGRES_USER: "${HD_DATABASE_USER}" + POSTGRES_PASSWORD: "${HD_DATABASE_PASS}" + POSTGRES_DB: "${HD_DATABASE_NAME}" + volumes: + - hedgedoc_postgres:/var/lib/postgresql/data + + proxy: + image: caddy:latest + restart: unless-stopped + environment: + HD_BASE_URL: "${HD_BASE_URL}" + ports: + - "80:80" + - "443:443" + - "443:443/udp" + volumes: + - $PWD/Caddyfile:/etc/caddy/Caddyfile + - caddy_data:/data + +volumes: + caddy_data: + hedgedoc_uploads: + hedgedoc_postgres: \ No newline at end of file diff --git a/docs/content/how-to/auth.md b/docs/content/how-to/auth.md new file mode 100644 index 000000000..d22a186d2 --- /dev/null +++ b/docs/content/how-to/auth.md @@ -0,0 +1,5 @@ +# How to use other authentication methods + +TODO: This pages is still missing some content. +See this issue for more information and if you want to contribute: + diff --git a/docs/content/how-to/backup.md b/docs/content/how-to/backup.md new file mode 100644 index 000000000..be2390305 --- /dev/null +++ b/docs/content/how-to/backup.md @@ -0,0 +1,5 @@ +# How to back up HedgeDoc + +TODO: This pages is still missing some content. +See this issue for more information and if you want to contribute: + diff --git a/docs/content/how-to/database.md b/docs/content/how-to/database.md new file mode 100644 index 000000000..04155c67b --- /dev/null +++ b/docs/content/how-to/database.md @@ -0,0 +1,5 @@ +# Database + +TODO: This pages is still missing some content. +See this issue for more information and if you want to contribute: + diff --git a/docs/content/dev/auth/ldap.md b/docs/content/how-to/develop/auth/ldap.md similarity index 59% rename from docs/content/dev/auth/ldap.md rename to docs/content/how-to/develop/auth/ldap.md index e040b620f..45298c20b 100644 --- a/docs/content/dev/auth/ldap.md +++ b/docs/content/how-to/develop/auth/ldap.md @@ -1,15 +1,17 @@ # LDAP -LDAP authentication can be tested with the [`test-openldap`][docker-image] -docker image from [rroemhild][rroemhild]. +If you are developing HedgeDoc and need to test something with an LDAP server you can use the +[`test-openldap`][docker-image] Docker image from [rroemhild][rroemhild]. Simply run -```sh + +```shell docker run --rm -p 10389:10389 -p 10636:10636 rroemhild/test-openldap ``` + -and add the following to the `.env` file before starting the backend. +and add the following to the `.env` file then start the backend. ```dotenv HD_AUTH_LDAP_SERVERS="FUTURAMA" @@ -23,7 +25,7 @@ HD_AUTH_LDAP_FUTURAMA_BIND_DN="cn=admin,dc=planetexpress,dc=com" HD_AUTH_LDAP_FUTURAMA_BIND_CREDENTIALS="GoodNewsEveryone" ``` -You should then be able to log in with either of these logins (`username` : `password`): +You should be able to log in with either of these logins (`username` : `password`): - `professor` : `professor` - `fry` : `fry` @@ -33,5 +35,8 @@ You should then be able to log in with either of these logins (`username` : `pas - `bender` : `bender` - `amy` : `amy` +If you need to know more about which information are held by each of these accounts, have a look at +the [documentation](https://github.com/rroemhild/docker-test-openldap#ldap-structure). + [docker-image]: https://github.com/rroemhild/docker-test-openldap [rroemhild]: https://github.com/rroemhild diff --git a/docs/content/dev/docker.md b/docs/content/how-to/develop/docker.md similarity index 87% rename from docs/content/dev/docker.md rename to docs/content/how-to/develop/docker.md index e471db3fd..1d3e15151 100644 --- a/docs/content/dev/docker.md +++ b/docs/content/how-to/develop/docker.md @@ -1,12 +1,12 @@ # Building Docker images -To build docker images of the backend or frontend use the following commands. +To build Docker images of the backend or frontend use the following commands. 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 +```shell docker buildx build -f backend/docker/Dockerfile -t hedgedoc-backend . ``` @@ -14,7 +14,7 @@ docker buildx build -f backend/docker/Dockerfile -t hedgedoc-backend . or -```sh +```shell docker buildx build -f frontend/docker/Dockerfile -t hedgedoc-frontend . ``` diff --git a/docs/content/dev/documentation.md b/docs/content/how-to/develop/documentation.md similarity index 74% rename from docs/content/dev/documentation.md rename to docs/content/how-to/develop/documentation.md index dfd84d95d..504b3364d 100644 --- a/docs/content/dev/documentation.md +++ b/docs/content/how-to/develop/documentation.md @@ -1,14 +1,16 @@ # Documentation -Our documentation is build with [mkdocs][mkdocs]. +Our documentation is build with [mkdocs][mkdocs]. While you can write documentation with every text +editor you like, if you want to build the documentation and want to see at how it will look you need +to have [python3][python3] and [mkdocs][mkdocs] installed. ## Writing -All documentation files are found in the `docs/content` directory of +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 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. @@ -19,20 +21,24 @@ otherwise the files will be very hard to find on the documentation website. To build the documentation locally you need to perform the following steps: -1. Make sure you have python3 installed. +1. Make sure you have [python3][python3] installed. `python3 --version` 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` 4. Start the mkdocs dev server (`mkdocs serve`) or build the documentation (`mkdocs build`). +If you run `mkdcs serve` a local server will serve the mkdocs files and change the served files as +you write documentation. + ## Deployment The documentation is deployed with [mkdocs][mkdocs]. 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 +[python3]: https://www.python.org/ [docs.hedgedoc.org]: https://github.com/hedgedoc/docs.hedgedoc.org diff --git a/docs/content/dev/setup/frontend.md b/docs/content/how-to/develop/frontend.md similarity index 99% rename from docs/content/dev/setup/frontend.md rename to docs/content/how-to/develop/frontend.md index a075c6d34..8c1065861 100644 --- a/docs/content/dev/setup/frontend.md +++ b/docs/content/how-to/develop/frontend.md @@ -11,7 +11,7 @@ The following environment variables are recognized by the frontend process. | 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 +Variables that start with `NEXT_PUBLIC_` will be compiled into the build. You can't change them after compilation. You shouldn't need to set them yourself. Use the designated npm tasks instead. ## UI Test diff --git a/docs/content/dev/getting-started.md b/docs/content/how-to/develop/setup.md similarity index 97% rename from docs/content/dev/getting-started.md rename to docs/content/how-to/develop/setup.md index 9311b0d94..cc2a01326 100644 --- a/docs/content/dev/getting-started.md +++ b/docs/content/how-to/develop/setup.md @@ -1,4 +1,4 @@ -# Getting started +# Development Setup To run HedgeDoc 2.0 you need three components: the backend, the frontend and the reverse proxy. @@ -12,7 +12,7 @@ This describes the easiest way to start a local development environment. For oth 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). +Backend and Frontend are included in the [HegdeDoc repo][hedgedoc-repo]. The reverse proxy can be chosen by preference. For development, we recommend caddy and the provided configuration. @@ -81,7 +81,7 @@ For development, we recommend creating an `.env` file. ## Build the `commons` package -Some code is shared by backend and frontend. This code lives in the `commons package and needs +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. @@ -158,5 +158,5 @@ We recommend to use our pre-configured [Caddy][caddy] configuration. [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 +[config-docs]: /references/config/ +[frontend-setup]: ./frontend.md diff --git a/docs/content/how-to/index.md b/docs/content/how-to/index.md new file mode 100644 index 000000000..84df40106 --- /dev/null +++ b/docs/content/how-to/index.md @@ -0,0 +1,34 @@ +# How-to guides + +How-to guides target the more advanced users and guide them +through a variety of topics, addressing non-trivial use-cases. +They are more advanced than tutorials and assume some knowledge of HedgeDoc. + + +
+ +
+ โ†ฉ๏ธ๏ธ + Configure a reverse proxy +
+ + +
+ ๐Ÿ’พ + Back up your instance +
+ + +
+ ๐Ÿ”‘ + Customize authentication +
+ + +
+ ๐Ÿ—„ + Use another database +
+ +
+ diff --git a/docs/content/how-to/reverse-proxy.md b/docs/content/how-to/reverse-proxy.md new file mode 100644 index 000000000..1a236aca5 --- /dev/null +++ b/docs/content/how-to/reverse-proxy.md @@ -0,0 +1,217 @@ +# How to use a reverse proxy + + + +When having multiple webservers or other applications running, that also use +port 80 and 443, you probably want to use a reverse proxy to serve HedgeDoc. + +We'll assume the domain you use for the instance is , so please +substitute your actual domain anywhere you encounter . + +## Configuring the reverse proxy + +We have collected some example configurations for popular reverse proxies below. +At the end is also a list of generic things the reverse proxy must do, if you prefer +to write your own config or use a reverse proxy not mentioned here. + +### Traefik + +As [traefik][traefik] has direct access to your running Docker containers, there is no need to +configure extra ports. Instead, you'll only have to add the following labels to the services +in your `docker-compose.yml`: + + + +??? abstract "docker-compose.yml" + ```yaml + backend: + image: ghcr.io/hedgedoc/hedgedoc/backend:2.0-alpha + volumes: + - $PWD/.env:/usr/src/app/backend/.env + - hedgedoc_uploads:/usr/src/app/backend/uploads + labels: + traefik.enable: "true" + traefik.http.routers.hedgedoc_2_backend.rule: "Host(`md.example.com`) && PathPrefix(`/realtime`, `/api`, `/public`)" + traefik.http.routers.hedgedoc_2_backend.tls: "true" + traefik.http.routers.hedgedoc_2_backend.tls.certresolver: "letsencrypt" + traefik.http.services.hedgedoc_2_backend.loadbalancer.server.port: "3000" + traefik.http.services.hedgedoc_2_backend.loadbalancer.server.scheme: "http" + frontend: + image: ghcr.io/hedgedoc/hedgedoc/frontend:2.0-alpha + environment: + HD_BASE_URL: "${HD_BASE_URL}" + labels: + traefik.enable: "true" + traefik.http.routers.hedgedoc_2_frontend.rule: "Host(`md.example.com`)" + traefik.http.routers.hedgedoc_2_frontend.tls: "true" + traefik.http.routers.hedgedoc_2_frontend.tls.certresolver: "letsencrypt" + traefik.http.services.hedgedoc_2_frontend.loadbalancer.server.port: "3001" + traefik.http.services.hedgedoc_2_frontend.loadbalancer.server.scheme: "http" + ``` + + + +We added [Let's Encrypt][letsencrypt] as a certificate resolver, as it enables you to +quickly use HTTPS. If you don't want to use that feel free to change +the `.certresolver` variables accordingly. + +If you used the `docker-compose.yml` file from the tutorial, please remove +the service `proxy` and the volume `caddy_data` as caddy is no longer needed when using traefik. + +### Other reverse proxies + +In the following we'll also assume that you run a HedgeDoc backend on port `3000`, +a HedgeDoc frontend on port `3001`. +Furthermore, we assume that you have TLS certificates located at +`/etc/letsencrypt/live/md.example.com/fullchain.pem` +and +`/etc/letsencrypt/live/md.example.com/privkey.pem` respectively +and are using [Let's Encrypt][letsencrypt] for your certificates. +Replace these paths with the actual paths to your certificates. + +**Preparations when using the default docker-compose.yml:** + +If your starting with the `docker-compose.yml` file from the tutorial, +you need to add the `ports` entry for both `backend` and `frontend` as following. + + + +??? abstract "docker-compose.yml" + ```yaml + backend: + image: ghcr.io/hedgedoc/hedgedoc/backend:2.0-alpha + volumes: + - $PWD/.env:/usr/src/app/backend/.env + - hedgedoc_uploads:/usr/src/app/backend/uploads + ports: + - "3000:3000" + frontend: + image: ghcr.io/hedgedoc/hedgedoc/frontend:2.0-alpha + environment: + HD_BASE_URL: "${HD_BASE_URL}" + ports: + - "3001:3001" + ``` + + + +Also, you want to remove the service `proxy` and the volume `caddy_data` +to avoid port conflicts with your reverse-proxy software. + +#### nginx + +Here is an example configuration for [nginx][nginx]. + + + +??? abstract "nginx config" + ``` + map $http_upgrade $connection_upgrade { + default upgrade; + '' close; + } + server { + server_name md.example.com; + + location ~ ^/(api|public|uploads|apidoc)/ { + proxy_pass http://127.0.0.1:3000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + + location /realtime { + proxy_pass http://127.0.0.1:3000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + } + + location / { + proxy_pass http://127.0.0.1:3001; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + + listen [::]:443 ssl http2; + listen 443 ssl http2; + ssl_certificate fullchain.pem; + ssl_certificate_key privkey.pem; + include options-ssl-nginx.conf; + ssl_dhparam ssl-dhparams.pem; + } + ``` + + + +#### Apache + +You will need these modules enabled: `proxy`, `proxy_http` and `proxy_wstunnel`. +Here is an example config snippet for [Apache][apache]: + + + +??? abstract "Apache config" + ``` + + ServerName md.example.com + + RewriteEngine on + RewriteCond %{REQUEST_URI} ^/realtime [NC] + RewriteCond %{HTTP:Upgrade} =websocket [NC] + RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L] + + ProxyPass /api http://127.0.0.1:3000/ + ProxyPass /apidoc http://127.0.0.1:3000/ + ProxyPass /public http://127.0.0.1:3000/ + ProxyPass /realtime http://127.0.0.1:3000/ + + ProxyPassReverse /api http://127.0.0.1:3000/ + ProxyPassReverse /apidoc http://127.0.0.1:3000/ + ProxyPassReverse /public http://127.0.0.1:3000/ + ProxyPassReverse /realtime http://127.0.0.1:3000/ + + ProxyPass / http://127.0.0.1:3001/ + ProxyPassReverse / http://127.0.0.1:3001/ + + RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME} + + ErrorLog ${APACHE_LOG_DIR}/error.log + CustomLog ${APACHE_LOG_DIR}/access.log combined + + SSLCertificateFile /etc/letsencrypt/live/md.example.com/fullchain.pem + SSLCertificateKeyFile /etc/letsencrypt/live/md.example.com/privkey.pem + Include /etc/letsencrypt/options-ssl-apache.conf + + ``` + + + +#### Generic + +Here is a list of things your reverse proxy needs to do to let HedgeDoc work: + +- Websocket `Upgrade` requests at path `/realtime`. +- Passing `/realtime` to +- Passing `/api/*` to +- Passing `/public/*` to +- Passing `/uploads/*` to +- Passing `/apidoc/*` to +- Passing `/*` to +- Set the `X-Forwarded-Proto` header + +In essence there are a few special urls that need to be handled by the HedgeDoc backend +and everything else is handled by the frontend. + + + +[traefik]: https://traefik.io/traefik/ +[letsencrypt]: https://letsencrypt.org/ +[nginx]: https://nginx.org/ +[apache]: https://httpd.apache.org/ diff --git a/docs/content/images/tutorial/note/editor-filled.png b/docs/content/images/tutorial/note/editor-filled.png new file mode 100644 index 000000000..d88fc0404 Binary files /dev/null and b/docs/content/images/tutorial/note/editor-filled.png differ diff --git a/docs/content/images/tutorial/note/editor.png b/docs/content/images/tutorial/note/editor.png new file mode 100644 index 000000000..daabfe70b Binary files /dev/null and b/docs/content/images/tutorial/note/editor.png differ diff --git a/docs/content/images/tutorial/top-right.png b/docs/content/images/tutorial/top-right.png new file mode 100644 index 000000000..56ba75b1f Binary files /dev/null and b/docs/content/images/tutorial/top-right.png differ diff --git a/docs/content/images/tutorial/user/register-button.png b/docs/content/images/tutorial/user/register-button.png new file mode 100644 index 000000000..40203abd4 Binary files /dev/null and b/docs/content/images/tutorial/user/register-button.png differ diff --git a/docs/content/images/tutorial/user/register-form.png b/docs/content/images/tutorial/user/register-form.png new file mode 100644 index 000000000..f127770d7 Binary files /dev/null and b/docs/content/images/tutorial/user/register-form.png differ diff --git a/docs/content/index.md b/docs/content/index.md index 2c947a617..77c0f882c 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -1,16 +1,75 @@ # Welcome to the HedgeDoc 2 Documentation -HedgeDoc Logo -HedgeDoc Logo +HedgeDoc Logo +HedgeDoc Logo -๐Ÿšงโš ๏ธ๐Ÿšง **HedgeDoc 2.0 is still in development!** -You are probably looking for the 1.x docs. +!!! danger "๐Ÿšงโš ๏ธ๐Ÿšง **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). + + +Welcome to the documentation for HedgeDoc, a collaborative online markdown editor, +that you can host yourself. + +## Quick start + -Find them in the `master` branch and on [docs.hedgedoc.org](https://docs.hedgedoc.org). + +- ๐Ÿฆ” New to HedgeDoc? Take the [HedgeDoc tour][hedgedoc-tour] +- ๐Ÿš€ Want your own instance? [Install HedgeDoc yourself][install-guide] +- ๐Ÿ› ๏ธ Want to change something about HedgeDoc? Read the [Configuration reference][config-reference] -If you want to help us to develop HedgeDoc 2, join us on [Matrix][matrix.org-url]! +## Getting help -[matrix.org-url]: https://chat.hedgedoc.org +Having trouble? Weโ€™d like to help! + +- โ“ Take a look into the [FAQ][faq] โ€“ there are answers to many common questions. +- ๐ŸŒ Still any questions? Ask them at our [community forum][community-forum]. +- ๐Ÿ’ฌ Talk to us on our [matrix chat][chat]. +- ๐Ÿ› Report bugs in our [issue tracker][issue-tracker]. + +## How the documentation is organized + +To make it easy for you to find the relevant documentation articles, we organized our docs by the +following categories: + +- **[Tutorials][tutorials]** are detailed step-by-step instructions. Start here if you're new to + HedgeDoc, want to create your first presentation or want to build a simple API application. +- **[How-to guides][how-to]** target the more advanced users and guide them through a variety of + topics, addressing non-trivial use-cases. They are more advanced than tutorials and assume some + knowledge of HedgeDoc. +- **[Core concepts][core-concepts]** explain the internal structure of HedgeDoc by providing + background information and explanations. They are especially useful for contributing to HedgeDoc. +- **[References][references]** are details to lookup in a non-guided way. These include for example + configuration options or API methods. + +## Participate in the HedgeDoc project + +There are different ways how you can participate in the HedgeDoc project: + +- Help others or share your experiences and tips in the [community forum][community-forum]. +- Improve the translation HegdeDoc of HedgeDoc into your language at our [weblate][weblate]. +- Report bugs, feature requests or enhancement ideas in our [issue tracker][issue-tracker]. +- Read the [getting started how-to for developers][how-to-dev] to start implementing + your own features. + +[hedgedoc-tour]: https://tour.hedgedoc.org +[install-guide]: /tutorials/setup/ +[config-reference]: /references/config/ + +[faq]: /faq/ +[community-forum]: https://community.hedgedoc.org/ +[chat]: https://chat.hedgedoc.org +[issue-tracker]: https://github.com/hedgedoc/hedgedoc/issues/new/choose + +[tutorials]: /tutorials/ +[how-to]: /how-to/ +[core-concepts]: /concepts/ +[references]: /references/ + +[weblate]: https://translate.hedgedoc.org +[how-to-dev]: /how-to/develop/ diff --git a/docs/content/dev/db-schema.plantuml b/docs/content/old/dev/db-schema.plantuml similarity index 100% rename from docs/content/dev/db-schema.plantuml rename to docs/content/old/dev/db-schema.plantuml diff --git a/docs/content/dev/dev_notes.md b/docs/content/old/dev/dev_notes.md similarity index 100% rename from docs/content/dev/dev_notes.md rename to docs/content/old/dev/dev_notes.md diff --git a/docs/content/dev/public_api.yml b/docs/content/old/dev/public_api.yml similarity index 100% rename from docs/content/dev/public_api.yml rename to docs/content/old/dev/public_api.yml diff --git a/docs/content/images/interface/toolbar/blocks.png b/docs/content/old/images/interface/toolbar/blocks.png similarity index 100% rename from docs/content/images/interface/toolbar/blocks.png rename to docs/content/old/images/interface/toolbar/blocks.png diff --git a/docs/content/images/interface/toolbar/emoji.png b/docs/content/old/images/interface/toolbar/emoji.png similarity index 100% rename from docs/content/images/interface/toolbar/emoji.png rename to docs/content/old/images/interface/toolbar/emoji.png diff --git a/docs/content/images/interface/toolbar/emphasis.png b/docs/content/old/images/interface/toolbar/emphasis.png similarity index 100% rename from docs/content/images/interface/toolbar/emphasis.png rename to docs/content/old/images/interface/toolbar/emphasis.png diff --git a/docs/content/images/interface/toolbar/large_blocks.png b/docs/content/old/images/interface/toolbar/large_blocks.png similarity index 100% rename from docs/content/images/interface/toolbar/large_blocks.png rename to docs/content/old/images/interface/toolbar/large_blocks.png diff --git a/docs/content/images/interface/toolbar/links.png b/docs/content/old/images/interface/toolbar/links.png similarity index 100% rename from docs/content/images/interface/toolbar/links.png rename to docs/content/old/images/interface/toolbar/links.png diff --git a/docs/content/images/interface/toolbar/table_modal.png b/docs/content/old/images/interface/toolbar/table_modal.png similarity index 100% rename from docs/content/images/interface/toolbar/table_modal.png rename to docs/content/old/images/interface/toolbar/table_modal.png diff --git a/docs/content/images/interface/toolbar/table_overlay.png b/docs/content/old/images/interface/toolbar/table_overlay.png similarity index 100% rename from docs/content/images/interface/toolbar/table_overlay.png rename to docs/content/old/images/interface/toolbar/table_overlay.png diff --git a/docs/content/images/interface/toolbar/whole.png b/docs/content/old/images/interface/toolbar/whole.png similarity index 100% rename from docs/content/images/interface/toolbar/whole.png rename to docs/content/old/images/interface/toolbar/whole.png diff --git a/docs/content/interface/toolbar.md b/docs/content/old/interface/toolbar.md similarity index 100% rename from docs/content/interface/toolbar.md rename to docs/content/old/interface/toolbar.md diff --git a/docs/content/references/config/auth/ldap.md b/docs/content/references/config/auth/ldap.md new file mode 100644 index 000000000..db3da2ae0 --- /dev/null +++ b/docs/content/references/config/auth/ldap.md @@ -0,0 +1,24 @@ +# 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. | +| `HD_AUTH_LDAP_$NAME_SEARCH_BASE` | - | `ou=users,dc=LDAP,dc=example,dc=com` | The LDAP search base which contains the user accounts on the LDAP server. | +| `HD_AUTH_LDAP_$NAME_SEARCH_FILTER` | `(uid={{username}})` | `(&(uid={{username}})(objectClass=inetOrgPerson))` | A LDAP search filter that filters the users that should have access. | +| `HD_AUTH_LDAP_$NAME_SEARCH_ATTRIBUTES` | - | `username,cn` | A comma-seperated list of attributes that the search filter from the LDAP server should access. | +| `HD_AUTH_LDAP_$NAME_USERID_FIELD` | `uid` | `uid`, `uidNumber`, `sAMAccountName` | The attribute of the user account which should be used as an id for the user. | +| `HD_AUTH_LDAP_$NAME_DISPLAY_NAME_FIELD` | `displayName` | `displayName`, `name`, `cn` | The attribute of the user account which should be used as the display name for the user. | +| `HD_AUTH_LDAP_$NAME_PROFILE_PICTURE_FIELD` | `jpegPhoto` | `jpegPhoto`, `thumbnailPhoto` | The attribute of the user account which should be used as the user image for the user. | +| `HD_AUTH_LDAP_$NAME_BIND_DN` | - | `cn=admin,dc=LDAP,dc=example,dc=com` | The dn which is used to perform the user search. If this is omitted then HedgeDoc will use an anonymous bind. | +| `HD_AUTH_LDAP_$NAME_BIND_CREDENTIALS` | - | `MyLdapPassword` | The credential to access the LDAP server. | +| `HD_AUTH_LDAP_$NAME_TLS_CERT_PATHS` | - | `LDAP-ca.pem` | A comma-seperated list of paths to TLS certificates for the LDAP server. diff --git a/docs/content/references/config/auth/local.md b/docs/content/references/config/auth/local.md new file mode 100644 index 000000000..277ca3d2f --- /dev/null +++ b/docs/content/references/config/auth/local.md @@ -0,0 +1,25 @@ +# 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. + +| 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 password score, that passwords need to have. See the table below for more explanations. | + +## Password score + +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 | +| 3 | `safely unguessable` and `very unguessable` passwords are allowed | 100.000.000 | +| 4 | Only `very unguessable` passwords are allowed | 10.000.000.000 | + +[zxcvbn-ts-score]: https://zxcvbn-ts.github.io/zxcvbn/guide/getting-started/#output diff --git a/docs/content/references/config/customization.md b/docs/content/references/config/customization.md new file mode 100644 index 000000000..fe662ec56 --- /dev/null +++ b/docs/content/references/config/customization.md @@ -0,0 +1,53 @@ +# 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. + +| 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 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: +![The demo logo][demo-logo] + +![The demo logo on the Frontpage][logo-front-page] +*logo used on the front page* + +![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` + +![The name on the Frontpage][name-front-page] +*name used on the front page* + +![The name in the editor (light)][name-editor-light] +![The name in the editor (dark)][name-editor-dark] +*name used in the editor* + +[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/references/config/database.md b/docs/content/references/config/database.md new file mode 100644 index 000000000..85a0cf629 --- /dev/null +++ b/docs/content/references/config/database.md @@ -0,0 +1,18 @@ +# Database + +We officially support and test these databases: + +- SQLite (for development and smaller instances) +- 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`.* | + diff --git a/docs/content/references/config/general.md b/docs/content/references/config/general.md new file mode 100644 index 000000000..0ee74b8f1 --- /dev/null +++ b/docs/content/references/config/general.md @@ -0,0 +1,14 @@ +# 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. | +| `HD_RENDERER_BASE_URL` | Content of HD_BASE_URL | | The URL the renderer runs on. If omitted this will be the same as `HD_BASE_URL`. For more detail see [this faq entry][faq-entry] | +| `HD_LOGLEVEL` | warn | | The loglevel that should be used. Options are `error`, `warn`, `info`, `debug` or `trace`. | +| `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_PERSIST_INTERVAL` | 10 | `0`, `5`, `10`, `20` | The time interval in **minutes** for the periodic note revision creation during realtime editing. `0` deactivates the periodic note revision creation. | + +[faq-entry]: /faq/#why-should-i-want-to-run-my-renderer-on-a-different-sub-domain diff --git a/docs/content/references/config/index.md b/docs/content/references/config/index.md new file mode 100644 index 000000000..6f7f8d1ff --- /dev/null +++ b/docs/content/references/config/index.md @@ -0,0 +1,29 @@ +# Configuration + +HedgeDoc can be configured via environment variables either directly or via an `.env` file. + +## The `.env` file + +The `.env` file should be in the working directory of the backend and contains key-value pairs of +environment variables and their corresponding value. +In the official Docker container this is `/usr/src/app/backend/` +This can for example look like this: + + +```ini +HD_BASE_URL="http://localhost:8080" +HD_SESSION_SECRET="change_me_in_production" +HD_DATABASE_TYPE="sqlite" +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. + +!!! warning + The minimal configuration provided in `.env.example` is exactly that: minimal. + It will let you start HedgeDoc for local development, + but it is **not** meant to be used in production without prior changes. diff --git a/docs/content/references/config/integrations.md b/docs/content/references/config/integrations.md new file mode 100644 index 000000000..972351ffe --- /dev/null +++ b/docs/content/references/config/integrations.md @@ -0,0 +1,6 @@ +# Integrations + +| 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 | diff --git a/docs/content/config/media/azure.md b/docs/content/references/config/media/azure.md similarity index 99% rename from docs/content/config/media/azure.md rename to docs/content/references/config/media/azure.md index e4667cd0c..8db8cc2f4 100644 --- a/docs/content/config/media/azure.md +++ b/docs/content/references/config/media/azure.md @@ -9,7 +9,7 @@ It's possible to create the container with the [Azure CLI][azure-cli], using you with the following command: -```sh +```shell az storage container create --name --public-access blob--connection-string "" ``` diff --git a/docs/content/config/media/filesystem.md b/docs/content/references/config/media/filesystem.md similarity index 100% rename from docs/content/config/media/filesystem.md rename to docs/content/references/config/media/filesystem.md diff --git a/docs/content/config/media/imgur.md b/docs/content/references/config/media/imgur.md similarity index 100% rename from docs/content/config/media/imgur.md rename to docs/content/references/config/media/imgur.md diff --git a/docs/content/config/media/s3.md b/docs/content/references/config/media/s3.md similarity index 93% rename from docs/content/config/media/s3.md rename to docs/content/references/config/media/s3.md index d44132c98..7c0008377 100644 --- a/docs/content/config/media/s3.md +++ b/docs/content/references/config/media/s3.md @@ -27,4 +27,4 @@ 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) +[amazon-region]: https://docs.aws.amazon.com/general/latest/gr/s3.html diff --git a/docs/content/config/media/webdav.md b/docs/content/references/config/media/webdav.md similarity index 100% rename from docs/content/config/media/webdav.md rename to docs/content/references/config/media/webdav.md diff --git a/docs/content/references/config/notes.md b/docs/content/references/config/notes.md new file mode 100644 index 000000000..439d9b406 --- /dev/null +++ b/docs/content/references/config/notes.md @@ -0,0 +1,9 @@ +# 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. | +| `HD_PERMISSION_DEFAULT_LOGGED_IN` | `write` | `none`, `read`, `write` | The default permission for the "logged-in" group that is set on new notes. | +| `HD_PERMISSION_DEFAULT_EVERYONE` | `read` | `none`, `read`, `write` | The default permission for the "everyone" group (logged-in & guest users), that is set on new notes created by logged-in users. Notes created by guests always set this to "write". | diff --git a/docs/content/references/hfm.md b/docs/content/references/hfm.md index 46d4dc472..6b4bf8998 100644 --- a/docs/content/references/hfm.md +++ b/docs/content/references/hfm.md @@ -1,7 +1,7 @@ # HedgeDoc Flavored Markdown HedgeDoc has its own markdown dialect which supports many features from [CommonMark][commonmark] -and [Github Flavored Markdown][gfm]. It also adds some new extensions and is missing some. +and [GitHub Flavored Markdown][gfm]. It also adds some new extensions and is missing some. These tables tell you what exactly we support in HedgeDoc 1.x (HFM 1) and HedgeDoc 2 (HFM 2). diff --git a/docs/content/references/index.md b/docs/content/references/index.md new file mode 100644 index 000000000..a18e7365b --- /dev/null +++ b/docs/content/references/index.md @@ -0,0 +1,21 @@ +# References + +References are details to lookup in a non-guided way. +These include for example configuration options or API methods. + + +
+ +
+ โœ + HedgeDoc Flavoured Markdown +
+ + +
+ ๐Ÿ›  + Configuration +
+ +
+ diff --git a/docs/content/setup/getting_started.md b/docs/content/setup/getting_started.md deleted file mode 100644 index f673e6272..000000000 --- a/docs/content/setup/getting_started.md +++ /dev/null @@ -1,40 +0,0 @@ -# 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. - -## 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 . -You will have to accept the TLS warning in your browser the first time the page is opened. - -## Production setup - -!!! 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 - instance for testing with your friends. - -For a production setup, first set a unique session secret with -`sed -i "s/change_me_in_production/$(pwgen -s 64)/" .env`. - -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). -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_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/ diff --git a/docs/content/theme/styles/hedgedoc-custom.css b/docs/content/theme/styles/hedgedoc-custom.css index 6938713e2..881f12d55 100644 --- a/docs/content/theme/styles/hedgedoc-custom.css +++ b/docs/content/theme/styles/hedgedoc-custom.css @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file) + * SPDX-FileCopyrightText: 2023 The HedgeDoc developers (see AUTHORS file) * * SPDX-License-Identifier: AGPL-3.0-only */ @@ -69,3 +69,39 @@ [data-md-color-scheme="light"] .dark-mode-only { display: none; } + +.topic-container { + display: grid; + grid-template-columns: repeat(2, 1fr); + grid-template-rows: 1fr; + gap: 2em; +} + +@media screen and (max-width: 900px) { + .topic-container { + grid-template-columns: repeat(1, 1fr); + } +} + +.topic-container a[href] { + color: var(--md-accent-bg-color--light); +} + +.topic-container a[href]:hover, .topic a[href]:focus, .topic a[href]:active { + color: #fff; +} + +.topic { + width: 100%; + font-size: 28px; + padding: 2em 1em; + display: flex; + gap: 0.5em; + align-items: center; + justify-content: center; + background-color: var(--md-primary-fg-color); +} + +.topic span { + text-align: center; +} diff --git a/docs/content/tutorials/first-note.md b/docs/content/tutorials/first-note.md new file mode 100644 index 000000000..b9cdeb81c --- /dev/null +++ b/docs/content/tutorials/first-note.md @@ -0,0 +1,52 @@ +# Create your first note + +We'll assume the domain you use for the instance is , so please +substitute your actual domain anywhere you encounter + +1. Go to . + +2. Click on the "New Note" button in the top right. HedgeDoc will now create a new + note for you and redirect you to the editor of this note. + + ![New Note button on the HedgeDoc start page][new-note]{ width="400" } + +3. Start typing your note. On the left (1) you find the editor to do so and + on the right (2) you see the rendering of what you wrote. + + ![The HedgeDoc Editor][editor] + +4. Copy the following text into your editor + +```markdown +# My first note + +You can format text **bold** or *italic*. + +There are lists both + +1. ordered + +and + +- unordered + +Also you can use + +- [ ] ToDo Lists +``` + +![The HedgeDoc Editor with the example text][editor-filled] + +## Further reading + +- [Checkout HedgeDoc's markdown syntax reference][hfm] +- [Creating your first presentation][tutorials/first-presentation] +- [Advanced configuration options][config] + +[new-note]: ../images/tutorial/top-right.png +[editor]: ../images/tutorial/note/editor.png +[editor-filled]: ../images/tutorial/note/editor-filled.png + +[hfm]: /references/hfm/ +[tutorials/first-presentation]: /tutorials/first-presentation/ +[config]: /references/config/ diff --git a/docs/content/tutorials/first-presentation.md b/docs/content/tutorials/first-presentation.md new file mode 100644 index 000000000..034b54f45 --- /dev/null +++ b/docs/content/tutorials/first-presentation.md @@ -0,0 +1,5 @@ +# Create your first presentation + +TODO: This pages is still missing some content. +See this issue for more information and if you want to contribute: + diff --git a/docs/content/tutorials/index.md b/docs/content/tutorials/index.md new file mode 100644 index 000000000..340c8e35d --- /dev/null +++ b/docs/content/tutorials/index.md @@ -0,0 +1,33 @@ +# Tutorials + +Tutorials are detailed step-by-step instructions. Start here if you're new to HedgeDoc, +want to create your first presentation or want to build a simple API application. + + +
+ +
+ ๐Ÿš€ + Install HedgeDoc +
+ + +
+ ๐Ÿ™Ž + Create a user +
+ + +
+ ๐Ÿ“ + Create your first note +
+ + +
+ ๐Ÿ“ฝ + Create your first presentation +
+ +
+ \ No newline at end of file diff --git a/docs/content/tutorials/setup.md b/docs/content/tutorials/setup.md new file mode 100644 index 000000000..9528588f9 --- /dev/null +++ b/docs/content/tutorials/setup.md @@ -0,0 +1,82 @@ +# Setup + +After completing this tutorial you'll have your own HedgeDoc instance running. +We will use [Docker][docker-docs] to accomplish this. + + + +1. Open the terminal of the machine you want to install HedgeDoc on. + +2. Check if you have Docker installed by running `docker --version`. + The response should contain some version number greater than `20.10.13`. + - If not please refer to [the Docker install guide][docker-install] to install Docker. + +3. Create a new directory for your HedgeDoc instance: `mkdir -p /opt/hedgedoc`. + +4. Change into the directory with `cd /opt/hedgedoc`. + +5. Download these files: + - `curl -o .env https://docs.hedgedoc.dev/files/setup-docker/config.env` + - `curl -o Caddyfile https://docs.hedgedoc.dev/files/setup-docker/Caddyfile` + - `curl -o docker-compose.yml https://docs.hedgedoc.dev/files/setup-docker/docker-compose.yml` + +6. Open the file `.env` in the editor of your choice (for example with `nano`) and edit the + following variables: + - `HD_BASE_URL`: This should contain the full url you intend to run HedgeDoc on (e.g. for the + demo this would be `https://demo.hedgedoc.org`). If you just want to run HedgeDoc on your + local machine for now `https://hedgedoc.localhost` should be sufficient for testing. + - `HD_SESSION_SECRET`: This should contain a long and random secret for your login sessions. + You can generate it with `pwgen -s 64` or any other way you see fit. + - `HD_DATABASE_PASS`: This should contain a strong password than `password` for your database. + You can again use `pwgen -s 64` to generate it. + +7. Start the Docker containers by running `docker compose up -d`. + +8. Navigate your browser to the url you chose in step 6. Your instance is now ready to use. + + + +You can now play around with your HedgeDoc instance and read about next steps +as either [a new user](#for-users) or [an admin](#for-admins). + +## Next Steps + +### For Users + +- [Creating a user account][tutorials/user] +- [Creating your first note][tutorials/first-note] +- [Creating your first presentation][tutorials/first-presentation] + +### For admins + +- [How to use a reverse proxy][reverse-proxying] +- [How to back up HedgeDoc][backups] +- [How to use other authentication methods][auth-methods] +- [Advanced configuration options][config] + +## Troubleshooting + +### Port already used + +```text +Error response from daemon: driver failed programming external connectivity: Bind for 0.0.0.0:80 +failed: port is already allocated. +``` + +If you see this error, it means there is already something running on your machine that uses +port `80` or `443`. The easiest fix for this is to stop the other application. +If you want to run multiple applications on that port on your server you may want to read our guide +about [reverse proxying][reverse-proxying]. + +[docker-docs]: https://docs.docker.com/ +[docker-install]: https://docs.docker.com/engine/install/ + +[tutorials/user]: /tutorials/user/ +[tutorials/first-note]: /tutorials/first-note/ +[tutorials/first-presentation]: /tutorials/first-presentation/ + +[reverse-proxying]: /how-to/reverse-proxy/ +[backups]: /how-to/backup/ +[auth-methods]: /how-to/auth/ + +[config]: /references/config/ diff --git a/docs/content/tutorials/user.md b/docs/content/tutorials/user.md new file mode 100644 index 000000000..ccdcd5b9b --- /dev/null +++ b/docs/content/tutorials/user.md @@ -0,0 +1,41 @@ +# Create a user + +This tutorial assumes that you just deployed a HedgeDoc instance with [this guide][setup]. +We'll assume the domain you use for the instance is , so please +substitute your actual domain anywhere you encounter + +1. Go to . + +2. Click the "Sign In" button in the top right corner of the page. + + ![Sign In button on the HedgeDoc start page][sign-in]{ width="400" } + +3. Click on the "Register" button in "Sign in via Username" section. + + ![Register button in Sign in via Username section][register-button]{ width="500" } + +4. Fill out the form. + + You are able to change any of these values except the username, so please chose a username + you want to keep. + ![Register form][register-form]{ width="500" } + +5. Click on the "Register" button. + +Congratulation you know have a working local user account for your HedgeDoc instance. + +## Further reading + +- [Creating your first note][tutorials/first-note] +- [Creating your first presentation][tutorials/first-presentation] +- [Advanced configuration options][config] + +[setup]: ./setup.md + +[sign-in]: ../images/tutorial/top-right.png +[register-button]: ../images/tutorial/user/register-button.png +[register-form]: ../images/tutorial/user/register-form.png + +[tutorials/first-note]: /tutorials/first-note/ +[tutorials/first-presentation]: /tutorials/first-presentation/ +[config]: /references/config/ diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b7e961486..ed4c765a9 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,45 +1,66 @@ site_name: HedgeDoc 2 -site_url: https://docs.hedgedoc.org +site_url: https://docs.hedgedoc.dev repo_url: https://github.com/hedgedoc/hedgedoc -site_description: 'HedgeDoc Documentation' +site_description: 'HedgeDoc 2 Documentation' site_author: 'HedgeDoc Developers' docs_dir: content -edit_uri: https://github.com/hedgedoc/hedgedoc/edit/master/docs/content/ +edit_uri: https://github.com/hedgedoc/hedgedoc/edit/develop/docs/content/ nav: - Home: index.md - - Installation: - - Getting Started: setup/getting_started.md - - Configuration: - - Configuration: config/index.md - - Media: - - Azure: config/media/azure.md - - Filesystem: config/media/filesystem.md - - imgur: config/media/imgur.md - - S3: config/media/s3.md - - WebDAV: config/media/webdav.md - - Interface: - - Toolbar: interface/toolbar.md + - Tutorials: + - Overview: tutorials/index.md + - Setup: tutorials/setup.md + - 'Create a user': tutorials/user.md + - 'Create a note': tutorials/first-note.md + - 'Create a presentation': tutorials/first-presentation.md + - 'How-to guides': + - Overview: how-to/index.md + - 'Reverse Proxy': how-to/reverse-proxy.md + - Backup: how-to/backup.md + - Authentication: how-to/auth.md + - Database: how-to/database.md + - Develop: + - Setup: how-to/develop/setup.md + - 'Frontend setup': how-to/develop/frontend.md + - 'Build docker images': how-to/develop/docker.md + - 'Build Documentation': how-to/develop/documentation.md + - 'LDAP test environment': how-to/develop/auth/ldap.md + - 'Core concepts': + - Overview: concepts/index.md + - Notes: concepts/notes.md + - 'User Profiles': concepts/user-profiles.md + - Config: concepts/config.md + - 'API Auth': concepts/api-auth.md + - Events: concepts/events.md - References: - - 'HedgeDoc Flavored Markdown': references/hfm.md - - Development: - - Getting Started: dev/getting-started.md - - Frontend: dev/setup/frontend.md - - Development Notes: dev/dev_notes.md - - Docker: dev/docker.md - - Writing Docs: dev/documentation.md - - Design Documents: - - API Authentication: dev/design_docs/api_auth.md - - Configuration: dev/design_docs/config.md - - Events: dev/design_docs/events.md - - Notes: dev/design_docs/notes.md - - 'User Profiles & Authentication': dev/design_docs/user_profiles.md - - FAQ: https://hedgedoc.org/faq + - Overview: references/index.md + - 'HFM Syntax': references/hfm.md + - Configuration: + - Overview: references/config/index.md + - General: references/config/general.md + - Notes: references/config/notes.md + - Database: references/config/database.md + - Authentication: + - 'Local accounts': references/config/auth/local.md + - LDAP: references/config/auth/ldap.md + - Customization: references/config/customization.md + - Media Backends: + - Azure: references/config/media/azure.md + - Filesystem: references/config/media/filesystem.md + - imgur: references/config/media/imgur.md + - S3: references/config/media/s3.md + - WebDAV: references/config/media/webdav.md + - Integrations: references/config/integrations.md + - FAQ: faq/index.md markdown_extensions: - toc: permalink: true - admonition + - pymdownx.details + - pymdownx.superfences - attr_list - footnotes + - mdx_truly_sane_lists theme: name: 'material' language: en diff --git a/docs/netlify.toml b/docs/netlify.toml new file mode 100644 index 000000000..5a59aa9f3 --- /dev/null +++ b/docs/netlify.toml @@ -0,0 +1,3 @@ +[build] +publish = "site" +command = "echo Pseudo build command because the build is made by the CI" diff --git a/docs/requirements.txt b/docs/requirements.txt index 314b03f70..79b49ffe8 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ mkdocs==1.5.2 mkdocs-material==9.3.1 pymdown-extensions==10.3 +mdx_truly_sane_lists==1.3