docs: restructure

.env.example

@@ -1,7 +1,3 @@
-# SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
-#
-# SPDX-License-Identifier: CC0-1.0
-
 # General settings
 HD_BASE_URL="http://localhost:8080"
 HD_SESSION_SECRET="session_secret"

.github/workflows/test-and-build.yml

@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [ '20' ] # Are you changing this? Don't forget to update the min. and recommended node version in docs/content/how-to/develop/setup.md!
+        node: [ '20' ] # Are you changing this? Don't forget to update the min. and recommended node version in docs/content/development/guides/setup.md!
         include:
           - node: '20'
             coverage: true

README.md

@@ -36,7 +36,7 @@ We are currently working on HedgeDoc 2, a complete rewrite of HedgeDoc. Please n
 - HedgeDoc 2 will be split in two components. The backend and the frontend. Both are present in this repository.
 
 ## Development
-Information for setting up a local development environment can be found in the [developer documentation](https://docs.hedgedoc.dev/how-to/develop/setup/)
+Information for setting up a local development environment can be found in the [developer documentation](https://docs.hedgedoc.dev/development/guides/setup/)
 
 ## HedgeDoc 2 Alpha
 Curious about the new look and feel of HedgeDoc 2? We provide a demo of the alpha on [hedgedoc.dev](https://hedgedoc.dev).

backend/docker/Dockerfile

@@ -56,7 +56,7 @@ FROM base as prod
 LABEL org.opencontainers.image.title='HedgeDoc production backend image'
 LABEL org.opencontainers.image.url='https://hedgedoc.org'
 LABEL org.opencontainers.image.source='https://github.com/hedgedoc/hedgedoc'
-LABEL org.opencontainers.image.documentation='https://github.com/hedgedoc/hedgedoc/blob/develop/docs/content/how-to/develop/docker.md'
+LABEL org.opencontainers.image.documentation='https://github.com/hedgedoc/hedgedoc/blob/develop/docs/content/development/guides/docker.md'
 LABEL org.opencontainers.image.licenses='AGPL-3.0'
 
 USER node

docker/.env

@@ -1,6 +1,6 @@
 # General settings
-HD_BASE_URL="https://hedgedoc2.localhost"
+HD_BASE_URL="https://hedgedoc.localhost"
-HD_SESSION_SECRET="change_me_in_production"
+HD_SESSION_SECRET="replace_this"
 
 # Database settings
 HD_DATABASE_TYPE="postgres"
@@ -8,7 +8,7 @@ HD_DATABASE_HOST="db"
 HD_DATABASE_PORT="5432"
 HD_DATABASE_NAME="hedgedoc"
 HD_DATABASE_USER="hedgedoc"
-HD_DATABASE_PASS="password"
+HD_DATABASE_PASS="replace_this"
 
 # Uploads
 HD_MEDIA_BACKEND="filesystem"

docker/Caddyfile

@@ -1,20 +1,15 @@
-#
+{$HD_BASE_URL} {
-# SPDX-FileCopyrightText: 2023 The HedgeDoc developers (see AUTHORS file)
-#
-# SPDX-License-Identifier: AGPL-3.0-only
-#
 
-{$HD_BASE_URL}
+    log {
+        output stdout
+        level WARN
+        format console
+    }
 
-log {
+    reverse_proxy /realtime http://backend:{$HD_BACKEND_PORT:3000}
-	output stdout
+    reverse_proxy /api/* http://backend:{$HD_BACKEND_PORT:3000}
-	level WARN
+    reverse_proxy /public/* http://backend:{$HD_BACKEND_PORT:3000}
-	format console
+    reverse_proxy /uploads/* http://backend:{$HD_BACKEND_PORT:3000}
+    reverse_proxy /media/* http://backend:{$HD_BACKEND_PORT:3000}
+    reverse_proxy /* http://frontend:{$HD_FRONTEND_PORT:3001}
 }
-
-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

docker/Caddyfile.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2024 The HedgeDoc developers (see AUTHORS file)
+
+SPDX-License-Identifier: AGPL-3.0-only

docker/docker-compose.yml

@@ -1,24 +1,24 @@
-# SPDX-FileCopyrightText: 2023 The HedgeDoc developers (see AUTHORS file)
-# SPDX-License-Identifier: AGPL-3.0-only
----
 services:
   backend:
-    image: ghcr.io/hedgedoc/hedgedoc/backend:develop
+    image: ghcr.io/hedgedoc/hedgedoc/backend:2.0.0-alpha.3
     volumes:
       - $PWD/.env:/usr/src/app/backend/.env
       - hedgedoc_uploads:/usr/src/app/backend/uploads
 
   frontend:
-    image: ghcr.io/hedgedoc/hedgedoc/frontend:develop
+    image: ghcr.io/hedgedoc/hedgedoc/frontend:2.0.0-alpha.3
     environment:
       HD_BASE_URL: "${HD_BASE_URL}"
+      HD_INTERNAL_API_URL: http://backend:3000
 
   db:
-    image: postgres:15
+    image: postgres:16
     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
@@ -34,5 +34,6 @@ services:
       - caddy_data:/data
 
 volumes:
-  hedgedoc_uploads:
   caddy_data:
+  hedgedoc_uploads:
+  hedgedoc_postgres:

docs/content/development/concepts/index.md

@@ -5,37 +5,37 @@ background information and explanations. They are especially useful for contribu
 
 <!-- markdownlint-disable no-inline-html -->
 <div class='topic-container'>
-    <a href='/concepts/notes/'>
+    <a href='/development/concepts/notes/'>
         <div class='topic'>
             <span>📝</span>
             <span>Notes</span>
         </div>
     </a>
-    <a href='/concepts/media/'>
+    <a href='/development/concepts/media/'>
         <div class='topic'>
             <span>📸</span>
             <span>Media</span>
         </div>
     </a>
-    <a href='/concepts/user-profiles/'>
+    <a href='/development/concepts/user-profiles/'>
         <div class='topic'>
             <span>🙎</span>
             <span>User Profiles</span>
         </div>
     </a>
-    <a href='/concepts/config/'>
+    <a href='/development/concepts/config/'>
         <div class='topic'>
             <span>🛠️</span>
             <span>Config</span>
         </div>
     </a>
-    <a href='/concepts/api-auth/'>
+    <a href='/development/concepts/api-auth/'>
         <div class='topic'>
             <span>🤖️</span>
             <span>API Auth</span>
         </div>
     </a>
-    <a href='/concepts/events/'>
+    <a href='/development/concepts/events/'>
         <div class='topic'>
             <span>🎩</span>
             <span>Events</span>

docs/content/development/guides/setup.md

@@ -163,5 +163,5 @@ set `CADDY_HOST` to your domain (for example `CADDY_HOST=http://my-hedgedoc.home
 [hedgedoc-repo]: https://github.com/hedgedoc/hedgedoc
 [yarn]: https://yarnpkg.com/getting-started/install
 [caddy]: https://caddyserver.com/
-[config-docs]: ../../references/config/index.md
+[config-docs]: ../../config/index.md
 [frontend-setup]: ./frontend.md

docs/content/files/setup-docker/Caddyfile

@@ -1,14 +0,0 @@
-{$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 /media/* http://backend:3000
-reverse_proxy /* http://frontend:3001

docs/content/files/setup-docker/config.env

@@ -1,19 +0,0 @@
-# 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"

docs/content/files/setup-docker/docker-compose.yml

@@ -1,39 +0,0 @@
-services:
-  backend:
-    image: ghcr.io/hedgedoc/hedgedoc/backend:2.0.0-alpha.3
-    volumes:
-      - $PWD/.env:/usr/src/app/backend/.env
-      - hedgedoc_uploads:/usr/src/app/backend/uploads
-
-  frontend:
-    image: ghcr.io/hedgedoc/hedgedoc/frontend:2.0.0-alpha.3
-    environment:
-      HD_BASE_URL: "${HD_BASE_URL}"
-      HD_INTERNAL_API_URL: http://backend:3000
-
-  db:
-    image: postgres:16
-    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:

docs/content/getting-started/explore.md

@@ -1,4 +1,4 @@
-# Use the explore page
+# Explore notes
 
 TODO: This pages is still missing some content.
 See this issue for more information and if you want to contribute:

docs/content/getting-started/first-note.md

@@ -0,0 +1,152 @@
+# Create your first note
+
+We assume that you followed the previous tutorials for setting up an instance of HedgeDoc
+and created an user account.
+We assume the domain you use for the instance is <https://hedgedoc.localhost>, so please
+substitute it with your actual domain anywhere you encounter <https://hedgedoc.localhost>
+if that differs.
+
+## Creating a new note
+
+1. Go to <https://hedgedoc.localhost> and log in. You should now be on the "explore page" within the
+   "My notes" section.
+
+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 in the top right of the page][new-note]{ width="400" }
+
+3. You are now in the editor, the main component of HedgeDoc. Let's explore the different parts of
+it now.
+
+## The editor
+
+![Editor view with different sections numbered and highlighted in color][editor]{ width="700" }
+
+1. **Editor pane:** You will write your note contents here on the left side.
+   Notes are written in Markdown syntax.
+2. **Renderer pane:** The renderer pane on the right contains the rendered output from the markdown
+   on the left side.
+3. **View mode selection:** You can choose if you want to see only the editor pane, only the
+   renderer pane or both panes (the default). This setting will be remembered for future visits.
+4. **Pane split resizer:** Use the little arrow handle in the middle to resize the split between
+   editor pane and renderer pane by dragging it to the left or right.
+   You can always reset the split by clicking the middle *view mode selector (3)*.
+5. **Editor toolbar:** The toolbar contains buttons to quickly insert markdown fragments into the
+   editor at your current cursor position. It has buttons to upload an image or opening an
+   emoji-picker too.
+6. **Editor statusbar:** The statusbar contains information about the current cursor position,
+   selection and the note length.
+7. **Sidebar:** The sidebar contains all the important functionality to manage your note.
+   There's for example the list of currently online people, the permission management, the
+   possibility of importing or exporting the note content, and much more.
+
+## Writing markdown
+
+Start by writing a few things in the editor pane on the left side.
+You will see the same content in the renderer pane on the right side.
+
+Markdown uses a few characters to control how the output looks. One of them is the hashtag (#).
+When written at the beginning of a line, the following text is treated as a heading.
+
+There are several more such control characters, so just copy the example below into the editor,
+to get a first gist about them:
+
+```markdown
+# A heading
+
+## Another heading, but one level more nested
+
+Some **bold**, *italic*, and ~~strokethrough~~ text.
+
+- A bullet point list
+- ... which can be ...
+   - nested as well
+      - into multiple levels.
+
+1. There are ...
+2. numbered lists too.
+
+[This is a link](https://www.example.com).
+And this is a picture: ![Some image description](https://picsum.photos/600/400).
+```
+
+The result should look like this:
+
+![Editor with the example from above][editor-text]{ width="700" }
+
+You might have seen that the title in the middle of the top bar now says "A heading" instead of
+"Untitled". If not specified otherwise, the first heading of your note is used as the title of
+the note.
+
+There's a whole lot more of things you can add to your note, from to-do lists, tables, flowcharts,
+to UML diagrams or simple sheet music. To discover the syntax for all these things, please refer
+to the *Cheatsheet*. It can be opened from the "Help menu", which opens when clicking the little
+button with the question mark at the top right.
+
+## Collaborate on the note
+
+You might have seen that the URL now looks like this:
+`https://hedgedoc.localhost/n/a2gra3bsstrjjy5w0dk2k1q3y0`.
+
+Each new note receives an unique identifier, that is added to the URL.
+You can share this URL with other people to work collaboratively with them.
+Changes done by one user are applied in realtime to all other users as well.
+There's no limit on how many users can participate on a note.
+
+By default, users that also have an account on your instance have write access, while non-logged-in
+users only have read access.
+You can manage these permissions on a more granular basis, see the
+[section about permissions](#setting-permissions) below.
+
+When another user with write access joins your note, you see their cursor too.
+Each person has another color, so it is easier to distinguish between multiple ones.
+
+![Screenshot of the editor with another person's cursor][collaboration]{ width="700" }
+
+If you click the little icon with the persons in the sidebar, you get a list of the users which are
+currently working alongside you in the note. A little indicator circle next to the name shows
+whether the user currently has the editor focused (green) or not (red). This way you can quickly see
+who's actively writing in the moment.
+
+## Setting permissions
+
+By clicking the little lock icon in the sidebar, you open the permissions management dialog.
+This allows you to configure who has access to your note, and especially who has write access and
+who only read access.
+
+![Screenshot of the permissions management dialog][permissions]{ width="400" }
+
+You can also transfer your note ownership to another user, if you like.
+The owner of a note, is the only one who can change the permissions or delete the note.
+
+You can add other users by entering their username into the field "Add user" and submit through the
+plus-icon button. If a username does not exist, you'll see an error notification appearing in the
+top right of the app.
+
+There are two special kinds of permission that you can set below the individual user permissions.
+The entry "All logged-in users" refers - as the name says - to the group of registered user accounts
+on the instance. This becomes useful, if you have a known group of users on your instance and
+registration disabled.
+The other entry "Everyone" means that this permission is applied to everyone who accesses the note
+by its URL. This means the URL should be treated like a secret in case of (write) access.
+
+
+## Working with images
+
+## Adding frontmatter metadata
+
+## Further reading
+
+- [Checkout HedgeDoc's markdown syntax reference][hfm]
+- [Creating your first presentation][getting-started/first-presentation]
+- [Advanced configuration options][config]
+
+[new-note]: ../images/tutorial/app-bar.png
+[editor]: ../images/tutorial/note/editor.png
+[editor-text]: ../images/tutorial/note/editor-text.png
+[collaboration]: ../images/tutorial/note/collaboration.png
+[permissions]: ../images/tutorial/note/permissions.png
+
+[hfm]: ../references/hfm.md
+[getting-started/first-presentation]: first-presentation.md
+[config]: ../config/index.md

docs/content/getting-started/index.md

@@ -1,29 +1,36 @@
-# Tutorials
+# Getting started
 
-Tutorials are detailed step-by-step instructions. Start here if you're new to HedgeDoc,
+These tutorials are detailed step-by-step instructions.
-want to create your first presentation or want to build a simple API application.
+Start here to learn how to create your first note or presentation, how to manage your
+notes or even how to setup your own instance.
 
 <!-- markdownlint-disable no-inline-html -->
 <div class='topic-container'>
-    <a href='/tutorials/setup/'>
+    <a href='/getting-started/setup/'>
         <div class='topic'>
             <span>🚀</span>
             <span>Install HedgeDoc</span>
         </div>
     </a>
-    <a href='/tutorials/user/'>
+    <a href='/getting-started/user/'>
         <div class='topic'>
             <span>🙎</span>
             <span>Create a user</span>
         </div>
     </a>
-    <a href='/tutorials/first-note/'>
+    <a href='/getting-started/first-note/'>
         <div class='topic'>
             <span>📝</span>
             <span>Create your first note</span>
         </div>
     </a>
-    <a href='/tutorials/first-presentation/'>
+    <a href='/getting-started/explore/'>
+        <div class='topic'>
+            <span>🔭</span>
+            <span>Explore notes</span>
+        </div>
+    </a>
+    <a href='/getting-started/first-presentation/'>
         <div class='topic'>
             <span>📽</span>
             <span>Create your first presentation</span>

docs/content/getting-started/setup.md

@@ -0,0 +1,135 @@
+# Install HedgeDoc
+
+After completing this tutorial you'll have your own HedgeDoc instance running.
+We will use [Docker][docker-docs] to accomplish this.
+
+!!! warning "HedgeDoc 2 is currently in alpha"
+    Alpha releases come with no guarantees regarding upgradeability.
+    It is very likely that you will need to wipe the database between alpha releases.  
+    Please set up a separate instance to test HedgeDoc 2, there is currently no migration path
+    from HedgeDoc 1.
+
+<!-- markdownlint-disable proper-names -->
+<!-- markdownlint-disable line-length -->
+
+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 you don't have Docker installed or if the version is too old, 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://raw.githubusercontent.com/hedgedoc/hedgedoc/refs/heads/develop/docker/.env`
+   - `curl -o Caddyfile https://raw.githubusercontent.com/hedgedoc/hedgedoc/refs/heads/develop/docker/Caddyfile`
+   - `curl -o docker-compose.yml https://raw.githubusercontent.com/hedgedoc/hedgedoc/refs/heads/develop/docker/docker-compose.yml`
+     <!-- TODO: Create short links for these URLs, for example at source.hedgedoc.org/docker/Caddyfile etc. -->
+
+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 1` or any other way you see fit.
+     If you don't have `pwgen` installed you can also use this command which should work
+     out of the box: `tr -dc A-Za-z0-9 < /dev/urandom | head -c 64`
+   - `HD_DATABASE_PASS`: This should contain a stronger password than `password` for your database.
+     You can again use `pwgen -s 64 1` or a similar command to generate it.
+
+7. Start the Docker containers by running `docker compose up -d`. This command will start four docker
+   containers: The HedgeDoc frontend, the HedgeDoc backend, a PostgreSQL database and the Caddy reverse-proxy.
+
+8. Navigate your browser to the url you chose in step 6. Your instance is now ready to use.
+
+<!-- markdownlint-disable no-space-in-code -->
+
+!!! info Using a different port
+    This tutorial assumes that you run your HedgeDoc 2 instance on port 80 and 443 (HTTP and HTTPS).
+    If you want to use a custom port, be sure to update your `.env` file to include the port in the
+    `HD_BASE_URL` variable as well as update the port bindings in the `docker-compose.yml` file.  
+    For example, when using the base URL `http://192.168.1.100:8080`, only use the following ports
+    section for the `proxy` service:
+    ```yaml
+    ports:
+      - "8080:8080"
+    ```
+
+<!-- markdownlint-enable no-space-in-code -->
+<!-- markdownlint-enable line-length -->
+<!-- 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][getting-started/user]
+- [Creating your first note][getting-started/first-note]
+- [Explore notes][getting-started/explore]
+- [Creating your first presentation][getting-started/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. You can use the
+command `ss -tulpn` to see which application utilizes which port.
+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].
+
+### Instance unreachable
+
+You followed the guide to set up your instance, but when trying to access it in the browser, you
+receive an error like `ERR_CONNECTION_REFUSED`.
+
+First, check that the Docker containers are running. For this you can use the command
+`docker compose ps -a`. If some of them are not running, check the logs and look out for error
+messages. You can use `docker compose logs` for this.
+
+In case the containers are running but you still can't reach HedgeDoc in the browser, verify that
+the content of the variable `HD_BASE_URL` in the `.env` file matches exactly the URL you are trying
+to open. Verify that the ports (`80` or `443` or a custom one) are correctly mapped in the
+`docker-compose.yml`.
+
+### Connection insecure
+
+When accessing the HedgeDoc instance in your browser, you receive a warning that the HTTPS
+certificate is not trustworthy. This is the case, if you use a URL ending in `.localhost`.
+Caddy creates a temporary HTTPS certificate which is not signed by any public CA. You can
+safely ignore and bypass this error. See [the Caddy docs on HTTPS][caddy-https] for more
+information.
+
+[docker-docs]: https://docs.docker.com/
+[docker-install]: https://docs.docker.com/engine/install/
+
+[getting-started/user]: user.md
+[getting-started/first-note]: first-note.md
+[getting-started/first-presentation]: first-presentation.md
+[getting-started/explore]: explore.md
+
+[reverse-proxying]: ../guides/reverse-proxy.md
+[backups]: ../guides/backup.md
+[auth-methods]: ../guides/auth.md
+
+[config]: ../config/index.md
+[caddy-https]: https://caddyserver.com/docs/automatic-https

docs/content/getting-started/user.md

@@ -0,0 +1,50 @@
+# Create an user account
+
+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://hedgedoc.localhost>, so please
+substitute it with your actual domain anywhere you encounter <https://hedgedoc.localhost> if
+that differs.
+
+1. Go to <https://hedgedoc.localhost>. You will be greeted by the login page.
+
+   ![HedgeDoc login page][login-page]{ width="700" }
+
+2. Click on the "Register" button in "Sign in via Username" section.
+
+3. Choose your preferred username, display name and password.
+
+   You are able to change any of these values except the username, so choose a username
+   you want to keep. The username needs to be lowercase and may only contain the letters a-z,
+   the numbers 0-9, and the underscore (_), dot (.) and hyphen (-).
+   ![Register form][register-form]{ width="400" }
+
+4. Click on the "Register" button.
+
+If everything worked, you'll now get redirected to the "explore page", which is the start
+page for accessing your notes. A notification in the top right confirms your account creation.
+
+![Notification confirming the successful account creation][success-notification]{ width="400" }
+
+HedgeDoc stores your login for 14 days in your browser per default. You can configure this
+session duration via the config options. Of course, you can always log out of your account
+to clear the session.
+
+The next time you need to log in, just use your chosen username and password.
+
+## Further reading
+
+- [Creating your first note][getting-started/first-note]
+- [Learn about the explore page][getting-started/explore]
+- [Creating your first presentation][getting-started/first-presentation]
+- [Advanced configuration options][config]
+
+[setup]: ./setup.md
+
+[login-page]: ../images/tutorial/user/login-page.png
+[register-form]: ../images/tutorial/user/register-form.png
+[success-notification]: ../images/tutorial/user/notification-success.png
+
+[getting-started/first-note]: first-note.md
+[getting-started/first-presentation]: first-presentation.md
+[getting-started/explore]: explore.md
+[config]: ../config/index.md

docs/content/guides/index.md

@@ -6,25 +6,25 @@ 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/'>
+    <a href='/guides/reverse-proxy/'>
         <div class='topic'>
             <span>↩️️</span>
             <span>Configure a reverse proxy</span>
         </div>
     </a>
-    <a href='/how-to/backup/'>
+    <a href='/guides/backup/'>
         <div class='topic'>
             <span>💾</span>
             <span>Back up your instance</span>
         </div>
     </a>
-    <a href='/how-to/auth/'>
+    <a href='/guides/auth/'>
         <div class='topic'>
             <span>🔑</span>
             <span>Customize authentication</span>
         </div>
     </a>
-    <a href='/how-to/database/'>
+    <a href='/guides/database/'>
         <div class='topic'>
             <span>🗄</span>
             <span>Use another database</span>

docs/content/index.md

@@ -19,9 +19,9 @@ that you can host yourself.
 <!-- markdownlint-disable proper-names -->
 <!-- TODO: HedgeDoc Tour Video https://github.com/hedgedoc/hedgedoc/issues/4828 -->
 <!-- markdownlint-enable proper-names -->
-- 🦔 New to HedgeDoc? Take the [HedgeDoc tour][hedgedoc-tour]
+- 🦔 New to HedgeDoc? Watch the [HedgeDoc tour video][hedgedoc-tour].
-- 🚀 Want your own instance? [Install HedgeDoc yourself][install-guide]
+- 🚀 Want your own instance? [Install HedgeDoc yourself][install-guide].
-- 🛠️ Want to change something about HedgeDoc? Read the [Configuration reference][config-reference]
+- 🛠️ Want to change something about HedgeDoc? Read the [Configuration reference][config-reference].
 
 ## Getting help
 
@@ -37,42 +37,47 @@ Having trouble? We’d like to help!
 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
+- **[Getting started][tutorials]:** This section contains tutorials for people who are new to
-  HedgeDoc, want to create your first presentation or want to build a simple API application.
+  HedgeDoc. Start here to learn how to create your first note or presentation, how to manage your
-- **[How-to guides][how-to]** target the more advanced users and guide them through a variety of
+  notes or even how to setup your own instance.
-  topics, addressing non-trivial use-cases. They are more advanced than tutorials and assume some
+- **[How-to guides][how-to]:** This section targets the more advanced users. It guides you through 
-  knowledge of HedgeDoc.
+  a variety of topics, addressing non-trivial use-cases. The guides are more advanced than tutorials
-- **[Core concepts][core-concepts]** explain the internal structure of HedgeDoc by providing
+  and assume some knowledge of HedgeDoc.
-  background information and explanations. They are especially useful for contributing to HedgeDoc.
+- **[Configuration][config-reference]:** All configuration options are explained in this section.
-- **[References][references]** are details to lookup in a non-guided way. These include for example
+  Use it as a reference when setting up your own instance or explore the possibilities what can be
-  configuration options or API methods.
+  configured.
+- **[Development][development]:** This section contains explanations of the core concepts behind
+  the architecture of HedgeDoc as well as guides to set up the development environment for
+  ontributing to the codebase. Use this section as a starting point if you intend to contribute
+  code-wise to HedgeDoc.
+- **[References][references]:** This section contains information that is useful to look up in a
+  non-guided way. This includes for example the supported Markdown features or the API endpoints.
 
 ## 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].
+- Improve the translation of HedgeDoc into your language at our [translation tool][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
+- Read the [development section][development] of the docs to setup your local dev environment and
-  your own features.
+  start implementing your own features.
 
 [![Deployed using netlify](https://www.netlify.com/img/global/badges/netlify-color-accent.svg)
 ](https://www.netlify.com)
 
 [hedgedoc-tour]: https://tour.hedgedoc.org
-[install-guide]: tutorials/setup.md
+[install-guide]: getting-started/setup.md
-[config-reference]: references/config/index.md
+[config-reference]: config/index.md
 
 [faq]: faq/index.md
 [community-forum]: https://community.hedgedoc.org/
 [chat]: https://chat.hedgedoc.org
 [issue-tracker]: https://github.com/hedgedoc/hedgedoc/issues/new/choose
 
-[tutorials]: tutorials/index.md
+[tutorials]: getting-started/index.md
-[how-to]: how-to/index.md
+[how-to]: guides/index.md
-[core-concepts]: concepts/index.md
+[development]: development/index.md
 [references]: references/index.md
 
 [weblate]: https://translate.hedgedoc.org
-[how-to-dev]: how-to/develop/setup.md

docs/content/references/api.md

@@ -0,0 +1,5 @@
+# API
+
+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>

docs/content/references/index.md

@@ -11,7 +11,7 @@ These include for example configuration options or API methods.
             <span>HedgeDoc Flavoured Markdown</span>
         </div>
     </a>
-    <a href='/references/config/'>
+    <a href='/config/'>
         <div class='topic'>
             <span>🛠</span>
             <span>Configuration</span>

docs/content/tutorials/first-note.md

@@ -1,52 +0,0 @@
-# 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.md
-[tutorials/first-presentation]: first-presentation.md
-[config]: ../references/config/index.md

docs/content/tutorials/setup.md

@@ -1,102 +0,0 @@
-# Setup
-
-After completing this tutorial you'll have your own HedgeDoc instance running.
-We will use [Docker][docker-docs] to accomplish this.
-
-!!! warning "HedgeDoc 2 is currently in alpha"
-    Alpha releases come with no guarantees regarding upgradeability.
-    It is very likely that you will need to wipe the database between alpha releases.  
-    Please set up a separate instance to test HedgeDoc 2, there is currently no migration path
-    from HedgeDoc 1.
-
-<!-- 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-disable no-space-in-code -->
-
-!!! info Using a different port
-    This tutorial assumes that you run your HedgeDoc 2 instance on port 80 and 443 (HTTP and HTTPS).
-    If you want to use a custom port, be sure to update your `.env` file to include the port in the
-    `HD_BASE_URL` variable as well as update the port bindings in the `docker-compose.yml` file.  
-    For example, when using the base URL `http://localhost:8080`, only use the following ports
-    section for the `proxy` service:
-    ```yaml
-    ports:
-      - "8080:8080"
-    ```
-
-<!-- markdownlint-enable no-space-in-code -->
-<!-- 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]: user.md
-[tutorials/first-note]: first-note.md
-[tutorials/first-presentation]: first-presentation.md
-
-[reverse-proxying]: ../how-to/reverse-proxy.md
-[backups]: ../how-to/backup.md
-[auth-methods]: ../how-to/auth.md
-
-[config]: ../references/config/index.md

docs/content/tutorials/user.md

@@ -1,41 +0,0 @@
-# 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]: first-note.md
-[tutorials/first-presentation]: first-presentation.md
-[config]: ../references/config/index.md

docs/mkdocs.yml

@@ -7,52 +7,56 @@ docs_dir: content
 edit_uri: https://github.com/hedgedoc/hedgedoc/edit/develop/docs/content/
 nav:
   - Home: index.md
-  - Tutorials:
+  - 'Getting started':
-    - Overview: tutorials/index.md
+    - Overview: getting-started/index.md
-    - Setup: tutorials/setup.md
+    - 'Install HedgeDoc': getting-started/setup.md
-    - 'Create a user': tutorials/user.md
+    - 'Create a user': getting-started/user.md
-    - 'Create a note': tutorials/first-note.md
+    - 'Create a note': getting-started/first-note.md
-    - 'Create a presentation': tutorials/first-presentation.md
+    - 'Explore notes': getting-started/explore.md
+    - 'Create a presentation': getting-started/first-presentation.md
   - 'How-to guides':
-    - Overview: how-to/index.md
+    - Overview: guides/index.md
-    - 'Reverse Proxy': how-to/reverse-proxy.md
+    - 'Reverse Proxy': guides/reverse-proxy.md
-    - Backup: how-to/backup.md
+    - Backup: guides/backup.md
-    - Authentication: how-to/auth.md
+    - Authentication: guides/auth.md
-    - Database: how-to/database.md
+    - Database: guides/database.md
-    - Develop:
+  - 'Configuration':
-      - Setup: how-to/develop/setup.md
+    - Overview: config/index.md
-      - 'Frontend setup': how-to/develop/frontend.md
+    - General: config/general.md
-      - 'Build docker images': how-to/develop/docker.md
+    - Notes: config/notes.md
-      - 'Build Documentation': how-to/develop/documentation.md
+    - Database: config/database.md
-      - 'LDAP test environment': how-to/develop/auth/ldap.md
+    - Authentication:
-  - 'Core concepts':
+      - Overview: config/auth/index.md
-    - Overview: concepts/index.md
+      - 'Local accounts': config/auth/local.md
-    - Notes: concepts/notes.md
+      - LDAP: config/auth/ldap.md
-    - 'User Profiles': concepts/user-profiles.md
+      - 'OpenID Connect (OIDC)': config/auth/oidc.md
-    - Config: concepts/config.md
+    - Customization: config/customization.md
-    - 'API Auth': concepts/api-auth.md
+    - Media Backends:
-    - Events: concepts/events.md
+      - Azure: config/media/azure.md
+      - Filesystem: config/media/filesystem.md
+      - imgur: config/media/imgur.md
+      - S3: config/media/s3.md
+      - WebDAV: config/media/webdav.md
+    - Integrations: config/integrations.md
+  - Development:
+    - Overview: development/index.md
+    - Guides:
+      - Setup: development/guides/setup.md
+      - 'Frontend setup': development/guides/frontend.md
+      - 'Build docker images': development/guides/docker.md
+      - 'Build Documentation': development/guides/documentation.md
+      - 'LDAP test environment': development/guides/auth/ldap.md
+    - Concepts:
+      - Overview: development/concepts/index.md
+      - Notes: development/concepts/notes.md
+      - 'User Profiles': development/concepts/user-profiles.md
+      - Config: development/concepts/config.md
+      - 'API Auth': development/concepts/api-auth.md
+      - Events: development/concepts/events.md
   - References:
       - Overview: references/index.md
       - 'HFM Syntax': references/hfm.md
-      - Configuration:
+      - API: references/api.md
-        - Overview: references/config/index.md
-        - General: references/config/general.md
-        - Notes: references/config/notes.md
-        - Database: references/config/database.md
-        - Authentication:
-          - Overview: references/config/auth/index.md
-          - 'Local accounts': references/config/auth/local.md
-          - LDAP: references/config/auth/ldap.md
-          - 'OpenID Connect (OIDC)': references/config/auth/oidc.md
-        - Customization: references/config/customization.md
-        - Media Backends:
-          - Azure: references/config/media/azure.md
-          - Filesystem: references/config/media/filesystem.md
-          - imgur: references/config/media/imgur.md
-          - S3: references/config/media/s3.md
-          - WebDAV: references/config/media/webdav.md
-        - Integrations: references/config/integrations.md
   - FAQ: faq/index.md
 markdown_extensions:
   - toc:

frontend/docker/Dockerfile

@@ -36,7 +36,7 @@ ENV NEXT_TELEMETRY_DISABLED=1
 LABEL org.opencontainers.image.title='HedgeDoc production frontend image'
 LABEL org.opencontainers.image.url='https://hedgedoc.org'
 LABEL org.opencontainers.image.source='https://github.com/hedgedoc/hedgedoc'
-LABEL org.opencontainers.image.documentation='https://github.com/hedgedoc/hedgedoc/blob/develop/docs/content/how-to/develop/docker.md'
+LABEL org.opencontainers.image.documentation='https://github.com/hedgedoc/hedgedoc/blob/develop/docs/content/development/guides/docker.md'
 LABEL org.opencontainers.image.licenses='AGPL-3.0'
 
 WORKDIR /usr/src/app