Write, share, and publish documents with HedgeDoc

Slide Shows

At time of writing, slide show support in HedgeDoc is in beta. However, as demonstrated by a screenshot from the official HedgeDoc slide show demo [7] (Figure 9), it is already possible to turn a HedgeDoc note into a simple slide show viewable in any browser. To create a slide show, you must declare the note type as slide in the frontmatter. You can specify how the slides should look in the frontmatter using the following options:

slideOptions:
  transition: fade
  theme: white
Figure 9: You can also turn Markdown text into an online slide show.

For more details on slideshows, please see the HedgeDoc documentation and demo.

Collaborative Editing

After logging in (see the "Self-Hosting" section for information on how to create an account), HedgeDoc greets you with the default homepage (Figure 10). From here, you can create a new note. You can also search for an existing note using tags (from the note's frontmatter) or generic keywords (from the note's text), with the results ordered by time or title.

Figure 10: The HedgeDoc's default homepage after login.

If you are working collaboratively with other users, perhaps simultaneously, on the same note, you will see something similar to the two browser windows in Figure 11. In the left window, after logging in as a registered user (mfioretti), I created a sample note as a test. Then I opened the same note in another window but this time as an anonymous guest. Note that HedgeDoc assigns guests an arbitrary name (e.g., Pena in Figure 11).

Figure 11: A HedgeDoc note edited by two users simultaneously: one logged in and one an anonymous guest.

The large blue button in the top right corner of each window lets you know who is currently working on a note. Clicking this button lists all users currently working on the active note, with each registered assigned a color (light brown for mfioretti). As shown in Figure 11, the paragraphs I wrote working in the left window as mfioretti are marked with a vertical light brown bar to the right of the line number. Both guests and registered users see changes made by each other in real time.

Figure 11 also highlights a problem with HedgeDoc's interface. Based on this screenshot, it looks like only registered users have the Publish button. This is not true. If a window (on the right Figure 11) is below a certain width, some elements of the top toolbar disappear. With a wider screen, I would have seen two identical toolbars; even the anonymous guest should have the Publish button because I had set the note's permission to Freely, which gives all users permission to do whatever they want with the note. In this example, the only difference between a registered user and an anonymous guest is that only the registered user, who created the note, can change the permissions.

Self-Hosting

Instead of using the web-based app, you can self-host HedgeDoc. At time of writing, the current stable 1.x version is available in several formats, including a Cloudron app [8]. However, the simplest way to host a standalone HedgeDoc instance appears to be the official Docker images [9] (although they are only available for the AMD64 architecture). Almost all the screenshots in this tutorial come from HedgeDoc v1.8.2 running in a Docker container on an Ubuntu 21.04 system.

The recommended way to install a Docker container consists of downloading the sample configuration file (in YAML format) from the HedgeDoc Docker page [10], customizing it according to your needs, and then launching Docker with it. As an example of what you can do with this configuration file see the excerpt shown in Listing 4.

Listing 4

docker-compose.yml (Excerpt)

version: '3'
services:
  database:
    image: postgres:9.6-alpine
    environment:
      - POSTGRES_USER=hedgedoc
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=hedgedoc
....
  app:
    # Make sure to use the latest release from https://hedgedoc.org/latest-release
    image: quay.io/hedgedoc/hedgedoc:1.8.2
    environment:
      - CMD_DB_URL=postgres://hedgedoc:password@database:5432/hedgedoc
      - CMD_DOMAIN=localhost
...
    ports:
      - "3000:3000"

To summarize the instructions in Listing 4: Because HedgeDoc needs a PostGreSql database, you need to download an additional container for PostGreSQL. You then start both containers, making HedgeDoc listen on TCP port 3000. A complete configuration file can contain much more than what is shown in Listing 4.

The HedgeDoc Docker configuration page [10] describes all the variables you can set in the configuration file. I recommend first testing HedgeDoc without changing anything in the configuration file. Once you understand how it works, you can customize the variables.

To download the container and start it as described in the configuration file, run the docker-compose command:

#> sudo docker-compose up -f /absolute/path/to/docker-compose.yml

Unless you see an error message, this should be enough to let you load the homepage of your very own HedgeDoc instance by pointing your browser to https://localhost:3000 (if you installed it on your own computer) or replacing the localhost with the URL of the server where you started the container.

After setting up your instance, you need to create user accounts for you and your team if you want to keep private at least some of the notes that you and your team create. There are two ways to do this. One option is to have each user self-register from the HedgeDoc homepage and receive a password via email. For this option to work, you have to set both self-registration and email delivery in the container configuration file, as described in the HedgeDoc documentation.

The other method, which I personally prefer, involves logging in to the container that runs HedgeDoc and then adding as many users as needed with the command-line utility, manage_users, which is bundled with HedgeDoc. To create my personal account, after launching the container, I found the container's identification code with the ps option of the docker command (Listing 5).

Listing 5

Finding the Container Identification Code

#> sudo docker ps
[sudo] password for marco:
CONTAINER ID    IMAGE                                COMMAND                     CREATED    STATUS      PORTS     NAMES
572918fbff01    quay.io/hedgedoc/hedgedoc:1.8.2      "/usr/local/bin/dock..."    ..

Then I used that code (572918fbff01) to log in to the container, inside a Bash shell, as shown in Listing 6.

Listing 6

Logging in to the Container

#>  sudo docker exec -it 572918fbff01 /bin/bash
root@572918fbff01:/hedgedoc#
#> root@572918fbff01:/hedgedoc# ./bin/manage_users --pass testing --add mfioretti@nexaima.net
Using password from commandline...
Created user with email mfioretti@nexaima.net
root@572918fbff01:/hedgedoc#

Then I ran manage_users to create a HedgeDoc account with my email address as the username and testing as the password. You can also use manage_users to delete users or reset their passwords.

Another thing to do the first time you log in to the container is to look at the internal configuration file, files/config.json. In this file, you can tell HedgeDoc to, among other things, do the following:

  • Accept user logins via LDAP, Facebook, Twitter, or GitHub
  • Store notes in Dropbox instead of locally
  • Store images inside Imgur, Minio, or S3 accounts.

The HedgeDoc main configuration page [11] describes all the values for each of these options. Keep in mind that these options can all be overwritten with environmental variables, which normally have a CMD_ prefix (e.g., CMD_DB_URL or CMD_DOMAIN in Listing 4).

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

SINGLE ISSUES
 
SUBSCRIPTIONS
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More

News