Why you should write in Markdown

Posted on: Wednesday September 16, 2015

What's all this then?

I had a bit of free time this afternoon, and decided I should take a moment to talk about one of my favorite things: Markdown. In the post, I'd like to talk about what I've been using Markdown for and a few of the services and tools I've been looking at and using. Hopefully it'll be useful!

Markdown is awesome

Let's get this disclaimer out of the way up front. I <3 Markdown. I use it to write basically everything (this post brought to you by the Markdown Module ). It's not for everyone, and for publishing it's not going to replace Publisher or Pages anytime soon, especially for things with highly complex layouts.

In my case, Markdown fits my needs very well.

Writing is awesome

Since we've established that Markdown is awesome (for me), it follows that getting to write things in Markdown is also essential. Even more so when you can do things like write standard reports, books, and anything else that could potentially be published in Markdown.

Thus, recently I've been working with Gitbook - a publishing platform and node package which can convert structured Markdown files into a book, which is styled according to the default gitbook css. At Acquia, my team has also been doing a fair amount of work with using GitBook's open source node module to write reports in.

I have to say that GitBook is a pleasure to work with. I find myself spending less time having to deal with formatting quirks, and more time proofreading and writing the things I want to produce.

Why GitBook is nice

With GitBook, the way it wants you to structure your book makes it pretty intuitive to keep the file structure well aligned with the structure of your outline.

At minimum, you need a README.md and a summary.md. The summary file contains the outline of your book, chapters, subchapters, etc. This can then be used to automatically generate folders for your book to go into using the gitbook init command. Double fun, because it's smart enough to not overwrite files that already exist, so you can use it to stub out files for you while you're working.

The README serves as the summary file for the book, and appears at the front as an introduction. Both of these files are configurable by editing the book.json file and pointing them to different locations.

Want a cover? No problem. By default simply placing a cover.jpg file in that directory will produce a book cover. You can also change what this file is with config values in book.json.

Once you've written a bunch and want to convert your book into a pdf or epub file, gitbook has you covered there too (though you do need calibre installed to do it properly).

All in all, it makes my life easier since it takes away the pain of having to deal with a full-fledged Word Processor which may or may not generate things in a consistent manner.

GitBook Editor

For my workflow, I use Atom to write the book and then make use of the gitbook serve command in order to preview changes to my book as I'm writing. It's a workflow that works really well for me.

However, GitBook also provides a really slick editor that hooks nicely into their gitbook.com service (the publishing platform). It does the same kinds of things that I do in Atom, but also provides a WYSIWYG editor side pane (which Atom can also do), and a lot of nice features for speeding up editing if you don't want to just type the Markdown.

Publishing to Gitbook.com

I've not done this yet, but the whole process seems pretty reasonable. If you choose to charge for your book, you receive 80% royalties. There's also a mechanism for taking donations, however I'm not 100% sure how that works.

And now for something completely different

I'm happy to also be acquainted with the creator of Remarq, a Markdown-based report generation tool. It generates beautiful PDF reports from your Markdown content and then templates it for you based upon some configuration settings which you can generate. Basically it allows you to create super-slick looking reports without having to futz with trying to make them look pretty.

Great if you're very focused on the content of a report and want to still create something visually appealing to the report's intended audience.

I don't personally use this for anything at the moment, but it's awesome and helps push my "Markdown for everything" agenda.

In Closing

Just give Markdown a shot, there are tons of editors you can play with and get previews on, and the syntax is super easy to use. Commonmark provides a basic spec and introduction, and Github has a nice Markdown Basics page which should help a lot.

MARKDOWN EVERYTHING.