Search
Search

How to Organize Your Writing with Markdown


We all do a lot of writing on our computers.

I use my computer to write blog articles (see?), documentation for work, emails, books that will never be published, And, while I was in school, I wrote lots and lots of papers. But all of this writing on the computer presents some problems. For one, how do you keep all those documents organized? Should you write them all in Microsoft Word? What about notebook apps likes Evernote or OneNote?

How should we organize, version, and format our written documents so they will be the most useful for us in the long run?

Formatting, the Problem

As I see it, the main problem with creating written documents on the computer is that you often don’t know what final form your writing will end up in. For example, I often have an idea pop into my mind and I want to start writing right away before I get distracted and forget about it. But, is this idea going to be for an article, social media post, blog, or something else? Before I even begin typing, I’m faced with a big decision. If it’s going to be a blog article, I should start a draft in WordPress. But if I’m thinking it’s going into a paper, I need to open Microsoft Word. If a book, Scrivener. Where do I begin?

I came to realize that what I really needed was to divorce content and formatting.

And the problem is exacerbated when you consider that most writing doesn’t stay in one form. I have frequently adapted sermon notes into blog articles, blog articles into teaching notes, and seminary papers into PowerPoint presentations. But it doesn’t always go smoothly. Each time you adapt writing from one format to another you have to go through the arduous process of removing all of the formatting and then reformatting it for a different document type.

And that’s not even getting into the organizational problems this presents. If I have three versions of the same file on my hard drive, which one is the “master” document?

We need a better way.

The Ideal

Several years ago, growing frustrated with this process, I came to realize that I needed to divorce content and formatting. Now, I know God hates divorce (Malachi 2:16), but this was a union conceived in sin.

Think about it. The moment you open up Microsoft Word and start typing, you begin to apply formatting. Even if you don’t touch the defaults, Word is choosing a font, adding headings, and selecting margins as you type. But why are we formatting our writing as we write it? That should be the very last step of the process, not the first.

One of the final stages in publishing a book is typesetting. The manuscript needs to go through several rounds of editing, revisions, and rewriting before they even consider what font it will use and the style of the chapter headings. We should do the same thing in our personal writing; content first, formatting last.

By separating content from formatting we turn writing into a two-stage process. This gives us greater agility in how we deploy that written content later on.

If I approach the relationship between content and formatting in this way I can solve several problems at once: I can eliminate the clutter of having thousands of formatted Word documents littering the dusty corners of my computer’s file system, I can remove the decision fatigue of having to decide the form of my document before I actually begin writing it, and I can have a repository of “master” documents which are format-agnostic, ready to be deployed into whatever final forms I need them in. If I ever want to rework or republish something I’ve done in a new format, I just return to the master document and re-render it.

The Implementation

So, we know we want to divorce content from formatting, but how do we implement this ideal? Thankfully, there’s an easy way using a simple language called Markdown.

Markdown is a formatting syntax which allows you to write documents in plain-text and later render them with basic formatting. From a Markdown document, you can output your writing as HTML, PDF, DOCX, etc.

1 – Begin Your Writing in Markdown

What Markdown adds to your plain-text writing is some simple syntax to indicate what different elements in your document are. For example, you can mark something as a level-one heading by using a hashtag. Level two headings begin with two hashtags and so forth. Bullet lists just need to begin with a hyphen or asterisk. To see all of the options check out this comprehensive Markdown cheatsheet.

Here’s a screenshot of an early draft of this article done in Markdown using Ulysses.

When you finally render your document, the Markdown app formats those headings, lists, and boldface according to whatever rules you’ve asked it to apply in the target document type. More on rendering Markdown in point three. But before we render, we need to get organized. Markdown can help with this too.

2 – Use a Markdown Editor to Organize

Since Markdown documents are plain-text you could just store them in folders on your computer. But I much prefer to use a Markdown editor to organize my documents.

This is Ulysses. The left column contains all the folders and subfolders I use to organize my writing and ideas.

I use Ulysses for this since I like its infinite folder structure. But there are tons of other Markdown editors which also have organizational abilities. And most of these sync across your devices. So, you can jot stuff down from your phone.

  • Drafts is a great lightweight option.
  • iA Writer works in Windows, Mac, iOS, and Android.
  • Bear is a beautiful option for the Apple ecosystem
  • And Caret is another good cross-platform option.

There are also lots of online Markdown editors like Dillinger. Or HackMD which allow you to work on Markdown documents collaboratively a la Google Docs.

Dillinger is a free online Markdown editor you can use to output Markdown in a variety of formats. It also lets you preview the results, so it’s a good way to learn Markdown.

Another benefit of organizing your writing this way is that your Markdown editor can act like a notebook, similar to how people use Evernote or Microsoft OneNote. For me, that means when I have an idea, I just open up Ulysses and start typing. And if I want to find an old written document, I know it’s somewhere in Ulysses. Using a Markdown editor keeps your writing organized and efficient.

So, now you’re writing your master documents in Markdown and you’re organizing them with a Markdown editor, but what do you do when it’s time to output that writing to a specific format and apply styling?

3 – Render the Markdown and Finish Formatting

The final step with any Markdown document is rendering it to its final format. Often for me, that means publishing my blog articles as HTML. The Markdown editor does all the work of converting my headings, links, and images to HTML formatting and sticking that into a post on WordPress.

The is the example from above rendered to four different formats and document types using temples I’ve setup. You can get pretty fancy with this. For example, in seminary, I used an academic papers template to render my markdown as a .docx file with the correct font, heading styles, and even footnotes.

But if I wanted to use that blog post as a handout for a Bible study, I go back to my Markdown document in my markdown editor and I output it as a .docx file. It does all the simple formatting for me and any additional formatting I complete in Microsoft Word.

Markdown files are plain text, but you’ll need a Markdown editor to render those files to different formats.

Conclusion

That’s the beauty of Markdown, it gives you a better way to organize, version, and format your written documents.

Another side benefit of being familiar with markdown is that even though it’s been around since 2004, it keeps showing up in new places. WordPress, for example, which I use to host this blog, recently added the ability to use markdown in the text editor. All of Atlassian’s products use it natively and GitHub has used it for years on their platform. Don’t be surprised if you see it show up in even more places.

Because of its simplicity and benefits, Markdown isn’t going anywhere any time soon. So, why not learn it and take advantage of those benefits now?

Get 10% off a 2020 NeuYear wall calendar

Slave of Jesus Christ, husband, father, and Director of Digital Platforms at Grace to You. I also blog for The Master's Seminary.

Join the discussion

7 comments
  • Excellent post! Question. I have a dissertation project and I want to utilize markdown with a reference manger. Any solutions that have worked? I currently use Ulysses and Zotero.

    • I LOVE Zotero. I haven’t set-up a workflow between Zotero and Ulysses myself, but look into Better BibTex. It works with Zotero to make citations work in LaTeX/Markdown. This guy has developed a process using that to work with Zotero and Ulysses. He also developed a menubar application to simplify the process.

      If you’re willing to use something other than Ulysses, I’ve come across some good integrations for Atom. Check this one out. Here’s one guy’s workflow in Atom.

      • That’s awesome. I’m always on the quest of streamlining my writing and my preaching. I found that Ulysses was essential to the collection of thoughts, ideas, and notes. I loved Zotero for the price and for the accessiblity. I’ll give the links a look and see how I can integrate them better. By the way, do you use Things? Did you already write one of those click-drawing lists “Essential iPhone apps”; “Essential iPad apps”; and “Essential Watch apps”. 👍

          • That’d be fun! Nothing better than those productivity apps. I hear good reviews about Things but never bit the bullet for it. I look forward to that future list. Also, perhaps some workflow ideas for preachers? Or testimonials about how people use their technology for God’s glory. Looking forward to your posts!

  • Thanks for this article! I had just heard about Markdown so this was a helpful introduction to it. Any other resources to learn more about it?

Further reading

Reagan’s Roundup (12/13)

This edition of Reagan's Roundup includes The Bible App's Most Popular Verse of 2019, 3D Printed Neighborhoods, Should I Quit My Job and Become a...

Reagan’s Roundup (12/06)

Welcome to Reagan’s Roundup, where every Friday I share links to things from around the web that I think you will find interesting or helpful in your...

Some posts contain affiliate links to products or services referenced, recommended, or reviewed. This means Redeeming Productivity may receive a small commission if you make a purchase using these links. We only link and recommend services and products we really believe in. By using our links, you are helping to offset the costs associated with producing this website.