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
Direct Download
Read full article as PDF:
Price $2.95
News
-
OpenMandriva Lx ROME Technical Preview Released
OpenMandriva’s rolling release distribution technical preview has been released for testing purposes and adds some of the latest/greatest software into the mix.
-
Linux Mint 21 is Now Available
The latest iteration of Linux Mint, codenamed Vanessa, has been released with a new upgrade tool and other fantastic features.
-
Firefox Adds Long-Anticipated Feature
Firefox 103 has arrived and it now includes a feature users have long awaited…sort of.
-
System76 Refreshes Their Popular Oryx Pro Laptop with a New CPU
The System76 Oryx Pro laptop has been relaunched with a 12th Gen CPU and more powerful graphics options.
-
Elive Has Released a New Beta
The Elive team is proud to announce the latest beta version (3.8.30) of its Enlightenment-centric Linux distribution.
-
Rocky Linux 9 Has Arrived
The latest iteration of Rocky Linux is now available and includes a host of new features and support for new architecture.
-
Slimbook Executive Linux Ultrabook Upgrading Their CPUs
The Spanish-based company, Slimbook, has made available their next generation Slimbook Executive Linux ultrabooks with a 12th Gen Intel Alder Lake CPU.
-
Fedora Linux is Coming to the Raspberry Pi 4
Thanks to significant work in the upstream, the upcoming release of Fedora 37 will introduce support for the Raspberry Pi 4.
-
New Linux Ultrabook from TUXEDO Computers
TUXEDO Computers has released a new 15" Ultrabook running Linux.
-
GNOME 43 To Bring Some Exciting New Features
GNOME 43 is getting close to the first alpha development release and it promises to add one particular feature that should be exciting to several users.