docs: restructure documentation

This rewrite follows the principles of https://diataxis.fr/

Co-authored-by: Erik Michelson <github@erik.michelson.eu>
Signed-off-by: Philip Molares <philip.molares@udo.edu>
Signed-off-by: Erik Michelson <github@erik.michelson.eu>
This commit is contained in:
Philip Molares 2023-07-02 22:31:04 +02:00 committed by Tilman Vatteroth
parent e0dd24ed29
commit e07cd62596
68 changed files with 1163 additions and 315 deletions

View file

@ -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 }}\""

View file

@ -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

View file

@ -25,7 +25,7 @@
"style": "---"
},
"MD044": {
"names": ["HedgeDoc"]
"names": ["HedgeDoc", "Docker"]
},
"MD046": {
"style": "fenced"

3
docs/.netlify/state.json Normal file
View file

@ -0,0 +1,3 @@
{
"siteId": "3cb86ea9-e257-40f3-ab9c-7b9eb08423c4"
}

View file

@ -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

View file

@ -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.
<!-- markdownlint-disable no-inline-html -->
<div class='topic-container'>
<a href='/concepts/notes/'>
<div class='topic'>
<span>📝</span>
<span>Notes</span>
</div>
</a>
<a href='/concepts/user-profiles/'>
<div class='topic'>
<span>🙎</span>
<span>User Profiles</span>
</div>
</a>
<a href='/concepts/config/'>
<div class='topic'>
<span>🛠️</span>
<span>Config</span>
</div>
</a>
<a href='/concepts/api-auth/'>
<div class='topic'>
<span>🤖️</span>
<span>API Auth</span>
</div>
</a>
<a href='/concepts/events/'>
<div class='topic'>
<span>🎩</span>
<span>Events</span>
</div>
</a>
</div>
<!-- markdownlint-enable no-inline-html -->

View file

@ -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

View file

@ -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:
<!-- markdownlint-disable proper-names -->
```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/"
```
<!-- markdownlint-enable proper-names -->
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

99
docs/content/faq/index.md Normal file
View file

@ -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.
<!-- markdownlint-disable no-emphasis-as-heading -->
**Deprecated**
<!-- markdownlint-enable no-emphasis-as-heading -->
```yaml
tags: tag1, tag2
```
<!-- markdownlint-disable no-emphasis-as-heading -->
**New**
<!-- markdownlint-enable no-emphasis-as-heading -->
```yaml
tags:
- tag1
- tag2
```
<!-- markdownlint-disable no-emphasis-as-heading -->
*or*
<!-- markdownlint-enable no-emphasis-as-heading -->
```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

View file

@ -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

View file

@ -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"

View file

@ -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:

View file

@ -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:
<https://github.com/hedgedoc/hedgedoc/issues/4830>

View file

@ -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:
<https://github.com/hedgedoc/hedgedoc/issues/4830>

View file

@ -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:
<https://github.com/hedgedoc/hedgedoc/issues/4830>

View file

@ -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
<!-- markdownlint-disable proper-names -->
```shell
docker run --rm -p 10389:10389 -p 10636:10636 rroemhild/test-openldap
```
<!-- markdownlint-enable proper-names -->
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

View file

@ -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.
<!-- markdownlint-disable proper-names -->
```sh
```shell
docker buildx build -f backend/docker/Dockerfile -t hedgedoc-backend .
```
<!-- markdownlint-enable proper-names -->
@ -14,7 +14,7 @@ docker buildx build -f backend/docker/Dockerfile -t hedgedoc-backend .
or
<!-- markdownlint-disable proper-names -->
```sh
```shell
docker buildx build -f frontend/docker/Dockerfile -t hedgedoc-frontend .
```
<!-- markdownlint-enable proper-names -->

View file

@ -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
<!-- markdownlint-disable proper-names -->
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
<!-- markdownlint-enable proper-names -->
markdown files with nothing special about them.
<!-- markdownlint-enable proper-names -->
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].
<!-- markdownlint-disable proper-names -->
The repository [docs.hedgedoc.org][docs.hedgedoc.org] is used to deploy the actual website
<!-- markdownlint-enable proper-names -->
to github.io. Currently only the `master` branch is deployed as it contains the latest release.
<!-- markdownlint-enable proper-names -->
[mkdocs]: https://www.mkdocs.org
[python3]: https://www.python.org/
[docs.hedgedoc.org]: https://github.com/hedgedoc/docs.hedgedoc.org

View file

@ -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

View file

@ -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

View file

@ -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.
<!-- markdownlint-disable no-inline-html -->
<div class='topic-container'>
<a href='/how-to/reverse-proxy/'>
<div class='topic'>
<span>↩️️</span>
<span>Configure a reverse proxy</span>
</div>
</a>
<a href='/how-to/backup/'>
<div class='topic'>
<span>💾</span>
<span>Back up your instance</span>
</div>
</a>
<a href='/how-to/auth/'>
<div class='topic'>
<span>🔑</span>
<span>Customize authentication</span>
</div>
</a>
<a href='/how-to/database/'>
<div class='topic'>
<span>🗄</span>
<span>Use another database</span>
</div>
</a>
</div>
<!-- markdownlint-enable no-inline-html -->

View file

@ -0,0 +1,217 @@
# How to use a reverse proxy
<!-- markdownlint-disable proper-names -->
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 <https://md.example.com>, so please
substitute your actual domain anywhere you encounter <https://md.example.com>.
## 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`:
<!-- markdownlint-disable line-length no-space-in-code -->
??? 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"
```
<!-- markdownlint-enable line-length no-space-in-code -->
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.
<!-- markdownlint-disable no-space-in-code -->
??? 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"
```
<!-- markdownlint-enable no-space-in-code -->
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].
<!-- markdownlint-disable code-block-style -->
??? 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;
}
```
<!-- markdownlint-disable code-block-style -->
#### Apache
You will need these modules enabled: `proxy`, `proxy_http` and `proxy_wstunnel`.
Here is an example config snippet for [Apache][apache]:
<!-- markdownlint-disable code-block-style -->
??? abstract "Apache config"
```
<VirtualHost *:443>
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
</VirtualHost>
```
<!-- markdownlint-enable code-block-style -->
#### 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 <http://localhost:3000>
- Passing `/api/*` to <http://localhost:3000>
- Passing `/public/*` to <http://localhost:3000>
- Passing `/uploads/*` to <http://localhost:3000>
- Passing `/apidoc/*` to <http://localhost:3000>
- Passing `/*` to <http://localhost:3001>
- 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.
<!-- markdownlint-enable proper-names -->
[traefik]: https://traefik.io/traefik/
[letsencrypt]: https://letsencrypt.org/
[nginx]: https://nginx.org/
[apache]: https://httpd.apache.org/

Binary file not shown.

After

Width:  |  Height:  |  Size: 157 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 126 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 8.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 73 KiB

View file

@ -1,16 +1,75 @@
# Welcome to the HedgeDoc 2 Documentation
<!-- markdownlint-disable no-inline-html line-length -->
<img alt="HedgeDoc Logo" title="HedgeDoc Logo" class="light-mode-only" src="images/hedgedoc_logo_black.svg">
<img alt="HedgeDoc Logo" title="HedgeDoc Logo" class="dark-mode-only" src="images/hedgedoc_logo_white.svg">
<img alt="HedgeDoc Logo" title="HedgeDoc Logo" width="398" height="100" class="light-mode-only" src="images/hedgedoc_logo_black.svg">
<img alt="HedgeDoc Logo" title="HedgeDoc Logo" width="398" height="100" class="dark-mode-only" src="images/hedgedoc_logo_white.svg">
<!-- markdownlint-enable no-inline-html line-length -->
🚧⚠️🚧 **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.
<!-- markdownlint-disable proper-names -->
Find them in the `master` branch and on [docs.hedgedoc.org](https://docs.hedgedoc.org).
<!-- markdownlint-enable proper-names -->
Welcome to the documentation for HedgeDoc, a collaborative online markdown editor,
that you can host yourself.
## Quick start
<!-- markdownlint-disable proper-names -->
Find them in the `master` branch and on [docs.hedgedoc.org](https://docs.hedgedoc.org).
<!-- TODO: HedgeDoc Tour Video https://github.com/hedgedoc/hedgedoc/issues/4828 -->
<!-- markdownlint-enable proper-names -->
- 🦔 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? Wed 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/

View file

Before

Width:  |  Height:  |  Size: 6.8 KiB

After

Width:  |  Height:  |  Size: 6.8 KiB

View file

Before

Width:  |  Height:  |  Size: 111 KiB

After

Width:  |  Height:  |  Size: 111 KiB

View file

Before

Width:  |  Height:  |  Size: 7.8 KiB

After

Width:  |  Height:  |  Size: 7.8 KiB

View file

Before

Width:  |  Height:  |  Size: 5.7 KiB

After

Width:  |  Height:  |  Size: 5.7 KiB

View file

Before

Width:  |  Height:  |  Size: 4.2 KiB

After

Width:  |  Height:  |  Size: 4.2 KiB

View file

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 25 KiB

View file

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 10 KiB

View file

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

View file

@ -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.

View file

@ -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

View file

@ -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

View file

@ -0,0 +1,18 @@
# Database
We officially support and test these databases:
- SQLite (for development and smaller instances)
- PostgreSQL
- MariaDB
<!-- markdownlint-disable proper-names -->
| 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`.* |
<!-- markdownlint-enable proper-names -->

View file

@ -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

View file

@ -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:
<!-- markdownlint-disable proper-names -->
```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/"
```
<!-- markdownlint-enable proper-names -->
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.

View file

@ -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 |

View file

@ -9,7 +9,7 @@ It's possible to create the container with the [Azure CLI][azure-cli], using you
with the following command:
<!-- markdownlint-disable line-length -->
```sh
```shell
az storage container create --name <NAME> --public-access blob--connection-string "<CONNECTION_STRING>"
```
<!-- markdownlint-enable line-length -->

View file

@ -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

View file

@ -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". |

View file

@ -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).

View file

@ -0,0 +1,21 @@
# References
References are details to lookup in a non-guided way.
These include for example configuration options or API methods.
<!-- markdownlint-disable no-inline-html -->
<div class='topic-container'>
<a href='/references/hfm/'>
<div class='topic'>
<span></span>
<span>HedgeDoc Flavoured Markdown</span>
</div>
</a>
<a href='/references/config/'>
<div class='topic'>
<span>🛠</span>
<span>Configuration</span>
</div>
</a>
</div>
<!-- markdownlint-enable no-inline-html -->

View file

@ -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 <https://hedgedoc2.localhost>.
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/

View file

@ -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;
}

View file

@ -0,0 +1,52 @@
# Create your first note
We'll assume the domain you use for the instance is <https://md.example.com>, so please
substitute your actual domain anywhere you encounter <https://md.example.com>
1. Go to <https://md.example.com>.
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/

View file

@ -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:
<https://github.com/hedgedoc/hedgedoc/issues/4830>

View file

@ -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.
<!-- markdownlint-disable no-inline-html -->
<div class='topic-container'>
<a href='/tutorials/setup/'>
<div class='topic'>
<span>🚀</span>
<span>Install HedgeDoc</span>
</div>
</a>
<a href='/tutorials/user/'>
<div class='topic'>
<span>🙎</span>
<span>Create a user</span>
</div>
</a>
<a href='/tutorials/first-note/'>
<div class='topic'>
<span>📝</span>
<span>Create your first note</span>
</div>
</a>
<a href='/tutorials/first-presentation/'>
<div class='topic'>
<span>📽</span>
<span>Create your first presentation</span>
</div>
</a>
</div>
<!-- markdownlint-enable no-inline-html -->

View file

@ -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.
<!-- markdownlint-disable proper-names -->
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.
<!-- markdownlint-enable proper-names -->
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/

View file

@ -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 <https://md.example.com>, so please
substitute your actual domain anywhere you encounter <https://md.example.com>
1. Go to <https://md.example.com>.
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/

View file

@ -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

3
docs/netlify.toml Normal file
View file

@ -0,0 +1,3 @@
[build]
publish = "site"
command = "echo Pseudo build command because the build is made by the CI"

View file

@ -1,3 +1,4 @@
mkdocs==1.5.2
mkdocs-material==9.3.1
pymdown-extensions==10.3
mdx_truly_sane_lists==1.3