Like many people, I want to learn and use some new skills while on sabbatical. One of those skills on my list is writing in Markdown. According to the original developer John Gruber, Markdown is both a plain text formatting syntax and a software tool. I’ve been using Markdown for quite some time in R Studio. R Markdown is great for pseudo-coding, taking notes, and for including output such as tables and figures. It’s like the ultimate stats lab notebook, in my opinion.
Using Markdown for other writing is a bit new to me. Recently, I’ve begun using it within other pieces of software: Atom (for coding), Standard Notes (for note taking across multiple platforms), reText (for general writing), and here in WordPress (for writing this blog post). To me, one of the greatest affordances of Markdown is its simplicity. Also, Markdown documents can be easily rendered as .html or .pdf. This is fantastic for sharing the output as a static document.
There are some very good resources for learning to use Markdown. My main resource has been the Markdown Guide site by Matt Cone. The basic syntax is very easy to learn, but extended syntax can vary according to which Markup language is used by your Markdown application. And depending on which Markdown processor you use, various extensions support different extended syntax. It’s not as confusing as I’m making it sound (really). I recommend that you head over to the Markdown Guide site to read about it and learn more.
Markdown seems to be very popular with technical writers. In fact, one place I’ve been using it lately is in helping to write a User Guide for an amateur radio project I’ve been involved in. A group of developers is working on a new firmware for a radio that they were able to hack. This new firmware has many cool features and is constantly evolving based on new ideas, user input, and testing. Keeping up with development and use is hard, and users need a guide on how to operate the new firmware. The developers had been writing this in Word and then rendering it as a pdf, but a group of use moved it to Markdown where we can more easily (and simply) write, format, and share.
Here is an example from that project. This code:
The channel screen displays the same information in the top row, but displays the Channel name (in this example “Lee Hill”) as well as the Zone (“Home DMR”). In DMR mode the TalkGroup (in this case "ColoradoHD") will also be displayed  On both the VFO and Channel screens: Press the **Red** menu button to toggle between the VFO and Channel screens Press the **Green** menu key to enter the menu system Press **Function + Green** for quick access to the Channel details screen, which can also be accessed via the menu system. *Note:* The VFO is actually a special type of channel; hence the Channel Details screen also works for the VFO. ### Changing between VFO and Channel Press the **Function + Star** key to toggle between FM and DMR mode on either the VFO or Channel screens. ### Changing Timeslot in DMR mode In DMR mode, pressing the **Star** key toggles between TimeSlot 1 and TimeSlot 2. ### Controlling Tx power Press **Function + Right** to increase the power. Press **Function + Left** to decrease the power. Power can be set to 250mW, 500mW, 750mW, 1W, 2W, 3W, 4W and 5W. *Note:* The power output will only be correct after the operator has calibrated their own radio, as the GD-77 does not seem to have very accurate power calibration applied in the factory by TYT.
renders to this document from Markdown:
It is very easy to write the syntax for formatting and to render a nice, professional looking document. I wrote the above document in Atom, and shared it with the other collaborators through GitHub.
One other brief use case: the other day I wrote a manuscript review for a journal in Markdown using reText on my Linux laptop running popOS. That was a great experience. For me, writing reviews requires simple formatting and concentrating on the writing, and the ability to render the review as a pdf. I usually write reviews in Google docs and then “download as pdf.” This time I wrote it directly in reText and just rendered it as a pdf. The only formatting elements I needed were headers, italics, bold, and bullet lists. That’s all really easy to include with basic Markdown syntax.
Writing in Markdown is simple, fun, and renders professional looking documents. Will I do all of my writing in Markdown? Of course not. But for straightforward documents, notes, and technical work (think: lab notebook), Markdown is hard to beat.
One last thought: I’m going to make a few screencasts on using R Markdown so that I can share with interested colleagues. So look for those in this space soon.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
