HedgeDoc

https://docs.hedgedoc.org/
Admin
HedgeDoc is a real-time collaborative markdown editor for creating and sharing notes, inspired by...
Tokens:25,343
Snippets:317
Trust Score:9.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### 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
```

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

### Full Minio Configuration Example

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

A complete example of the Minio-related configuration block in config.json.

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

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

### Start HedgeDoc Server

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

Command to start the HedgeDoc server in production mode.

```bash
NODE_ENV=production yarn start
```

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

### Install Corepack

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

Command to install corepack globally if it is not available.

```bash
npm i -g corepack
```

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

### 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
(...)

```

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

### Fetch Specific Revision Example

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

Example parameter values for the specific note revision endpoint.

```text
my-note
```

```text
1570921051959
```

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

### Start Minio Development Container

Source: https://docs.hedgedoc.org/guides/media/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
```

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

### 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
```

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

### Build Frontend Bundle

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

Commands to install dependencies and build the frontend for versions older than 1.7.0.

```bash
yarn install --immutable
```

```bash
yarn build
```

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

### YAML Metadata Example

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

Example of YAML metadata block used for configuring document properties.

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

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

### Specify Note Path Parameter

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

Example value for the note identifier in the path.

```yaml
example: my-note
```

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

### Upgrade Git Repository

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

Command to fetch and switch to a specific version tag in a Git-based installation.

```bash
git fetch origin && git checkout 1.11.0
```

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

### Import Markdown Content

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

Example of markdown content used for importing into a new note.

```text/markdown
# Some header
```

```text/markdown
# Some heading
```

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

### GET /me/export

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

Exports a zip-archive with all notes of the current user.

```APIDOC
## GET /me/export

### Description
Exports a zip-archive with all notes of the current user.

### Method
GET

### Endpoint
/me/export
```

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

### Authelia OIDC configuration

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

Example configuration for the identity_providers section in Authelia's configuration.yml.

```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:
      - client_id: <random client id>
        client_name: HedgeDoc
        secret: <client secret here>
        public: false
        authorization_policy: two_factor
        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
        token_endpoint_auth_method: 'client_secret_post'
```

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

### GET /new

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

Creates a new note with a random ID and redirects to the created note.

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

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

### GET /{note}/download

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

Retrieves 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

### Parameters
#### 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
```

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

### Create New Note via API

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

Example of using curl to create a new note via the POST /new endpoint.

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

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

### 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 /me

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

Returns the profile data of the current logged-in user.

```APIDOC
## GET /me

### Description
Returns the profile data of the current logged-in user as a JSON object. Requires an active session.

### Method
GET

### Endpoint
/me

### Response
#### Success Response (200)
- **status** (string) - ok if everything works as expected, forbidden is the user is not logged-in
- **id** (string) - Unique id of the user
- **name** (string) - The user's display name
- **photo** (string) - An url to the online stored user profile photo
```

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

### Note Alias Parameter

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

Example of an alias string used in the URL path for note creation.

```text/plain
my-note
```

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

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

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

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

### Configure SAML in config.json

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

Add the SAML configuration block to your HedgeDoc config.json file, ensuring the issuer and URLs match your Keycloak setup.

```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
}
```

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

### GET /{note}/gist

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** (string) - Required - The note which should be pasted to GitHub gist
```

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

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

```

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

### GET /{note}/info

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

Returns metadata about the note, including 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

### Parameters
#### Path Parameters
- **note** (string) - Required - The note for which the info should be shown

### Response
#### Success Response (200)
- **title** (string) - The title of the note
- **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.
```

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

### Build and Run Alpine Docker Image

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

Commands to build and test the Alpine-based HedgeDoc container.

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

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

### GET /history

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

Returns a list of the last viewed notes.

```APIDOC
## GET /history

### Description
Returns a list of the last viewed notes as a JSON object containing an array of history entries.

### Method
GET

### Endpoint
/history

### Response
#### Success Response (200)
- **history** (array) - The array that contains history objects
```

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

### Build and Run Debian Docker Image

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

Commands to build and test the Debian-based HedgeDoc container.

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

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

### GET /{note}/slide

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

Redirects to the slide-presentation version of a specified note.

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

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

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

### Minimal Configuration File

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

A basic JSON configuration file for HedgeDoc using SQLite.

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

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

### 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
(...)

```

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

### 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'
```

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

### 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
```

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

### Configure HedgeDoc environment variables for S3

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

Set these environment variables to connect HedgeDoc to a Google Cloud Storage bucket using the S3 protocol.

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

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

### Configure Postgres Database

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

Configuration snippet for connecting HedgeDoc to a local Postgres instance.

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

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

### 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
```

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

### Replace User History

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

Example of a form-encoded request body for updating the user's history.

```application/x-www-form-urlencoded
history=[{"id":"example","text":"Untitled","time":1556275442010,"tags":[],"pinned":false}]
```

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

### 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 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
```

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

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

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

Returns the content and authorship metadata for a specific note revision.

```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** (string) - Required - The note for which the revision should be shown
- **revision-id** (string) - 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
- **patch** (array) - Data which gives insight about what changed in comparison to former revisions
```

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

### Configure MariaDB Database

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

Configuration snippet for connecting HedgeDoc to a local MariaDB instance.

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

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

### GET /status

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

Returns the current status of the HedgeDoc instance, including note counts and user activity.

```APIDOC
## GET /status

### Description
Returns the current status of the HedgeDoc instance. The data is returned as a JSON object containing the number of notes stored on the server, (distinct) online users and more.

### Method
GET

### Endpoint
/status

### Response
#### Success Response (200)
- **onlineNotes** (integer) - How many notes are edited at the moment
- **onlineUsers** (integer) - How many users are online at the moment
- **distinctOnlineUsers** (integer) - How many distinct users (different machines) are online at the moment
- **notesCount** (integer) - How many notes are stored on the server
- **registeredUsers** (integer) - How many users are registered on the server
- **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)
- **connectionSocketQueueLength** (integer)
- **isDisconnectBusy** (boolean)
- **disconnectSocketQueueLength** (integer)
```

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

### 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
```

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

### Set Node Environment

Source: https://docs.hedgedoc.org/guides/production-ready

Configure the application to run in production mode for optimized logging and configuration loading.

```bash
NODE_ENV=production
```

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

### POST /new

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

Imports markdown data into a new note with a random ID.

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

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

### GET /{note}/revision

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

Returns a list of the available note revisions as a JSON object containing revision IDs 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.

### Method
GET

### Endpoint
/{note}/revision

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

### Response
#### Success Response (200)
- **revision** (array) - Array that holds all revision-info objects
```

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

### Generate Private Key and Certificate

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

Use these OpenSSL commands to create a new private key and self-signed certificate for client authentication.

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

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

### Create Release Tarball

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

Commands to clone the repository, build the project, and package it into a tarball for distribution.

```bash
mkdir /tmp/hedgedoc && cd /tmp/hedgedoc
git clone -b master https://github.com/hedgedoc/hedgedoc.git .
yarn install
yarn build:ot
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 Authentication

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

Add this block to config.json after downloading the required certificate.

```json
"saml": {
  "idpSsoUrl": "https://auth.hedgedoc.cloud/application/saml/test-hd1-saml/sso/binding/redirect/",
  "idpCert": "/tmp/auth.hedgedoc.cloud.pem",
  "identifierFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
  "attribute": {
    "id": "http://schemas.goauthentik.io/2021/02/saml/uid",
    "username": "http://schemas.goauthentik.io/2021/02/saml/username",
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  }
}
```

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

### 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 docker-compose.yml configuration for running HedgeDoc with 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.11.0
    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
```

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

### Configure Minio Settings in config.json

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

Define the Minio connection parameters within the HedgeDoc configuration file.

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

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

### 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
```

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

### Enable Yarn via Corepack

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

Command to enable Yarn 4 using Node.js corepack.

```bash
corepack enable
```

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

### 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'
---
```

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

### Systemd Unit Configuration

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

A template for running HedgeDoc as a systemd service, requiring adjustments for user, group, and directory paths.

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

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

### Retrieve Minio Credentials

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

Fetch the access credentials from the running Minio container logs.

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

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

### 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
```

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

### POST /new/{alias}

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

Imports markdown data into a new note with a specific alias.

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

### Description
Imports some markdown data into a new note with a given alias. The alias from the url will be assigned to the note if FreeURL-mode is enabled.

### Method
POST

### Endpoint
/new/{alias}

### Parameters
#### 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
```

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

### 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
```

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

### 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;
```

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

### 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
```

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

### Backup PostgreSQL Database

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

Command to export the HedgeDoc PostgreSQL database to a SQL file.

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

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

### Migrate Database Credentials

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

Commands to update database roles and names when migrating from older versions to HedgeDoc.

```bash
docker-compose exec database createuser --superuser -Uhackmd postgres
docker-compose exec database psql -Upostgres -c "alter role hackmd rename to hedgedoc; alter role hedgedoc with password 'password'; alter database hackmd rename to hedgedoc;"
```

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

### 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 HedgeDoc config.json

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

Update the production configuration block to enable S3 image uploads with your specific 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"
  }
}
```

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

### Configure LDAP Authentication

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

Run the test OpenLDAP container and add this configuration to config.json.

```bash
docker run --rm -p 10389:10389 -p 10636:10636 -d ghcr.io/rroemhild/docker-test-openldap:master
```

```json
"ldap": {
  "url": "ldap://localhost:10389",
  "bindDn": "cn=admin,dc=planetexpress,dc=com",
  "bindCredentials": "GoodNewsEveryone",
  "searchBase": "ou=people,dc=planetexpress,dc=com",
  "searchFilter": "(&(uid={{username}})(objectClass=inetOrgPerson))",
  "searchAttributes": ["uid", "cn"],
  "usernameField": "cn",
  "useridField": "uid",
  "tlsOptions": {}
}
```

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

### 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>
```

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

### Enable Google Analytics with YAML

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

Provide your Google Analytics ID using the 'GA' option to enable tracking.

```yaml
GA: UA-12345667-8
```

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

### Restore PostgreSQL Database

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

Commands to restore a database backup into the PostgreSQL container.

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