Write, share, and publish documents with HedgeDoc
Tutorial – HedgeDoc
HedgeDoc lets you write documents collaboratively in Markdown and publish them online.
Markdown syntax [1] provides an easy way to create rich text documents out of plain text files. The magic of Markdown (see the "Markdown" box) is more than mere paragraphs, titles, and subtitles – you can also work with high-end features such as slideshows and embedded videos.
Markdown
Markdown files are plain text files, but they allow much more structure than an ordinary plain text file. I say "structure" instead of "formatting"; Markdown's real power lies in not caring about the actual formatting.
With Markdown, you add typographic detail to your text in the most generic way. Markdown makes it easy to write or generate text that is easily converted to any other document format. With just one click or command, a Markdown file can become a web page, a PDF file, a database record, a note in a mind-mapping application, and much more.
The Markdown cheat sheet in Figure 1 shows how Markdown works. For instance, a line starting with one or more hash characters denotes a chapter or subchapter header, text inside two asterisks is bold, square brackets followed by parentheses enclose a hyperlink, and so on.
Several available tools help users create, read, and edit Markdown files, but one of my favorites is HedgeDoc [2], a web-based Markdown editor and online publisher. HedgeDoc, the open source version of the online editing service HackMD [3], lets you create Markdown documents and publish them online from any browser. In addition, HedgeDoc lets you work collaboratively, making it useful for schools or organizations that need to create shared documents in a reusable format. HedgeDoc is also a privacy-friendly alternative to Google Docs or other commercial document services.
Workspace
HedgeDoc is a website, usable from desktop, tablet, and mobile devices, that looks and acts like a text editor or simple word processor. While HedgeDoc is reminiscent of Google Docs and Etherpad, HedgeDoc has the ability to show both the actual Markdown source code and the HTML web page preview (Figure 2).

HedgeDoc also lets you choose the privacy settings for each Markdown document, which HedgeDoc calls a "note." Privacy settings range from Freely (everyone can read, write, and eventually publish the note) to fully Private (Figure 3). If you set a note's permission to Editable, all you need to do to invite others to work on the note is to send them the note's URL. On the other hand, if you want the note to be read-only, you can share it by pressing the Publish button and using the URL it generates.
HedgeDoc's user interface (Figure 4) is as simple as it is functional. The toolbar located above the text input offers all the common formatting options, from bold and italic to lists, links, images, and tables. While these tools are great for beginners, expert Markdown users will rarely use them because typing the Markdown codes is faster. However, the tools do come in handy for all users when it comes to making tables and formatting images.
Above the toolbar, you'll find the workspace mode buttons. There are two modes for all device types: View and Edit. Clicking on the View button (the eye icon) displays only the formatted HTML text, and the Edit button (the pencil icon) displays only Markdown text. On a desktop or tablet (sorry, mobile devices), you have a third option: the Both button (the split-screen icon) shows you both the HTML and Markdown side-by-side. Rounding out the display modes are the half-moon icon, which lets you toggle between night (the default) and day mode for the menus and the HTML pane, and the question mark icon for help and documentation.
On the right side of the top bar, you'll find New and Publish buttons, a drop-down menu with some essential functions, and the Online button, which tells you how many users are working on the current document (more on this later).
Drop-down menu options of interest include Revision, Clipboard, download options, and Slide Mode, which I'll cover in the "Slide Show" section. Selecting Revision shows a note's existing revisions, with all changes highlighted, plus the option to download any revision. Clipboard lets you copy text taken from another source (a web page or document) and then paste it into your note in Markdown format.
You also have the option to download a note on your computer, saving it as Markdown, HTML, or Raw HTML. I strongly recommend saving each note's Markdown source code on your computer, unless you choose to use a script, which I'll address at the end of this article.
In my opinion, two things that could be improved in HedgeDoc's user interface are located in the toolbar. Resizing the browser window below a certain width makes some or all elements of the top buttonbar disappear. Also, the button that lets you switch between night and day mode for the Edit view is located at the very bottom of the window, instead of at the top for the other two views.
TOC, Two Ways
HedgeDoc offers two table of contents (TOC) options. You can embed a clickable TOC anywhere in your Markdown note using the [TOC]
syntax (Figure 5, item 1). Alternatively, you can use HedgeDoc's autogenerated TOC. Pressing the hamburger icon in the bottom right corner of the HTML pane (Figure 5, item 2) opens a collapsible outline. Unlike the embedded TOC, the autogenerated TOC is a part of the HedgeDoc interface, which lets you navigate anywhere in the document down to three levels of headers without adding the [TOC]
syntax to your Markdown code.

Choice of Editors
HedgeDoc can emulate three different editors: Sublime (the default), Emacs, and Vim. To switch between editor modes, click on the editor button (EMACS in Figure 5) in the toolbar at the bottom of the Markdown editor pane, and select your editor of choice from the drop-down menu that opens. Besides having its own keymap, each editing mode can collapse chapters or subchapters (when you click on the arrow symbol to the left of the header). The editors also support auto-completion for several types of markup. For example, if you type #, you will get the pop-up window with auto-completion hints as shown in Figure 6.
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
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.
News
-
elementary OS 7.1 Now Available for Download
The team behind elementary OS has released the latest version of its operating system with a focus on personalization, inclusivity, accessibility, and privacy.
-
The GNU Project Celebrates Its 40th Birthday
September 27 marks the 40th anniversary of the GNU Project, and it was celebrated with a hacker meeting in Biel/Bienne, Switzerland.
-
Linux Kernel Reducing Long-Term Support
LTS support for the Linux kernel is about to undergo some serious changes that will have a considerable impact on the future.
-
Fedora 39 Beta Now Available for Testing
For fans and users of Fedora Linux, the first beta of release 39 is now available, which is a minor upgrade but does include GNOME 45.
-
Fedora Linux 40 to Drop X11 for KDE Plasma
When Fedora 40 arrives in 2024, there will be a few big changes coming, especially for the KDE Plasma option.
-
Real-Time Ubuntu Available in AWS Marketplace
Anyone looking for a Linux distribution for real-time processing could do a whole lot worse than Real-Time Ubuntu.
-
KSMBD Finally Reaches a Stable State
For those who've been looking forward to the first release of KSMBD, after two years it's no longer considered experimental.
-
Nitrux 3.0.0 Has Been Released
The latest version of Nitrux brings plenty of innovation and fresh apps to the table.
-
Linux From Scratch 12.0 Now Available
If you're looking to roll your own Linux distribution, the latest version of Linux From Scratch is now available with plenty of updates.
-
Linux Kernel 6.5 Has Been Released
The newest Linux kernel, version 6.5, now includes initial support for two very exciting features.