Tutorial – HedgeDoc

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.

Figure 1: The Markdown syntax supports most of the elements required by complex documents.

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

Figure 2: HedgeDoc let's you see both the Markdown source (on the left) and rendered HTML (on the right).

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.

Figure 3: As a collaborative editing tool, HedgeDoc provides several levels of access to each note.

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.

Figure 4: The HedgeDoc interface: Everything you need to edit and publish text, and nothing more.

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.

Figure 5: You can embed a TOC as HTML code anywhere in a HedgeDoc note (1) or use HedgeDoc's autogenerated TOC (2).

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.

Figure 6: Auto-completion makes writing Markdown even faster.