mirror of
https://github.com/hedgedoc/hedgedoc.git
synced 2025-05-29 22:35:50 -04:00
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
Tilman Vatteroth
parent
e0dd24ed29
commit
e07cd62596
68 changed files with 1163 additions and 315 deletions
.github/workflows
.reuse
docs
.markdownlint.jsonmkdocs.ymlnetlify.tomlrequirements.txt
.netlify
content
concepts
config
faq
files/setup-docker
how-to
images/tutorial
index.mdold
dev
images/interface/toolbar
interface
references
setup
theme/styles
tutorials
55
.github/workflows/docs-netlify-deploy.yml
vendored
Normal file
55
.github/workflows/docs-netlify-deploy.yml
vendored
Normal 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 }}\""
|
||||||
24
.reuse/dep5
24
.reuse/dep5
|
|
@ -35,11 +35,11 @@ Files: docs/**/*.png
|
||||||
Copyright: 2021 The HedgeDoc developers (see AUTHORS file)
|
Copyright: 2021 The HedgeDoc developers (see AUTHORS file)
|
||||||
License: CC-BY-SA-4.0
|
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)
|
Copyright: 2021 The HedgeDoc developers (see AUTHORS file)
|
||||||
License: CC-BY-SA-4.0
|
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)
|
Copyright: 2021 The HedgeDoc developers (see AUTHORS file)
|
||||||
License: CC-BY-SA-4.0
|
License: CC-BY-SA-4.0
|
||||||
|
|
||||||
|
|
@ -55,6 +55,26 @@ Files: docs/content/theme/styles/Roboto/*
|
||||||
Copyright: 2011 Christian Robertson
|
Copyright: 2011 Christian Robertson
|
||||||
License: Apache-2.0
|
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
|
Files: backend/public/*.md
|
||||||
Copyright: 2021 The HedgeDoc developers (see AUTHORS file)
|
Copyright: 2021 The HedgeDoc developers (see AUTHORS file)
|
||||||
License: CC0-1.0
|
License: CC0-1.0
|
||||||
|
|
|
||||||
|
|
@ -25,7 +25,7 @@
|
||||||
"style": "---"
|
"style": "---"
|
||||||
},
|
},
|
||||||
"MD044": {
|
"MD044": {
|
||||||
"names": ["HedgeDoc"]
|
"names": ["HedgeDoc", "Docker"]
|
||||||
},
|
},
|
||||||
"MD046": {
|
"MD046": {
|
||||||
"style": "fenced"
|
"style": "fenced"
|
||||||
|
|
|
||||||
3
docs/.netlify/state.json
Normal file
3
docs/.netlify/state.json
Normal file
|
|
@ -0,0 +1,3 @@
|
||||||
|
{
|
||||||
|
"siteId": "3cb86ea9-e257-40f3-ab9c-7b9eb08423c4"
|
||||||
|
}
|
||||||
|
|
@ -1,8 +1,8 @@
|
||||||
# API Authentication
|
# API Authentication
|
||||||
|
|
||||||
!!! info "Design Document"
|
!!! info "Design Document"
|
||||||
This is a design document, explaining the design and vision for a HedgeDoc 2
|
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.
|
feature. It is not a user guide and may or may not be fully implemented.
|
||||||
|
|
||||||
## Public API
|
## Public API
|
||||||
|
|
||||||
39
docs/content/concepts/index.md
Normal file
39
docs/content/concepts/index.md
Normal 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 -->
|
||||||
|
|
@ -88,9 +88,9 @@ In this case, the frontend should show the use a notice that they should contact
|
||||||
to resolve the issue.
|
to resolve the issue.
|
||||||
|
|
||||||
!!! warning
|
!!! warning
|
||||||
Admins must ensure that usernames are unique across all auth providers set as a global sync source.
|
Admins must ensure that usernames are unique across all auth providers set as a global sync
|
||||||
Otherwise, if e.g. in both LDAPs configured as sync source a user `johndoe` exists,
|
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.
|
only the first that logs in can use HedgeDoc.
|
||||||
|
|
||||||
#### Local sync sources
|
#### Local sync sources
|
||||||
|
|
||||||
|
|
@ -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
99
docs/content/faq/index.md
Normal 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
|
||||||
14
docs/content/files/setup-docker/Caddyfile
Normal file
14
docs/content/files/setup-docker/Caddyfile
Normal 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
|
||||||
19
docs/content/files/setup-docker/config.env
Normal file
19
docs/content/files/setup-docker/config.env
Normal 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"
|
||||||
38
docs/content/files/setup-docker/docker-compose.yml
Normal file
38
docs/content/files/setup-docker/docker-compose.yml
Normal 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:
|
||||||
5
docs/content/how-to/auth.md
Normal file
5
docs/content/how-to/auth.md
Normal 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>
|
||||||
5
docs/content/how-to/backup.md
Normal file
5
docs/content/how-to/backup.md
Normal 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>
|
||||||
5
docs/content/how-to/database.md
Normal file
5
docs/content/how-to/database.md
Normal 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>
|
||||||
|
|
@ -1,15 +1,17 @@
|
||||||
# LDAP
|
# LDAP
|
||||||
|
|
||||||
LDAP authentication can be tested with the [`test-openldap`][docker-image]
|
If you are developing HedgeDoc and need to test something with an LDAP server you can use the
|
||||||
docker image from [rroemhild][rroemhild].
|
[`test-openldap`][docker-image] Docker image from [rroemhild][rroemhild].
|
||||||
|
|
||||||
Simply run
|
Simply run
|
||||||
|
|
||||||
```sh
|
<!-- markdownlint-disable proper-names -->
|
||||||
|
```shell
|
||||||
docker run --rm -p 10389:10389 -p 10636:10636 rroemhild/test-openldap
|
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
|
```dotenv
|
||||||
HD_AUTH_LDAP_SERVERS="FUTURAMA"
|
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"
|
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`
|
- `professor` : `professor`
|
||||||
- `fry` : `fry`
|
- `fry` : `fry`
|
||||||
|
|
@ -33,5 +35,8 @@ You should then be able to log in with either of these logins (`username` : `pas
|
||||||
- `bender` : `bender`
|
- `bender` : `bender`
|
||||||
- `amy` : `amy`
|
- `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
|
[docker-image]: https://github.com/rroemhild/docker-test-openldap
|
||||||
[rroemhild]: https://github.com/rroemhild
|
[rroemhild]: https://github.com/rroemhild
|
||||||
|
|
@ -1,12 +1,12 @@
|
||||||
# Building Docker images
|
# 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
|
Make sure that you have installed the [Docker BuildKit Plugin][buildkit] and
|
||||||
execute the commands from the root level of the project.
|
execute the commands from the root level of the project.
|
||||||
Otherwise, the build process may fail.
|
Otherwise, the build process may fail.
|
||||||
|
|
||||||
<!-- markdownlint-disable proper-names -->
|
<!-- markdownlint-disable proper-names -->
|
||||||
```sh
|
```shell
|
||||||
docker buildx build -f backend/docker/Dockerfile -t hedgedoc-backend .
|
docker buildx build -f backend/docker/Dockerfile -t hedgedoc-backend .
|
||||||
```
|
```
|
||||||
<!-- markdownlint-enable proper-names -->
|
<!-- markdownlint-enable proper-names -->
|
||||||
|
|
@ -14,7 +14,7 @@ docker buildx build -f backend/docker/Dockerfile -t hedgedoc-backend .
|
||||||
or
|
or
|
||||||
|
|
||||||
<!-- markdownlint-disable proper-names -->
|
<!-- markdownlint-disable proper-names -->
|
||||||
```sh
|
```shell
|
||||||
docker buildx build -f frontend/docker/Dockerfile -t hedgedoc-frontend .
|
docker buildx build -f frontend/docker/Dockerfile -t hedgedoc-frontend .
|
||||||
```
|
```
|
||||||
<!-- markdownlint-enable proper-names -->
|
<!-- markdownlint-enable proper-names -->
|
||||||
|
|
@ -1,14 +1,16 @@
|
||||||
# Documentation
|
# 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
|
## Writing
|
||||||
|
|
||||||
All documentation files are found in the `docs/content` directory of
|
|
||||||
<!-- markdownlint-disable proper-names -->
|
<!-- 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
|
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.
|
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 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.
|
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:
|
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.
|
2. Go into the `docs` folder.
|
||||||
3. Install all the dependencies (E.g. with a [venv](https://docs.python.org/3/library/venv.html))
|
3. Install all the dependencies (E.g. with a [venv](https://docs.python.org/3/library/venv.html))
|
||||||
with `pip install -r requirements.txt`
|
with `pip install -r requirements.txt`
|
||||||
4. Start the mkdocs dev server (`mkdocs serve`) or build the documentation (`mkdocs build`).
|
4. Start the mkdocs dev server (`mkdocs serve`) or build the documentation (`mkdocs build`).
|
||||||
|
|
||||||
|
If you run `mkdcs serve` a local server will serve the mkdocs files and change the served files as
|
||||||
|
you write documentation.
|
||||||
|
|
||||||
## Deployment
|
## Deployment
|
||||||
|
|
||||||
The documentation is deployed with [mkdocs][mkdocs].
|
The documentation is deployed with [mkdocs][mkdocs].
|
||||||
|
|
||||||
<!-- markdownlint-disable proper-names -->
|
<!-- markdownlint-disable proper-names -->
|
||||||
The repository [docs.hedgedoc.org][docs.hedgedoc.org] is used to deploy the actual website
|
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.
|
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
|
[mkdocs]: https://www.mkdocs.org
|
||||||
|
[python3]: https://www.python.org/
|
||||||
[docs.hedgedoc.org]: https://github.com/hedgedoc/docs.hedgedoc.org
|
[docs.hedgedoc.org]: https://github.com/hedgedoc/docs.hedgedoc.org
|
||||||
|
|
@ -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_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. |
|
| 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.
|
after compilation. You shouldn't need to set them yourself. Use the designated npm tasks instead.
|
||||||
|
|
||||||
## UI Test
|
## UI Test
|
||||||
|
|
@ -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.
|
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.
|
follow the description below.
|
||||||
To run HedgeDoc 2.0 you need three components: the backend, the frontend and the reverse proxy.
|
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
|
The reverse proxy can be chosen by preference. For development, we recommend caddy
|
||||||
and the provided configuration.
|
and the provided configuration.
|
||||||
|
|
||||||
|
|
@ -81,7 +81,7 @@ For development, we recommend creating an `.env` file.
|
||||||
|
|
||||||
## Build the `commons` package
|
## 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.
|
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.
|
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
|
[hedgedoc-repo]: https://github.com/hedgedoc/hedgedoc
|
||||||
[yarn]: https://yarnpkg.com/getting-started/install
|
[yarn]: https://yarnpkg.com/getting-started/install
|
||||||
[caddy]: https://caddyserver.com/
|
[caddy]: https://caddyserver.com/
|
||||||
[config-docs]: ../config/index.md
|
[config-docs]: /references/config/
|
||||||
[frontend-setup]: ./setup/frontend.md
|
[frontend-setup]: ./frontend.md
|
||||||
34
docs/content/how-to/index.md
Normal file
34
docs/content/how-to/index.md
Normal 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 -->
|
||||||
217
docs/content/how-to/reverse-proxy.md
Normal file
217
docs/content/how-to/reverse-proxy.md
Normal 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/
|
||||||
BIN
docs/content/images/tutorial/note/editor-filled.png
Normal file
BIN
docs/content/images/tutorial/note/editor-filled.png
Normal file
Binary file not shown.
|
After 
(image error) Size: 157 KiB |
BIN
docs/content/images/tutorial/note/editor.png
Normal file
BIN
docs/content/images/tutorial/note/editor.png
Normal file
Binary file not shown.
|
After 
(image error) Size: 126 KiB |
BIN
docs/content/images/tutorial/top-right.png
Normal file
BIN
docs/content/images/tutorial/top-right.png
Normal file
Binary file not shown.
|
After 
(image error) Size: 8.9 KiB |
BIN
docs/content/images/tutorial/user/register-button.png
Normal file
BIN
docs/content/images/tutorial/user/register-button.png
Normal file
Binary file not shown.
|
After 
(image error) Size: 21 KiB |
BIN
docs/content/images/tutorial/user/register-form.png
Normal file
BIN
docs/content/images/tutorial/user/register-form.png
Normal file
Binary file not shown.
|
After 
(image error) Size: 73 KiB |
|
|
@ -1,16 +1,75 @@
|
||||||
# Welcome to the HedgeDoc 2 Documentation
|
# Welcome to the HedgeDoc 2 Documentation
|
||||||
|
|
||||||
<!-- markdownlint-disable no-inline-html line-length -->
|
<!-- 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" width="398" height="100" 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="dark-mode-only" src="images/hedgedoc_logo_white.svg">
|
||||||
<!-- markdownlint-enable no-inline-html line-length -->
|
<!-- markdownlint-enable no-inline-html line-length -->
|
||||||
|
|
||||||
🚧⚠️🚧 **HedgeDoc 2.0 is still in development!**
|
!!! danger "🚧⚠️🚧 **HedgeDoc 2.0 is still in development!**"
|
||||||
You are probably looking for the 1.x docs.
|
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 -->
|
<!-- 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 -->
|
<!-- 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? 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/
|
||||||
|
|
|
||||||
|
Before 
(image error) Size: 6.8 KiB After 
(image error) Size: 6.8 KiB
|
|
Before 
(image error) Size: 111 KiB After 
(image error) Size: 111 KiB
|
|
Before 
(image error) Size: 7.8 KiB After 
(image error) Size: 7.8 KiB
|
|
Before 
(image error) Size: 5.7 KiB After 
(image error) Size: 5.7 KiB
|
|
Before 
(image error) Size: 4.2 KiB After 
(image error) Size: 4.2 KiB
|
|
Before 
(image error) Size: 25 KiB After 
(image error) Size: 25 KiB
|
|
Before 
(image error) Size: 10 KiB After 
(image error) Size: 10 KiB
|
|
Before 
(image error) Size: 18 KiB After 
(image error) Size: 18 KiB
|
24
docs/content/references/config/auth/ldap.md
Normal file
24
docs/content/references/config/auth/ldap.md
Normal 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.
|
||||||
25
docs/content/references/config/auth/local.md
Normal file
25
docs/content/references/config/auth/local.md
Normal 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
|
||||||
53
docs/content/references/config/customization.md
Normal file
53
docs/content/references/config/customization.md
Normal 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
|
||||||
18
docs/content/references/config/database.md
Normal file
18
docs/content/references/config/database.md
Normal 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 -->
|
||||||
14
docs/content/references/config/general.md
Normal file
14
docs/content/references/config/general.md
Normal 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
|
||||||
29
docs/content/references/config/index.md
Normal file
29
docs/content/references/config/index.md
Normal 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.
|
||||||
6
docs/content/references/config/integrations.md
Normal file
6
docs/content/references/config/integrations.md
Normal 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 |
|
||||||
|
|
@ -9,7 +9,7 @@ It's possible to create the container with the [Azure CLI][azure-cli], using you
|
||||||
with the following command:
|
with the following command:
|
||||||
|
|
||||||
<!-- markdownlint-disable line-length -->
|
<!-- markdownlint-disable line-length -->
|
||||||
```sh
|
```shell
|
||||||
az storage container create --name <NAME> --public-access blob--connection-string "<CONNECTION_STRING>"
|
az storage container create --name <NAME> --public-access blob--connection-string "<CONNECTION_STRING>"
|
||||||
```
|
```
|
||||||
<!-- markdownlint-enable line-length -->
|
<!-- markdownlint-enable line-length -->
|
||||||
|
|
@ -27,4 +27,4 @@ should be `https://s3.us-east-2.amazonaws.com`.
|
||||||
[s3]: https://aws.amazon.com/s3/
|
[s3]: https://aws.amazon.com/s3/
|
||||||
[minIO]: https://min.io
|
[minIO]: https://min.io
|
||||||
[ceph]: https://docs.ceph.com/en/latest/radosgw/
|
[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
|
||||||
9
docs/content/references/config/notes.md
Normal file
9
docs/content/references/config/notes.md
Normal 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". |
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
# HedgeDoc Flavored Markdown
|
# HedgeDoc Flavored Markdown
|
||||||
|
|
||||||
HedgeDoc has its own markdown dialect which supports many features from [CommonMark][commonmark]
|
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).
|
These tables tell you what exactly we support in HedgeDoc 1.x (HFM 1) and HedgeDoc 2 (HFM 2).
|
||||||
|
|
||||||
|
|
|
||||||
21
docs/content/references/index.md
Normal file
21
docs/content/references/index.md
Normal 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 -->
|
||||||
|
|
@ -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/
|
|
||||||
|
|
@ -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
|
* SPDX-License-Identifier: AGPL-3.0-only
|
||||||
*/
|
*/
|
||||||
|
|
@ -69,3 +69,39 @@
|
||||||
[data-md-color-scheme="light"] .dark-mode-only {
|
[data-md-color-scheme="light"] .dark-mode-only {
|
||||||
display: none;
|
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;
|
||||||
|
}
|
||||||
|
|
|
||||||
52
docs/content/tutorials/first-note.md
Normal file
52
docs/content/tutorials/first-note.md
Normal 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/
|
||||||
5
docs/content/tutorials/first-presentation.md
Normal file
5
docs/content/tutorials/first-presentation.md
Normal 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>
|
||||||
33
docs/content/tutorials/index.md
Normal file
33
docs/content/tutorials/index.md
Normal 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 -->
|
||||||
82
docs/content/tutorials/setup.md
Normal file
82
docs/content/tutorials/setup.md
Normal 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/
|
||||||
41
docs/content/tutorials/user.md
Normal file
41
docs/content/tutorials/user.md
Normal 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/
|
||||||
|
|
@ -1,45 +1,66 @@
|
||||||
site_name: HedgeDoc 2
|
site_name: HedgeDoc 2
|
||||||
site_url: https://docs.hedgedoc.org
|
site_url: https://docs.hedgedoc.dev
|
||||||
repo_url: https://github.com/hedgedoc/hedgedoc
|
repo_url: https://github.com/hedgedoc/hedgedoc
|
||||||
site_description: 'HedgeDoc Documentation'
|
site_description: 'HedgeDoc 2 Documentation'
|
||||||
site_author: 'HedgeDoc Developers'
|
site_author: 'HedgeDoc Developers'
|
||||||
docs_dir: content
|
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:
|
nav:
|
||||||
- Home: index.md
|
- Home: index.md
|
||||||
- Installation:
|
- Tutorials:
|
||||||
- Getting Started: setup/getting_started.md
|
- Overview: tutorials/index.md
|
||||||
- Configuration:
|
- Setup: tutorials/setup.md
|
||||||
- Configuration: config/index.md
|
- 'Create a user': tutorials/user.md
|
||||||
- Media:
|
- 'Create a note': tutorials/first-note.md
|
||||||
- Azure: config/media/azure.md
|
- 'Create a presentation': tutorials/first-presentation.md
|
||||||
- Filesystem: config/media/filesystem.md
|
- 'How-to guides':
|
||||||
- imgur: config/media/imgur.md
|
- Overview: how-to/index.md
|
||||||
- S3: config/media/s3.md
|
- 'Reverse Proxy': how-to/reverse-proxy.md
|
||||||
- WebDAV: config/media/webdav.md
|
- Backup: how-to/backup.md
|
||||||
- Interface:
|
- Authentication: how-to/auth.md
|
||||||
- Toolbar: interface/toolbar.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:
|
- References:
|
||||||
- 'HedgeDoc Flavored Markdown': references/hfm.md
|
- Overview: references/index.md
|
||||||
- Development:
|
- 'HFM Syntax': references/hfm.md
|
||||||
- Getting Started: dev/getting-started.md
|
- Configuration:
|
||||||
- Frontend: dev/setup/frontend.md
|
- Overview: references/config/index.md
|
||||||
- Development Notes: dev/dev_notes.md
|
- General: references/config/general.md
|
||||||
- Docker: dev/docker.md
|
- Notes: references/config/notes.md
|
||||||
- Writing Docs: dev/documentation.md
|
- Database: references/config/database.md
|
||||||
- Design Documents:
|
- Authentication:
|
||||||
- API Authentication: dev/design_docs/api_auth.md
|
- 'Local accounts': references/config/auth/local.md
|
||||||
- Configuration: dev/design_docs/config.md
|
- LDAP: references/config/auth/ldap.md
|
||||||
- Events: dev/design_docs/events.md
|
- Customization: references/config/customization.md
|
||||||
- Notes: dev/design_docs/notes.md
|
- Media Backends:
|
||||||
- 'User Profiles & Authentication': dev/design_docs/user_profiles.md
|
- Azure: references/config/media/azure.md
|
||||||
- FAQ: https://hedgedoc.org/faq
|
- 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:
|
markdown_extensions:
|
||||||
- toc:
|
- toc:
|
||||||
permalink: true
|
permalink: true
|
||||||
- admonition
|
- admonition
|
||||||
|
- pymdownx.details
|
||||||
|
- pymdownx.superfences
|
||||||
- attr_list
|
- attr_list
|
||||||
- footnotes
|
- footnotes
|
||||||
|
- mdx_truly_sane_lists
|
||||||
theme:
|
theme:
|
||||||
name: 'material'
|
name: 'material'
|
||||||
language: en
|
language: en
|
||||||
|
|
|
||||||
3
docs/netlify.toml
Normal file
3
docs/netlify.toml
Normal file
|
|
@ -0,0 +1,3 @@
|
||||||
|
[build]
|
||||||
|
publish = "site"
|
||||||
|
command = "echo Pseudo build command because the build is made by the CI"
|
||||||
|
|
@ -1,3 +1,4 @@
|
||||||
mkdocs==1.5.2
|
mkdocs==1.5.2
|
||||||
mkdocs-material==9.3.1
|
mkdocs-material==9.3.1
|
||||||
pymdown-extensions==10.3
|
pymdown-extensions==10.3
|
||||||
|
mdx_truly_sane_lists==1.3
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue