I publish all my posts as text (below) and audio (above). Enjoy!
I've been writing for a long time. My first published article was in 2006 in the now-defunct print version of the Linux Journal and I haven't stopped since. I've written a handful of print articles, a short computer history book, and literally thousands of online articles and blog posts over the years. I've probably deleted a good third of what I've written but my stuff is still all over the internet in one form or another. I've learned a lot over the years and one thing that many writers will tell you is that the toughest part of writing isn't writing. Okay, it is, but there’s a close second and that is transferring that writing to the many different formats that your writing partners want.
I primarily write for an online audience these days so I don't have to mess with physical layout issues anymore. But even so, my sometimes editor wants my articles pasted into a shared Google doc. My publisher wants it written in HTML for the website, and the various other people in my life who want or need to read my stuff just want a Word document emailed to them. Copying my beautiful prose to all these formats while maintaining layout and readability is a total pain in the butt, however one format has evolved over time that works for pretty much everyone and that is the Markdown syntax.
If you haven't heard of Markdown, it's a play on the term markup. Many of us are familiar with the term markup because it's not uncommon for someone to review a draft document and "mark it up" with suggested changes. It's also been adopted by the language that web pages are written in which is HTML (HyperText Markup Language). These languages work great for indicating format changes, but they have one common problem: they obscure the text which makes it hard to read.
The Markdown syntax doesn't have that problem. It is an elegant and simple syntax that leaves documents readable after they're marked up. It is useful for both writers and editors. Writers can easily format text on the fly without getting bogged down by having to periodically stop and highlight text to format it or write complex tags around words, and editors can quickly insert formatting where needed without obfuscating the text.
Here's a quick example using a header:
Example Header
Using Markdown, the syntax for this is simple:
### Example Header
Using HTML, it requires more tagging, slows me down, and makes it harder to read:
<h3>Example Header</h3>
If you've ever tried to read a document formatted with HTML tags, you know how unreadable it is. You can give it a whirl by viewing the source of this page in your browser.
Markdown support
Markdown itself can't be read by web browsers or word processors. Regardless, its strength comes from its wide acceptance across the board. For example, I wrote this post using a Markdown editor. However, in order for you to be reading it on the web, it needed to be converted into HTML. Because of Markdown's broad support, I didn't actually have too much about that. I pasted the marked down text into the Substack editor and Substack converted it to HTML for me, with exactly zero effort on my part.
If there was a need to send this document to someone else in any other format, I can send them the marked down document just as plain text. The recipient would easily be able to read the document around the Markdown syntax and while I would not publish a document like that, it's easy for editors and reviewers to make sense of the content.
Also because of Markdown's broad support, it's easy to repurpose content over time for different platforms. Markdown is plain text and there is no more pliable form of content in today's internet-connected world than plain old text. I can send this marked down text to other website editors, print media editors, and easily chop it up to use different bits of it in different places. Markdown is the O Negative blood type of internet content. It can be used by everyone.
Markdown syntax
There are a few different Markdown syntaxes but they're similar enough that the differences usually only trip up advanced users that have special needs such as formatting mathematical formulas. The vast majority of text editing involves just a few things such as:
lists
bold text
italic text
headers
Using Markdown, it's easy to format this text on the fly, without breaking stride to write tags or click the formatting options in the toolbar. Here's what the raw text I wrote looks like. It’s easily readable even in raw form.
- lists
- **bold** text
- *italic* text
- ### headers
- [links](https://example.com)But that doesn't mean you can't do extremely complex layouts with Markdown. It has a very deep syntax and you can do tables, formulas, and many other formatting miracles. There's a good Markdown cheat sheet here.
Another bonus, and possibly an unintended consequence of Markdown is that because it uses very common symbols, it can be written on a variety of devices, even those with limited keyboards. To confirm this, I wrote this entire post on my Android phone and was able to do all the formatting needed. That may seem like a silly benefit, but when you're afflicted with the writing habit, you want to be able to write wherever and whenever the idea and mood strikes. Nothing kills ideas and passion faster than shelving an idea until you're able to get home and carve out some time to sit at your computer. Many writers carry notebooks for this reason. I prefer the digital kind because ultimately I'm going to publish everything I write digitally, so I want to avoid wasting time copying ideas from a notebook to digital form.
Getting started with Markdown
Getting started with Markdown is easy. It's very popular and that's a ton of Markdown editors for all platforms, including no-friction web editors such as the one at Stack Edit. Over time, I've come to prefer an app over a website because locally installed apps tend to perform better whereas websites can get laggy and disrupt my flow.
I've used a lot of Markdown editors over the years. The one I'm using today is Joplin. Joplin works on all the devices and operating systems I use, and it allows me to neatly organize my posts into various folders depending on where I intend to publish the final work. It also has some built-in syncing ability through Google Drive, Dropbox, and NextCloud to make sure that you can get at your documents in all the places. Personally, I don't much like storing documents in the cloud for privacy reasons, so I use Syncthing to keep my documents in sync across all my devices. Nothing is stored in the cloud that way, just direct encrypted syncing between my devices. But Syncthing is a topic for another post.
Bottom line
If you want to just write and not be preoccupied with concerns about the amount of work down the road reformatting your work, or always breaking your flow to highlight text and format it, then spend an hour learning the basics of Markdown. It will pay off in droves down the road.
Markdown: The Tool All Writers Need To Master