### Setup HedgeDoc Dependencies and Configs

Source: https://docs.hedgedoc.org/dev/getting-started

Run this script after cloning to install npm dependencies and create necessary configuration files. Requires Bash.

```bash
bin/setup
```

--------------------------------

### Review Full Configuration

Source: https://docs.hedgedoc.org/guides/minio-image-upload

Example of the combined configuration settings for Minio integration.

```json
{
  // all your other config…
  "minio": {
    "accessKey": "888MXJ7EP4XXXXXXXXX",
    "secretKey": "yQS2EbM1Y6IJrp/1BUKWq2/XXXXXXXXXXXXXXX",
    "endPoint": "localhost",
    "port": 9000,
    "secure": false
  },
  "s3bucket": "hedgedoc",
  "imageuploadtype": "minio"
}
```

--------------------------------

### Redirects File Example

Source: https://docs.hedgedoc.org/guides/migrate-etherpad

An example of the `redirects.txt` file generated by the migration script, mapping original pad names to their new HedgeDoc URLs.

```text
date-ideas -> Found. Redirecting to https://hedgedoc.example.com/mPt0KfiKSBOTQ3mNcdfn
groceries -> Found. Redirecting to https://hedgedoc.example.com/UukqgwLfhYyUUtARlcJ2_y
london -> Found. Redirecting to https://hedgedoc.example.com/_d3wa-BE8t4Swv5w7O2_9R
weddingchecklist -> Found. Redirecting to https://hedgedoc.example.com/XcQGqlBjl0u40wfT0N8TzQ
(...)

```

--------------------------------

### Start HedgeDoc Server Manually

Source: https://docs.hedgedoc.org/setup/manual-setup

Recommended command to start the HedgeDoc server manually in production mode. This helps in observing any potential warnings or errors during startup. For development, NODE_ENV=production can be omitted.

```bash
NODE_ENV=production yarn start

```

--------------------------------

### Start Minio Container

Source: https://docs.hedgedoc.org/guides/minio-image-upload

Run a non-persistent Minio instance for development purposes.

```bash
docker run --name test-minio --rm -d -p 9000:9000 minio/minio server /data
```

--------------------------------

### YAML Metadata Configuration Example

Source: https://docs.hedgedoc.org/dev/release_checklist

Example of YAML front matter for configuring document metadata, including title, description, tags, and display options.

```yaml
---
title: yaml metadata testing
description: This is a test description
tags: features, cool, updated
robots: noindex, nofollow
lang: en-US
dir: rtl
breaks: false
type: slide
slideOptions:
  transition: fade
  theme: white
opengraph:
  title: Special title for OpenGraph protocol
  image: https://dummyimage.com/600x600/000/fff
  image:type: image/png
---
```

--------------------------------

### Run HedgeDoc Server

Source: https://docs.hedgedoc.org/dev/getting-started

Starts the HedgeDoc server. This command is used after the frontend bundle has been built.

```javascript
node app.js
```

--------------------------------

### Restore PostgreSQL Database

Source: https://docs.hedgedoc.org/setup/docker

Commands to restore a database backup before starting the application.

```bash
docker-compose up -d database
cat backup.sql | docker exec -i $(docker-compose ps -q database) psql -U hedgedoc
```

--------------------------------

### Verify Alpine Docker Image Status

Source: https://docs.hedgedoc.org/dev/release_checklist

Example output from `docker ps` showing a healthy Alpine-based HedgeDoc container running.

```bash
hedgedoc-local:1.x.y-alpine                     "/usr/local/bin/dock…"   29 seconds ago   Up 28 seconds (healthy)
```

--------------------------------

### Basic YAML Frontmatter Structure

Source: https://docs.hedgedoc.org/references/yaml-metadata

Insert this structure at the start of your note to enable YAML metadata configuration.

```yaml
---
YAML metas
---
```

--------------------------------

### GET /{note}/download

Source: https://docs.hedgedoc.org/dev/openapi.yml

Returns the raw markdown content of a specified note.

```APIDOC
## GET /{note}/download

### Description
Returns the raw markdown content of a note.

### Method
GET

### Endpoint
/{note}/download

### Path Parameters
- **note** (string) - Required - The note which should be downloaded

### Response
#### Success Response (200)
- **content** (text/markdown) - The raw markdown content of the note

#### Response Example
```text/markdown
# Some heading
```

#### Error Response (404)
- Description: Note does not exist
```

--------------------------------

### Create New Note via API

Source: https://docs.hedgedoc.org/dev/release_checklist

Example of creating a new note using the HedgeDoc API with `curl`. This requires the API to be accessible and the content to be sent as markdown.

```bash
curl -i -d '# hello world' -H "Content-Type: text/markdown" http://localhost:3000/new
```

--------------------------------

### Verify Debian Docker Image Status

Source: https://docs.hedgedoc.org/dev/release_checklist

Example output from `docker ps` showing a healthy Debian-based HedgeDoc container running.

```bash
hedgedoc-local:1.x.y-debian                     "/usr/local/bin/dock…"   29 seconds ago   Up 28 seconds (healthy)
```

--------------------------------

### Verify Debian Docker Image Logs

Source: https://docs.hedgedoc.org/dev/release_checklist

Example log output from a running Debian-based HedgeDoc container, showing a successful health check.

```log
127.0.0.1 - - [06/Dec/2025:16:17:51 +0000] "GET /_health HTTP/1.1" 200 14 "-" "hedgedoc-container-healthcheck/1.2"
```

--------------------------------

### GET /new

Source: https://docs.hedgedoc.org/dev/openapi.yml

Creates a new note with a random ID and default (blank) content. A redirect to the newly created note is issued.

```APIDOC
## GET /new

### Description
Creates a new note. A random id will be assigned and the content will equal to the template (blank by default). After note creation a redirect is issued to the created note.

### Method
GET

### Endpoint
/new

### Response
#### Success Response (200)
- Description: Redirect to the new note
```

--------------------------------

### Minimal HedgeDoc Configuration

Source: https://docs.hedgedoc.org/setup/manual-setup

A minimal JSON configuration for HedgeDoc, specifying SQLite database and domain settings. This can be used as a starting point for production environments.

```json
{
  "production": {
    "db": {
      "dialect": "sqlite",
      "storage": "./db.hedgedoc.sqlite"
   },
    "urlAddPort": true,
    "domain": "localhost"
  }
}

```

--------------------------------

### Authelia Identity Providers Configuration

Source: https://docs.hedgedoc.org/guides/auth/authelia

Example `identity_providers` section for Authelia's `configuration.yml` to enable OIDC integration with HedgeDoc. Remember to use Docker secrets for sensitive information.

```yaml
identity_providers:
  oidc:
    hmac_secret: <hmac secret here> # use docker secrets for this
    issuer_private_key: <issuer private key secret here> # use docker secrets for this
    access_token_lifespan: 1h
    authorize_code_lifespan: 1m
    id_token_lifespan: 1h
    refresh_token_lifespan: 90m
    enable_client_debug_messages: false
    clients:
      - id: HedgeDoc # this should be changed to something more secure
        description: HedgeDoc SSO
        secret: <client secret here>
        public: false
        authorization_policy: two_factor
        audience: []
        scopes:
          - openid
          - email
          - profile
        redirect_uris:
          - https://<your-hedgedoc-url>/auth/oauth2/callback
        grant_types:
          - refresh_token
          - authorization_code
        response_types:
          - code
        response_modes:
          - form_post
          - query
          - fragment
        userinfo_signing_algorithm: none

```

--------------------------------

### GET /server/status

Source: https://docs.hedgedoc.org/dev/openapi.yml

Retrieves information about the running HedgeDoc instance, including user counts and socket queue status.

```APIDOC
## GET /server/status

### Description
Returns information about the running HedgeDoc instance, including metrics on online users and socket queue lengths.

### Method
GET

### Endpoint
/server/status

### Response
#### Success Response (200)
- **onlineRegisteredUsers** (integer) - How many of the online users are registered on the server
- **distinctOnlineRegisteredUsers** (integer) - How many of the distinct online users are registered on the server
- **isConnectionBusy** (boolean) - Status of the connection socket
- **connectionSocketQueueLength** (integer) - Length of the connection socket queue
- **isDisconnectBusy** (boolean) - Status of the disconnect socket
- **disconnectSocketQueueLength** (integer) - Length of the disconnect socket queue
```

--------------------------------

### HedgeDoc Environment Variables for LDAP Auth

Source: https://docs.hedgedoc.org/guides/auth/ldap-ad

Configure these environment variables in your HedgeDoc setup to enable Active Directory LDAP authentication. Ensure correct values for URL, bind credentials, and search base.

```shell
CMD_LDAP_URL=ldap://internal.example.com
CMD_LDAP_BINDDN=cn=binduser,cn=Users,dc=internal,dc=example,dc=com
CMD_LDAP_BINDCREDENTIALS="<super secret password>"
CMD_LDAP_SEARCHBASE=dc=internal,dc=example,dc=com
CMD_LDAP_SEARCHFILTER=(&(objectcategory=person)(objectclass=user)(|(sAMAccountName={{username}})(mail={{username}})))
CMD_LDAP_USERIDFIELD=sAMAccountName
CMD_LDAP_PROVIDERNAME="Example Inc AD"

```

--------------------------------

### Systemd Unit File for HedgeDoc

Source: https://docs.hedgedoc.org/setup/manual-setup

A standard systemd unit file configuration for running HedgeDoc in a production environment. Ensure the User, Group, and WorkingDirectory fields are updated to match your specific installation.

```ini
[Unit]
Description=HedgeDoc - The best platform to write and share markdown.
Documentation=https://docs.hedgedoc.org/
After=network.target
# Uncomment if you use MariaDB/MySQL
# After=mysql.service
# Uncomment if you use PostgreSQL
# After=postgresql.service

[Service]
Type=exec
Environment=NODE_ENV=production
Restart=always
RestartSec=2s
ExecStart=/usr/bin/yarn start
CapabilityBoundingSet=
NoNewPrivileges=true
PrivateDevices=true
RemoveIPC=true
LockPersonality=true
ProtectControlGroups=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectKernelLogs=true
ProtectClock=true
ProtectHostname=true
ProtectProc=noaccess
RestrictRealtime=true
RestrictSUIDSGID=true
RestrictNamespaces=true
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
SystemCallArchitectures=native
SystemCallFilter=@system-service pkey_alloc pkey_mprotect

# You may have to adjust these settings
User=hedgedoc
Group=hedgedoc
WorkingDirectory=/opt/hedgedoc

# Example: local storage for uploads and SQLite
# ReadWritePaths=/opt/hedgedoc/public/uploads /opt/hedgedoc/db

[Install]
WantedBy=multi-user.target
```

--------------------------------

### GET /{note}/publish

Source: https://docs.hedgedoc.org/dev/openapi.yml

Redirects to the published version of a specified note.

```APIDOC
## GET /{note}/publish

### Description
Redirects to the published version of the note.

### Method
GET

### Endpoint
/{note}/publish

### Path Parameters
- **note** (string) - Required - The note which should be published

### Response
#### Success Response (200)
- Description: Redirect to the published version of the note

#### Error Response (404)
- Description: Note does not exist
```

--------------------------------

### Manage Users with bin/manage_users

Source: https://docs.hedgedoc.org/dev/release_checklist

Demonstrates how to add, reset, and delete users using the `bin/manage_users` script. Ensure the script is executable before running.

```bash
bin/manage_users --add test@example.com
```

```bash
bin/manage_users --reset test@example.com
```

```bash
bin/manage_users --del test@example.com
```

--------------------------------

### Build and Run Alpine Docker Image

Source: https://docs.hedgedoc.org/dev/release_checklist

Builds an Alpine-based HedgeDoc Docker image and runs it, exposing port 3000. Configure domain, URL port addition, and database URL using environment variables. The server is accessible via http://localhost:3000.

```bash
docker buildx build -f alpine/Dockerfile -t hedgedoc-local:1.x.y-alpine .
docker run --rm -p 3000:3000 -e CMD_DOMAIN="localhost" -e CMD_URL_ADDPORT=true -e "CMD_DB_URL=sqlite://:memory:" hedgedoc-local:1.x.y-alpine
```

--------------------------------

### Build and Run Debian Docker Image

Source: https://docs.hedgedoc.org/dev/release_checklist

Builds a Debian-based HedgeDoc Docker image and runs it, exposing port 3000. Configure domain, URL port addition, and database URL using environment variables. The server is accessible via http://localhost:3000.

```bash
docker buildx build -f debian/Dockerfile -t hedgedoc-local:1.x.y-debian .
docker run --rm -p 3000:3000 -e CMD_DOMAIN="localhost" -e CMD_URL_ADDPORT=true -e "CMD_DB_URL=sqlite://:memory:" hedgedoc-local:1.x.y-debian
```

--------------------------------

### List of Pads from Etherpad

Source: https://docs.hedgedoc.org/guides/migrate-etherpad

A sample list of pad names, one per line, as obtained from Etherpad.

```text
date-ideas
groceries
london
weddingchecklist
(...)

```

--------------------------------

### Get Specific Note Revision

Source: https://docs.hedgedoc.org/dev/openapi.yml

Retrieves a specific revision of a note with its content and authorship metadata.

```APIDOC
## GET /{note}/revision/{revision-id}

### Description
Returns the revision of the note with some metadata. The revision is returned as a JSON object with the content of the note and the authorship.

### Method
GET

### Endpoint
`/{note}/revision/{revision-id}`

### Parameters
#### Path Parameters
- **note** (text/plain) - Required - The note for which the revision should be shown
- **revision-id** (text/plain) - Required - The id (timestamp) of the revision to fetch

### Response
#### Success Response (200)
- **content** (string) - The raw markdown content of the note revision
- **authorship** (array) - Data which gives insights about who worked on the note
  - items (integer) - Unique user ids and additional data
- **patch** (array) - Data which gives insight about what changed in comparison to former revisions
  - items (string)

#### Response Example
{
  "content": "# My Note",
  "authorship": [1, 2],
  "patch": ["added line 1"]
}
```

--------------------------------

### Get Note Revisions

Source: https://docs.hedgedoc.org/dev/openapi.yml

Retrieves a list of available note revisions, including their timestamps and lengths.

```APIDOC
## GET /{note}/revision

### Description
Returns a list of the available note revisions. The list is returned as a JSON object with an array of revision-id and length associations. The revision-id equals to the timestamp when the revision was saved.

### Method
GET

### Endpoint
`/{note}/revision`

### Parameters
#### Path Parameters
- **note** (text/plain) - Required - The note for which revisions should be shown

### Response
#### Success Response (200)
- **revision** (array) - Array that holds all revision-info objects
  - **time** (integer) - UNIX-timestamp of when the revision was saved. Is also the revision-id.
  - **length** (integer) - Length of the document to the timepoint the revision was saved

#### Response Example
{
  "revision": [
    {
      "time": 1570921051959,
      "length": 1024
    }
  ]
}
```

--------------------------------

### Available Presentation Options

Source: https://docs.hedgedoc.org/references/slide-options

A comprehensive list of configuration keys for customizing reveal.js behavior.

```yaml
# Display controls in the bottom right corner
controls: true

# Display a presentation progress bar
progress: true

# Set default timing of 2 minutes per slide
defaultTiming: 120

# Display the page number of the current slide
slideNumber: false

# Push each slide change to the browser history
history: false

# Enable keyboard shortcuts for navigation
keyboard: true

# Enable the slide overview mode
overview: true

# Vertical centering of slides
center: true

# Enables touch navigation on devices with touch input
touch: true

# Loop the presentation
loop: false

# Change the presentation direction to be RTL
rtl: false

# Randomizes the order of slides each time the presentation loads
shuffle: false

# Turns fragments on and off globally
fragments: true

# Flags if the presentation is running in an embedded mode,
# i.e. contained within a limited portion of the screen
embedded: false

# Flags if we should show a help overlay when the questionmark
# key is pressed
help: true

# Flags if speaker notes should be visible to all viewers
showNotes: false

# Global override for autolaying embedded media (video/audio/iframe)
# - null: Media will only autoplay if data-autoplay is present
# - true: All media will autoplay, regardless of individual setting
# - false: No media will autoplay, regardless of individual setting
autoPlayMedia: null

# Number of milliseconds between automatically proceeding to the
# next slide, disabled when set to 0, this value can be overwritten
# by using a data-autoslide attribute on your slides
autoSlide: 0

# Stop auto-sliding after user input
autoSlideStoppable: true

# Use this method for navigation when auto-sliding
autoSlideMethod: Reveal.navigateNext

# Enable slide navigation via mouse wheel
mouseWheel: false

# Hides the address bar on mobile devices
hideAddressBar: true

# Opens links in an iframe preview overlay
previewLinks: false

# Transition style
transition: 'slide' 
# none/fade/slide/convex/concave/zoom

# Transition speed
transitionSpeed: 'default'
# default/fast/slow

# Transition style for full page slide backgrounds
backgroundTransition: 'fade'
# none/fade/slide/convex/concave/zoom

# Number of slides away from the current that are visible
viewDistance: 3

# Parallax background image
parallaxBackgroundImage: ''
# e.g. "'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'"

# Parallax background size
parallaxBackgroundSize: ''
# CSS syntax, e.g. "2100px 900px"

# Number of pixels to move the parallax background per slide
# - Calculated automatically unless specified
# - Set to 0 to disable movement along an axis
parallaxBackgroundHorizontal: null
parallaxBackgroundVertical: null

# The display mode that will be used to show slides
display: 'block'
```

--------------------------------

### Checkout New HedgeDoc Release with Git

Source: https://docs.hedgedoc.org/setup/manual-setup

Use Git to fetch the latest changes and checkout a specific new release tag for upgrading HedgeDoc.

```bash
git fetch origin && git checkout 1.10.6
```

--------------------------------

### Build Frontend Bundle

Source: https://docs.hedgedoc.org/dev/getting-started

Builds the frontend bundle using webpack. This command is typically used for production builds.

```bash
yarn run build
```

--------------------------------

### Get User Profile

Source: https://docs.hedgedoc.org/dev/openapi.yml

Retrieves the profile data of the currently logged-in user. Requires an active session.

```APIDOC
## GET /me

### Description
Returns the profile data of the current logged-in user. The data is returned as a JSON object containing the user-id, the user's name and a url to the profile picture. Requires an active session of the user.

### Method
GET

### Endpoint
`/me`

### Response
#### Success Response (200)
- **status** (string) - ok if everything works as expected, forbidden if the user is not logged-in
- **id** (string) - Unique id of the user
- **name** (string) - Name of the user

#### Response Example
{
  "status": "ok",
  "id": "user123",
  "name": "John Doe"
}
```

--------------------------------

### GET /{note}/slide

Source: https://docs.hedgedoc.org/dev/openapi.yml

Redirects to the slide-presentation version of a specified note. This is useful for notes designed as slides.

```APIDOC
## GET /{note}/slide

### Description
Redirects to the slide-presentation of the note. This is only useful on notes which are designed to be slides.

### Method
GET

### Endpoint
/{note}/slide

### Path Parameters
- **note** (string) - Required - The note which should be shown as slide

### Response
#### Success Response (200)
- Description: Redirect to the slide version of the note

#### Error Response (404)
- Description: Note does not exist
```

--------------------------------

### Migrate Filesystem Uploads to Minio

Source: https://docs.hedgedoc.org/dev/release_checklist

Steps to migrate existing uploads from the local filesystem to a Minio S3 bucket. This involves configuring HedgeDoc with Minio details and running the migration script.

```bash
bin/migrate_fs_to_minio
```

--------------------------------

### Auto-Reload Server with Nodemon

Source: https://docs.hedgedoc.org/dev/getting-started

Restarts the server automatically when changes are detected in specified files. Requires nodemon to be installed.

```bash
nodemon --watch app.js --watch lib --watch locales app.js
```

--------------------------------

### Configure Minio Settings

Source: https://docs.hedgedoc.org/guides/minio-image-upload

Define the Minio connection parameters in the HedgeDoc configuration file.

```json
"minio": {
  "accessKey": "888MXJ7EP4XXXXXXXXX",
  "secretKey": "yQS2EbM1Y6IJrp/1BUKWq2/XXXXXXXXXXXXXXX",
  "endPoint": "localhost",
  "port": 9000,
  "secure": false
}
```

--------------------------------

### GET /{note}/info

Source: https://docs.hedgedoc.org/dev/openapi.yml

Returns metadata about a specified note, including its title, description, creation date, and view count.

```APIDOC
## GET /{note}/info

### Description
Returns metadata about the note. This includes the title and description of the note as well as the creation date and viewcount.

### Method
GET

### Endpoint
/{note}/info

### Path Parameters
- **note** (string) - Required - The note for which to retrieve information

### Response
#### Success Response (200)
- **title** (string) - The title of the note (default: Untitled)
- **description** (string) - The description of the note or the first words from the note
- **viewcount** (integer) - How often the published version of the note was viewed
- **createtime** (string) - The timestamp when the note was created in ISO 8601 format.
- **updatetime** (string) - The timestamp when the note was last updated in ISO 8601 format.

#### Response Example
```json
{
  "title": "My Note Title",
  "description": "This is a sample note.",
  "viewcount": 150,
  "createtime": "2023-10-27T10:00:00Z",
  "updatetime": "2023-10-27T10:30:00Z"
}
```
```

--------------------------------

### Configure SAML Attributes via Environment Variables

Source: https://docs.hedgedoc.org/guides/auth/saml-keycloak

Set these environment variables if you prefer configuring HedgeDoc without modifying the config.json file.

```bash
CMD_SAML_ATTRIBUTE_USERNAME=username
CMD_SAML_ATTRIBUTE_EMAIL=email
```

--------------------------------

### Configure Mattermost OAuth2 via environment variables

Source: https://docs.hedgedoc.org/guides/auth/mattermost-self-hosted

Use these environment variables as an alternative to the config.json file for setting up Mattermost authentication.

```bash
CMD_OAUTH2_BASEURL=https://your.mattermost.domain
CMD_OAUTH2_USER_PROFILE_URL=https://your.mattermost.domain/api/v4/users/me
CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=id
CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=username
CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=email
CMD_OAUTH2_TOKEN_URL=https://your.mattermost.domain/oauth/access_token
CMD_OAUTH2_AUTHORIZATION_URL=https://your.mattermost.domain/oauth/authorize
CMD_OAUTH2_CLIENT_ID=ii4p1u3jz7dXXXXXXXXXXXXXXX
CMD_OAUTH2_CLIENT_SECRET=mqzzx6fydbXXXXXXXXXXXXXXXX
```

--------------------------------

### Configure GitHub Client ID and Secret via Environment Variables

Source: https://docs.hedgedoc.org/guides/auth/github

Alternatively, set your GitHub Client ID and Client Secret as environment variables for authentication.

```bash
CMD_GITHUB_CLIENTID=3747d30eaccXXXXXXXXX
CMD_GITHUB_CLIENTSECRET=2a8e682948eee0c580XXXXXXXXXXXXXXXXXXXXXX
```

--------------------------------

### Execute Migration Script

Source: https://docs.hedgedoc.org/guides/migrate-etherpad

Command to run the migration script, providing the file containing the list of pad names as an argument.

```shell
./migrate-etherpad.sh pad_names.txt

```

--------------------------------

### Configure HedgeDoc SAML settings

Source: https://docs.hedgedoc.org/guides/auth/saml-keycloak

Add this block to your config.json file to enable SAML authentication.

```json
"saml": {
  "issuer": "hedgedoc", // Change to the "Client ID" specified in the Keycloak Client
  "identifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
  "idpSsoUrl": "https://keycloak.example.org/auth/realms/test/protocol/saml", // replace keycloak.example.org with the url of your keycloak server
  "idpCert": "/path/to/the/cert.pem",
  "clientCert": "/path/to/the/key.pem" // this one is optional, see below
}
```

--------------------------------

### Create Release Tarball

Source: https://docs.hedgedoc.org/dev/release_checklist

Commands to create a release tarball of the HedgeDoc project. This involves cloning the repository, installing dependencies, building the project, and packaging the necessary files.

```bash
mkdir /tmp/hedgedoc && cd /tmp/hedgedoc
git clone -b master https://github.com/hedgedoc/hedgedoc.git .
yarn install
yarn build
cd ..
tar cvzf hedgedoc-x.y.z.tar.gz --sort=name --exclude hedgedoc/node_modules --exclude hedgedoc/.git --exclude hedgedoc/.github --exclude hedgedoc/.yarn/cache hedgedoc
```

--------------------------------

### Configure SAML in HedgeDoc

Source: https://docs.hedgedoc.org/guides/auth/saml-onelogin

Provides the configuration options for SAML authentication using either a JSON file or environment variables.

```json
{
  "production": {
    "saml": {
      "idpSsoUrl": "https://*******.onelogin.com/trust/saml2/http-post/sso/******",
      "idpCert": "/path/to/idp_cert.pem"
    }
  }
}
```

```bash
CMD_SAML_IDPSSOURL=https://*******.onelogin.com/trust/saml2/http-post/sso/******
CMD_SAML_IDPCERT=/path/to/idp_cert.pem
```

--------------------------------

### Insert Migration into SequelizeMeta Table

Source: https://docs.hedgedoc.org/guides/migration-troubleshooting

Use this SQL statement to manually add a failed migration's name to the SequelizeMeta table. This is necessary when HedgeDoc fails to record migration progress, preventing it from starting.

```sql
INSERT INTO "SequelizeMeta" (name) VALUES ('20180306150303-fix-enum.js');
```

--------------------------------

### Deploy HedgeDoc with Docker Compose

Source: https://docs.hedgedoc.org/setup/docker

A minimal configuration for running HedgeDoc and a PostgreSQL database. Not intended for production use.

```yaml
version: '3'
services:
  database:
    image: postgres:17.7-alpine
    environment:
      - POSTGRES_USER=hedgedoc
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=hedgedoc
    volumes:
      - database:/var/lib/postgresql/data
    restart: always
  app:
    # Make sure to use the latest release from https://hedgedoc.org/latest-release
    image: quay.io/hedgedoc/hedgedoc:1.10.6
    environment:
      - CMD_DB_URL=postgres://hedgedoc:password@database:5432/hedgedoc
      - CMD_DOMAIN=localhost
      - CMD_URL_ADDPORT=true
    volumes:
      - uploads:/hedgedoc/public/uploads
    ports:
      - "3000:3000"
    restart: always
  depends_on:
      - database
volumes:
  database:
  uploads:
```

--------------------------------

### Migrate Etherpad to HedgeDoc Script

Source: https://docs.hedgedoc.org/guides/migrate-etherpad

A shell script to automate the migration of Etherpad pads to HedgeDoc using `curl` and `hedgedoc-cli`. Ensure to configure `ETHERPAD_SERVER` and `HEDGEDOC_SERVER`.

```shell
#!/bin/sh

# migrate-etherpad.sh
#
# Description: Migrate pads from etherpad to HedgeDoc
# Author: Daan Sprenkels <hello@dsprenkels.com>

# This script uses the HedgeDoc command line script[1] to import a list of pads from
# [1]: https://github.com/hedgedoc/cli/blob/master/bin/hedgedoc

# The base url to where etherpad is hosted
ETHERPAD_SERVER="https://etherpad.example.com"

# The base url where HedgeDoc is hosted
HEDGEDOC_SERVER="https://hedgedoc.example.com"

# Write a list of pads and the urls which they were migrated to
REDIRECTS_FILE="redirects.txt"


# Fail if not called correctly
if (( $# != 1 )); then
    echo "Usage: $0 PAD_NAMES_FILE"
    exit 2
fi

# Do the migration
for PAD_NAME in $1; do
    # Download the pad
    PAD_FILE="$(mktemp)"
    curl "$ETHERPAD_SERVER/p/$PAD_NAME/export/txt" >"$PAD_FILE"

    # Import the pad into HedgeDoc
    OUTPUT="$(./hedgedoc import "$PAD_FILE")"
    echo "$PAD_NAME -> $OUTPUT" >>"$REDIRECTS_FILE"
done

```

--------------------------------

### Configure Slide Options with YAML

Source: https://docs.hedgedoc.org/references/yaml-metadata

Use 'slideOptions' to provide custom configurations for slide mode, such as transition effects and themes. Ensure two spaces for indentation.

```yaml
slideOptions:
  transition: fade
  theme: white
```

--------------------------------

### Generate private keys and certificates

Source: https://docs.hedgedoc.org/guides/auth/saml-keycloak

Use OpenSSL to generate a private key and certificate for signing.

```bash
openssl genrsa -out priv.pem 2048
openssl req -new -x509 -key priv.pem -out cert.pem
```

--------------------------------

### Retrieve Minio Credentials

Source: https://docs.hedgedoc.org/guides/minio-image-upload

Fetch the access and secret keys from the running container logs.

```bash
docker logs test-minio
```

--------------------------------

### POST /new

Source: https://docs.hedgedoc.org/dev/openapi.yml

Imports markdown data into a new note. A random ID is assigned, and the content is set to the request body. A redirect to the new note is issued.

```APIDOC
## POST /new

### Description
Imports some markdown data into a new note. A random id will be assigned and the content will equal to the body of the received HTTP-request.

### Method
POST

### Endpoint
/new

### Request Body
- **content** (text/markdown) - Required - The content of the note to be imported as markdown

### Request Example
```text/markdown
# Some header
```

### Response
#### Success Response (200)
- Description: Redirect to the imported note
```

--------------------------------

### Configure Twitter Credentials via Environment Variables

Source: https://docs.hedgedoc.org/guides/auth/twitter

Alternatively, set your Twitter consumer key and secret as environment variables for authentication.

```bash
CMD_TWITTER_CONSUMERKEY=esTCJFXXXXXXXXXXXXXXXXXXX
CMD_TWITTER_CONSUMERSECRET=zpCs4tU86pRVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

--------------------------------

### Configure Presentation via YAML Header

Source: https://docs.hedgedoc.org/references/slide-options

Define slide options within the YAML block at the top of the document. Ensure exactly two spaces are used for indentation.

```yaml
---
title: Example Slide
tags: presentation
slideOptions:
  theme: solarized
  transition: 'fade'
  # parallaxBackgroundImage: 'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'
---
```

--------------------------------

### Clone HedgeDoc Repository

Source: https://docs.hedgedoc.org/dev/getting-started

Use this command to clone the HedgeDoc repository. Cloning is the preferred method for obtaining the source code.

```bash
git clone https://github.com/hedgedoc/hedgedoc.git hedgedoc-server
```

--------------------------------

### Configure HedgeDoc OAuth2 via Environment Variables

Source: https://docs.hedgedoc.org/guides/auth/nextcloud

Alternatively, configure HedgeDoc's OAuth2 authentication with Nextcloud using environment variables. This is useful for containerized deployments. Replace placeholders with your Nextcloud domain and client credentials.

```bash
CMD_OAUTH2_CLIENT_ID=ii4p1u3jz7dXXXXXXXXXXXXXXX
CMD_OAUTH2_CLIENT_SECRET=mqzzx6fydbXXXXXXXXXXXXXXXX
CMD_OAUTH2_AUTHORIZATION_URL=https://<your-nextcloud-domain>/apps/oauth2/authorize
CMD_OAUTH2_TOKEN_URL=https://<your-nextcloud-domain>/apps/oauth2/api/v1/token
CMD_OAUTH2_USER_PROFILE_URL=https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json
CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=ocs.data.id
CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=ocs.data.display-name
CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=ocs.data.email
```

--------------------------------

### Clone HedgeDoc Repository

Source: https://docs.hedgedoc.org/setup/manual-setup

Use Git to clone the HedgeDoc repository and checkout a specific release version.

```bash
git clone -b 1.10.6 https://github.com/hedgedoc/hedgedoc.git
```

--------------------------------

### Configure Nginx HTTP/2 for Older Versions

Source: https://docs.hedgedoc.org/guides/reverse-proxy

Use this syntax for Nginx versions prior to 1.25.1 where http2 is a parameter of the listen directive.

```nginx
listen [::]:443 ssl http2;
listen 443 ssl http2;
```

--------------------------------

### Configure Postgres Database

Source: https://docs.hedgedoc.org/dev/release_checklist

Configuration snippet for connecting HedgeDoc to a PostgreSQL database. Ensure the PostgreSQL server is running and accessible with the provided credentials.

```json
"db": {
  "username": "hd1db",
  "password": "hd1db",
  "database": "hd1db",
  "host": "localhost",
  "port": "5432",
  "dialect": "postgres"
}
```

--------------------------------

### Configure HedgeDoc environment variables for S3

Source: https://docs.hedgedoc.org/guides/s3-google-cloud-storage

Set these environment variables to enable S3-compatible storage in HedgeDoc. Replace the placeholder values with your specific Google Cloud credentials and bucket name.

```bash
CMD_IMAGE_UPLOAD_TYPE="s3"
CMD_S3_ENDPOINT="https://storage.googleapis.com"
CMD_S3_ACCESS_KEY_ID="GOOG1EXXXXXXXXXX"
CMD_S3_SECRET_ACCESS_KEY="XXXXXXXXXX"
CMD_S3_BUCKET="your-bucket-name"
```

--------------------------------

### Set Meta Description with YAML

Source: https://docs.hedgedoc.org/references/yaml-metadata

The 'description' option sets the meta description tag, affecting only the Publish function.

```yaml
description: meta description
```

--------------------------------

### Create GitHub Gist from Note

Source: https://docs.hedgedoc.org/dev/openapi.yml

Creates a new GitHub Gist with the note's content. Requires GitHub integration to be configured.

```APIDOC
## GET /{note}/gist

### Description
Creates a new GitHub Gist with the note's content. If GitHub integration is configured, the user will be redirected to GitHub and a new Gist with the content of the note will be created.

### Method
GET

### Endpoint
`/{note}/gist`

### Parameters
#### Path Parameters
- **note** (text/plain) - Required - The note which should be pasted to GitHub gist

### Response
#### Default Response
- Description: Redirect to the created gist (or the GitHub authentication before)

#### Response Example
(Redirect to GitHub)
```

--------------------------------

### Configure HedgeDoc config.json

Source: https://docs.hedgedoc.org/guides/s3-image-upload

Update the production configuration block to enable S3 image uploads with your credentials.

```json
{
  "production": {
    ...
    "imageuploadtype": "s3",
    "s3": {
      "accessKeyId": "YOUR_S3_ACCESS_KEY_ID",
      "secretAccessKey": "YOUR_S3_ACCESS_KEY",
      "region": "YOUR_S3_REGION" // example: ap-northeast-1
    },
    "s3bucket": "YOUR_S3_BUCKET_NAME"
  }
}
```

--------------------------------

### POST /new/{alias}

Source: https://docs.hedgedoc.org/dev/openapi.yml

Imports markdown data into a new note with a specified alias. This is only possible if FreeURL-mode is enabled. The content is taken from the request body.

```APIDOC
## POST /new/{alias}

### Description
Imports some markdown data into a new note with a given alias. This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](../configuration-env-vars.md#users-and-privileges) is enabled.

### Method
POST

### Endpoint
/new/{alias}

### Path Parameters
- **alias** (string) - Required - The alias for the note-id under which the note will be saved

### Request Body
- **content** (text/markdown) - Required - The content of the note to be imported as markdown

### Request Example
```text/markdown
# Some heading
```

### Response
#### Success Response (200)
- Description: Redirect to the imported note
```

--------------------------------

### Nginx Redirect Configuration

Source: https://docs.hedgedoc.org/guides/migrate-etherpad

An Nginx configuration snippet generated from the `redirects.txt` file to set up 301 permanent redirects for old Etherpad URLs to new HedgeDoc URLs.

```nginx
location = /p/date-ideas {
    return 301 https://hedgedoc.example.com/mPt0M1KfiKSBOTQ3mNcdfn;
}
location = /p/groceries {
    return 301 https://hedgedoc.example.com/UukqgwLfhYyUUtARlcJ2_y;
}
location = /p/london {
    return 301 https://hedgedoc.example.com/_d3wa-BE8t4Swv5w7O2_9R;
}
location = /p/weddingchecklist {
    return 301 https://hedgedoc.example.com/XcQGqlBjl0u40wfT0N8TzQ;
}


```

--------------------------------

### Configure HedgeDoc OAuth2 environment variables

Source: https://docs.hedgedoc.org/guides/auth/keycloak

Add these environment variables to the app service in your docker-compose.yml file to connect HedgeDoc to Keycloak.

```yaml
  app:
    environment:
      - CMD_OAUTH2_USER_PROFILE_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/userinfo
      - CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=preferred_username
      - CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=name
      - CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=email
      - CMD_OAUTH2_TOKEN_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/token
      - CMD_OAUTH2_AUTHORIZATION_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/auth
      - CMD_OAUTH2_CLIENT_ID=<your client ID>
      - CMD_OAUTH2_CLIENT_SECRET=<your client secret, which you can find under the Credentials tab for your client>
      - CMD_OAUTH2_PROVIDERNAME=Keycloak
      - CMD_OAUTH2_SCOPE=openid email profile
      - CMD_DOMAIN=<hedgedoc.example.com>
      - CMD_PROTOCOL_USESSL=true
      - CMD_URL_ADDPORT=false
```

--------------------------------

### Configure Apache Reverse Proxy

Source: https://docs.hedgedoc.org/guides/reverse-proxy

Apache configuration requiring proxy, proxy_http, and proxy_wstunnel modules to be enabled.

```apache
<VirtualHost *:443>
  ServerName hedgedoc.example.com

  RewriteEngine on
  RewriteCond %{REQUEST_URI} ^/socket.io             [NC]
  RewriteCond %{HTTP:Upgrade} =websocket             [NC]
  RewriteRule /(.*)  ws://127.0.0.1:3000/$1          [P,L]

  ProxyPass / http://127.0.0.1:3000/
  ProxyPassReverse / http://127.0.0.1:3000/

  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/hedgedoc.example.com/fullchain.pem
  SSLCertificateKeyFile /etc/letsencrypt/live/hedgedoc.example.com/privkey.pem
  Include /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>
```

--------------------------------

### Backup PostgreSQL Database

Source: https://docs.hedgedoc.org/setup/docker

Uses pg_dump to export the HedgeDoc database to a local SQL file.

```bash
 docker-compose exec database pg_dump hedgedoc -U hedgedoc > backup.sql
```