Content Workflow Using Github And Markdown

Table of Contents

• The Four Rules Of Content Workflow
• Setting Up Your Tools
• Getting Ready To Write
• Writing
• Committing (Saving) Your Work
• Publishing
• Repurposing
• Resources

TL;DR We publish digital content. We write and create for the internet and screens. But our content workflow dates back to the days of desktop publishing. This post suggests a better way that uses Github and Markdown. It gets away from word processors and folders, helping you create content that’s ready for reuse. It uses readily available tools that won’t bloat your work or lock you into proprietary formats. Read on for a step-by-step walkthru. With a few stops for ranting and raving.

A couple years ago I measured how I spend time when writing. I wanted to see where/if I could tweak my content workflow. The result was so depressing I wore the same pair of cycling socks for a week:

It takes me about 90 minutes to write a 750-word blog post. In that time, I spend:

• 45 minutes writing
• 15 minutes editing
• 30 minutes doing… what exactly?

Wait. What? That can’t be right. I spend a third of my time on a writing project not writing.

What. The. Actual. Fucklebucket.^*

So I checked my notes.

33% of writing time is sucked out of me by time-wasting stupidity:

• Flailing around, trying to clean up a formatting problem in a blog post
• Troubleshooting software problems
• Digging up the second version of my intro, which I think I liked better than the fifth and sixth, but I honestly can’t remember because I usually just delete and type over stuff
• Trying to figure out how the hell I create a smart quote
• Reformatting a whole Word doc because the editor wants it in Google Docs format
• Recapturing images because they’re all embedded in the document, and they look like poo

All these examples fall into two groups: Formatting and version management. Both are our jobs. Even if we have our own editorial and design team

HAHAHAHA DID I JUST SAY THAT BECAUSE YEAH SURE I HAVE 3 PEOPLE AT MY BECK AND CALL JUST TO MAKE SURE MY STUFF LOOKS GOOD HAHAHAHAHAAAAAAA cough sniff

we’re responsible for the first pass. Formatting and version management is part of our job.

And we suck at them.

We worry about flinging the next blog post over the wall, instead of creating versatile content that we can publish anywhere and reuse anytime.

We’ve Got Problems

We think about decoration first, structure second.

We worry about flinging the next blog post over the wall, instead of creating versatile content that we can publish anywhere and reuse anytime.

We save five minutes now and cost ourselves hours later.

We spend our time on writing, editing, and publishing. But we ignore the stuff that moves content between those steps: Workflow. So our workflow is riddled with potholes and broken glass. We still have to move from writing to editing to publishing. But instead of helping, the workflow slows us down.

An Outdated Workflow For Outdated Tools

We’re working on the internet, but we use tools created for desktop publishing in the 1980s. Yes, even you fresh-faced youngsters with healthy backs and no ear hair are using the software equivalent of antiques.

I’m talking about Word Processors. Word processors weren’t designed for writing. They were designed for typing and decorating. Word, Google Docs, and their devil-spawn relatives were designed to bring bold type and Comic Sans to the masses. They are not designed to help writers create, manage, and publish structured content.

I’m also talking about storage. Files saved in folders—online or off—are a metaphor for paper and filing cabinets. They’re about as useful as the corded phone I now use as a doorstop. They were created so that one person (maybe two) could work on one piece of content at a time.

Sure, there are tools out there that claim to update all of this, streamline workflow, etc. They all become bloated, expensive versions of the word processors and dated storage metaphors they try to replace. Fancier potholes. Prettier broken glass.

So poof. A third of my time gone because I’m spending my time in Dropbox and plinking away in Microsoft Word and Google Docs.

We need a better way to do this.

Find A Better Way

This is what I’ve worked out: A workflow that creates structured, reusable content. It lets me manage versions across devices and multiple writers. And it works well for 750-word blog posts as well as chapter books.

Most important, it lets me spend more time writing.

There’s a nice benefit to all this, too: Your writing looks better on the web. Let’s face it: Most of us write for the web. We’re publishing blog posts day in, day out. Use this workflow and your writing is web-ready (I hate that phrase, but it works here). It looks better, loads faster, and gets view source-ing HTML geeks like me nodding with approval.

Feel free to try all or some of it.

Also feel free to hunt me down on LinkedIn or Twitter: @portentint and https://www.linkedin.com/in/ianlurie/

The Four Rules Of Content Workflow

First, a successful workflow has to follow these four rules:

Structure > Format And Design

Structure matters more than format or design: The fact that you have say, a level one heading is more important than exactly how that level one heading looks, because it may look different on various platforms.

You can pour well-structured content into lots of different formats, from Microsoft Word to HTML. You can easily change the design of well-structured content using CSS or any other templates, including Microsoft Word and Google Docs.

You can also easily repurpose well-structured content, adapting it from prose to presentation to script.

So a good content workflow has to support structure first, format and design second.

Proprietary Tools Are Traps

Tools—word processors, for example—trap us with proprietary formats. They also trap us on specific devices.

Yes, I can open a Google Doc or Word file on my phone. Yes, I could edit it. But I won’t, because it’s awful.

I need a cross-platform process that’s as tool-independent as possible.

Repurposing Is Inevitable

Smart content creators re-use their work.

• E-books become blog series
• Blog posts become slide decks
• Transcripts become blog posts
• Word documents become Google Docs become HTML

I’m going to repurpose content. My workflow has to support that.

Good Writers Are Orderly Hoarders

I always seem to delete an old file moments before I need it. Or I forget why I made an edit. Or I edit in circles, ending up back where I started.

We need to keep everything for every project:

• All revisions and drafts
• All image files
• All other supporting files
• The full change history for all of the above

And we need to keep it in an organized format.

Setting Up Your Tools

You only have to do this work once. If you’ve never used these tools, there’s a learning curve that feels pretty short if you’ve been using desktop software.

Still, it takes a little patience to install new stuff. Take the extra time now, and you’ll save hours later.

Install Markdown Tools

First, you’re going to work in Markdown. I’ve already written about why, so I won’t waste too many words on it here. Markdown is a super-simple markup language that’s perfect for writers. Everything you’re reading right now started as Markdown.

There’s also a great tutorial here and a syntax cheatsheet here.

You can write Markdown using a plain text editor, then preview and export it to other formats, like HTML.

But there are a few Markdown-focused editors that make it easier. They still use plain text—no proprietary formatting—but they flatten the learning curve. My favorite is Typora.

Typora

Typora runs on OS X, Windows and Linux. Type in Markdown and Typora gives you an instant preview. So if I type:

# Typora

It instantly turns that into a level one heading “Typora.”

Download it here: typora.io.

Note: When you install Typora, go to Preferences or Settings (depending on the operating system). Find the Markdown tab/settings. Make sure you uncheck “Smart Quotes:”

Typora is filled with all sorts of other niftiness, like key combos to add links and set headings. Be sure to explore it.

Other Options

I also really like:

• Dillinger.io
• iaWriter
• Ulysses

And my longtime favorite, atom.io. Atom is a pure text editor, so it’s not as friendly, but it’s fast as heck and easy to customize. If you want to get nerdier, that’s your best choice.

You can use a standalone preview and export tool like Marked 2, or automate advanced templating and batching with Pandoc (very steep learning curve, very powerful). But for 99% of your work, Typora’s export features will work just fine.

Set Up Version Control With Github

Rule of Content Workflow Number Four: We need to be orderly hoarders. To do that, use Github.

Developers built it to support developers. But what do developers do? They type stuff into files. They save the files. They manage versions of those files while lots of other developers edit and contribute.

So this tool they built is perfect for writers, too. And while it looks scary, it isn’t that hard to learn.

1. Install Git on your computer. You can get the Windows installer here and the OS X installer here. If you’re on Linux, I’ll assume you know what you’re doing.
2. Go to github.com
3. Set up an account
4. Download the Github desktop client

You’re all set.

Git will let you track changes with far more detail than Microsoft Word, and pass your work around for simultaneous revisions or contributions by lots of other people.

It’s also close to bulletproof, which you’ll really appreciate if you’ve ever used the revision tracking in Word, Google Docs and other tools.

One Last Gadget

Go get TextExpander. Yes, it costs a little money. It’s worth it.

After you install it, subscribe to this snippet group:

HTML Entities

It’s where I keep the shortcuts I use to create smart quotes and such. They’re handy if you’re in a hurry or can’t remember the HTML entity for a smart right quote (like me).

What You’ve Got

You’re ready to follow all four rules of content workflow:

• Markdown and Typora help you create structure
• You’re not using any proprietary formats
• The resulting content will be easily repurposed from one format to another
• Thanks to Github, you’ll be an orderly hoarder

Hopefully, this whole process didn’t take more than fifteen minutes. If it did, I apologize. Please throw empty beverage cans at me the next time you see me. Empty ones. It’s not like I stole your car or something.

Getting Ready To Write

I’ve got lots of steps here, but this takes about five minutes, start to finish:

Step 1: Create Your Work Folder And File

Your work needs a home. Create one in advance. I’m writing this to prep for Learn Inbound. I’m going to have images and some supporting files.

Now, create your markdown file.

1. Create a folder where your work will live. I’m writing this to prep for Learn Inbound. I’m going to have images and some supporting files. I create folders accordingly
2. Open Typora
3. Click File >> New
4. Save the file in your work folder. You can name it whatever you want. I’m not feeling all that creative, so I’ll name it “post.”

You’ll end up with this:

For bonus points, in Typora, click View >> Outline and you’ll see a nice heading-based outline of your work as you write. It’s a structural view of your content. And structure is what we’re all about, right?

Step 2: Create Your Github Repository

Git is pretty intimidating until you break it down into steps:

1. Open Github Desktop
2. Click File >> Add Local Repository
3. Choose your work folder
4. If Github Desktop asks, click create a repository here

   

5. Click Create Repository or Add Repository as relevant
6. Github does its thing. If you look in your folder and can see hidden files, you may see some stuff like this. They belong there. Let them go on with their lives:

   

7. You’ll also see the repository appear on the left, much like this:

It won’t have the lock until you push the repository to Github.com.

Now that you did all that, here’s a tip: You can also create a repository by dragging a folder into Github Desktop. But if you do, I deny all responsibility. I’ve had very odd results with drag and drop. Which is reasonable from a tool built by folks who probably haven’t used a mouse in 20 years. I say that with the utmost respect and awe.

Step 3: Put Your Repository On Github.com

So far, you’ve got a Github repository on your local computer. That’s not all that helpful. Now you need to “push” all of this up to Github. That way, your files are backed up, you can retrieve them anywhere, and you can have other folks work on your writing.

1. In Github Desktop, click the Publish Repository button. Here’s what it looks like on OS X:

   

2. Check Keep this code private
3. Unless you’ve set up a Github organization or have an enterprise account (you’ll know if you do), don’t change any other settings
4. Click Publish Repository
5. If you’re not logged into Github, you’ll get a login prompt.
6. Github desktop pushes files up to the cloud and creates a repository on your Github account

Done. If you want to geek out, log into github.com. You’ll see that your new repository is all comfy and cozy:

Large Projects

Github kicks buttocks if you’re creating something large and complicated. If you’re working on a big project, you’ll want to do a couple other things:

1. Add a readme.md. it’s a special file that Github will show as part of your project’s “home page.” It’s an excellent place to make notes for the rest of the team
2. Invite others to the repository. Sharing is caring (the kind of thing I write on a Sunday when I’ve rewritten this post five times)
3. Learn how branches work. I wrote a very short bit about that below. Someday I’ll write a separate post

What You’ve Got

You should now have:

• A home for your work, both on your desktop and on Github.com
• Your first files

Between that and a few bathroom breaks, you’ve spent about ten minutes.

Now you can write!

Writing

You know what to do. Write stuff. Add images and whatever else you need. A few time- and sanity savers:

Structure

Remember Rule Number One: Structure is more important than format.

Use the handy outline on the left side of Typora for an at-a-glance structural view of your content:

If you’re working on a large, multi-file project, you can change the outline to a file tree. Then you can see all text and Markdown files. I’m an outline fan myself.

Syntax

This isn’t a guide to Markdown. You can find that here.

But follow these guidelines:

Headings

Headings are the core of good structure. Web browsers, search engines, word processors, presentation software and most other content tools convert headings into content blocks and outline elements. You must use them.

When you create a heading, use this syntax:

# Heading 1

## Heading 2

### Heading 3

And so on. That creates real, structural headlines.

In HTML, that markup becomes proper markup for each heading level:

<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>

And so on. In Word, it will become a proper Heading 1, 2, 3. In Powerpoint, proper headings become the outline of slides and slide headings.

Psst: Typora also has a handy key combo to set headings. On OS X, CMD+1 creates a level one heading. CMD+2 creates a second level heading. And so on. On Windows, use CTRL+1, etc.

Lists

Lists are the next-most-important structural element. Lists in HTML are a pain in the butt. Lists in Markdown are easy:

* List item 1
* List item 2
* List item 3

Becomes:

• List item 1
• List item 2
• List item 3

For numbered lists, replace * with numbers.

When you export to HTML, Typora will convert the Markdown list to correct HTML markup:

<ul>
 	<li>List item 1</li>
 	<li>List item 2</li>
 	<li>List item 3</li>
</ul>

It will also generate a proper list in Microsoft Word, RTF, etc., applying any styles you’ve created for lists.

Tables

This is a good reason to use Typora. In Markdown, tables look like this:

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Row 1    |          |          |
| Row 2    |          |          |
| Row 3    |          |          |

I take one look at that and my brain throws up in its mouth.

Typora has a nice WYSIWYG tool that lets you create and manage tables the same way you would in—dare I say it—a word processor. Hey, Microsoft Word is good at a few things.

Those tables convert directly to HTML, .doc, etc.

Images

Since Markdown files are text, you don’t embed images directly in them. Instead, you use some code to point to the image:

When you convert your work to .doc, Google Docs or PDF, the converter embeds the images. But if you’re converting this all to a blog post on, say, WordPress, you’ll have to insert the images again.

Bummer.

You should still insert the images. That way you can see them and get an idea how they’ll look in the final document. And, when you generate formats other than HTML, the images will come along for the ride. Yes, you’ll have to insert them again in WordPress. But it’s fast since you already have all the images in a nice, neat folder on your laptop.

Again, Typora makes inserting images quite a bit easier: Click Format >> Image and it inserts the code, as well as a nice file dialog so you can select the image.

Links

Links use the same code as images, but remove the “!”

[Link text here](https://www.portent.com)

Becomes

Link text here

Note that Typora automatically previews the link for you, hiding the code and replacing it with the link text.

TextExpander, Smart Quotes And Entities

This isn’t a structure thing. It’s all about Rules Two and Three: Proprietary tools are traps, and repurposing is Inevitable.

There are dumb quotes:

" A dumb double quote

' A dumb single quote

And there are smart quotes:

‘ A smart left single quote

’ A smart right single quote

“ A smart left double quote

” A smart right double quote

There are hyphens and en and em dashes, ellipses, and all sorts of other smart symbols. They look a lot better than straight quotes, and they’re easier to use than hand-coding trademarks and long dashes.

To correctly show smart characters In HTML, you need to use entities. For example, ‘ shows a smart left single quote. Entities will convert correctly from Markdown to HTML, to Word, and to all other formats.

But I just hit 50 years old. I can’t remember that ‘ is the entity for a smart left single quote. I can’t remember where I left my bike helmet.

That’s where TextExpander comes in handy. If you grabbed the snippets collection I linked to above—here it is again—then you have a shortcut.

If you need a smart left single quote, type .ldq+TAB. TextExpander will turn that shortcut into “. It will do the same for ellipses (.ep) and a bunch of others. You can browse the snippet collection to see what’s available. If you need something else, let me know, and I’ll add it.

You can use TextExpander for other stuff. Go read up on it. It’ll save you more writing time.

I wrote a post way back about little things to make your content better. Smart quotes were part of it. Have a look.

What You’ve Got

You’re creating structured content without proprietary tools or formats. It’s ready for publishing to multiple formats. You’ve nailed every rule of content workflow.

Time Saved

Because you’re writing for structure, you can type your brains out, creating headings and such, without worrying about how your content will look. Your work will apply whatever template or CSS is waiting for it when you publish.

My rough math: Working in Markdown saves me about 10 minutes for every hour of work on a writing project.

Committing Your Work (Saving, Sort Of)

Remember, all good writers are hoarders.

The cool kids call it “committing,” not “saving.”

Set whatever editing tool you use—Typora or something else—to autosave, of course. But that just saves your work to the original file.

It doesn’t do any nifty cool version management, and it doesn’t push it to Github, where the file can hunker down all nice and safe with all the related image files, support files, etc. etc.

Whenever you finish a section, or a draft, or take a break, use Github Desktop to commit your work. Committing saves a snapshot of every file in your project, including your Markdown.

I just finished writing this section. One of my cats is demanding a tummy rub. Before I give that tummy rub and she flays me alive (which she will), I commit my work:

1. Open Github Desktop
2. Make sure you’ve selected your project as the current repository:

   

3. If you’ve been working and committing changes for a while, you’ll see all sorts of neat stuff. A list of changed files (1), notation showing text you’ve deleted (2), text you’ve added and older changes (3):

   

4. Look at the lower left corner of the Github Desktop window. See the field that reads “Summary (required)?”

   

5. Enter a label for this snapshot. I usually use a short phrase that indicates where I stopped, like “Just finished first draft of committing work section.” You can enter a description too if you want.
6. Click Commit to master. “Master” may be a different word depending on the branch (another concept for later). 99.999% of the time, it will read Commit to master.
7. Github Desktop saves a snapshot of every file as it exists right now, with your label.

That’s it. I go pet my cat, then use Neosporin after she tries to rip my arm off, then get back to work. Next time I take a break, I’ll commit those changes. And so on.

Here’s why you do it. And pay attention, because this is freaking awesome. I can now see every commit in Github Desktop, down to the individual edits I made. I can zip up and down the History, going all the way back to the very beginning of my writing.

How Github Can Save Writers Time

I wrote a whole funny metaphor about monkeys and cork and rocks. I crack myself up. But it has no place in a written piece that’s already too long, so I delete it.

I do want to use it in a talk I’m giving at Learn Inbound. So I delete the whole section, then commit the change:

I can retrieve it later and, if anyone else ever reviews, they can see what I did and why.

I can also recover files that I may have deleted.

Pushing Your Changes to Github

You’ve got everything committed on your computer. That won’t do much good if:

• Your computer goes flying out of your backpack while you’re biking home (happened)
• That ONE TIME you decide not to take your laptop on vacation, you suddenly remember you need to add a section to your piece (happened)
• You want someone else to have a look, but you can’t email a copy to them (happened)
• You hate what you wrote, decide to start over, delete everything in a fit, then have regrets (never happened)

You need to “push” your changes to Github.com:

1. In Github Desktop, click Push Origin:

Actually, it’s a one-step process. You’re done.

Every change you’ve committed is now uploaded (“pushed”) to Github.

At the very least, it’s the best backup ever.

But it’s a heck of a lot more than that. These are a few things you can do. I won’t go into the procedures for each. Knowing they’re available is enough for now:

• Provide three copies of your work to three people, let them edit independently, then compare and merge changes
• Retrieve your work anywhere, work on it, and then check it back in
• Recover an image you deleted a month ago
• Automatically publish when you push to Github (ooooohhhh ahhhhhh)
• Automatically push to Github when you publish (ooooh ahhhhhh)
• Publish entire books on Github

Neat.

Showing Off: Team Workflow With Github

Say you want to hand your blog post to the rest of your team for their review. What do you do?

Most people cut-and-paste the blog post into Word or Google Docs. The other writers make their edits using Track Changes or Recommendations mode. Then you review and accept/reject each change and make the corresponding change in your original HTML, text, or other format.

Eesh.

Instead, pass your Markdown file to your teammates. Let them edit it. Then check in their changes and accept or reject them in the original.

To do that:

1. Share your project with your teammates
2. Create a branch for each teammate
3. Let them do their work
4. Compare branches with flagged changes
5. Accept or reject them, branch by branch
6. Merge the branches back to the original “master”

No cutting-and-pasting to and from Word or Google Docs.

It’s a little more complicated than this. If you reach a point where you’re using team-based workflows, take the time to learn how branching works. For now, put a bookmark here. Understand that it’s possible, and that you’ve got the tools in place to support it.

What You’ve Got

You now have a rock-solid backup and save toolset. You can be an orderly hoarder, following Content Workflow Rule Four. You can support more complex team workflows later on.

Time Saved

Github Desktop lets me hoard every change I’ve ever made to any file in this project.

Yeah, I get a little excited thinking about it.

Time saved: I’ve spent an hour or two trying to track down a note or a change, or replacing lost images, video, or attachments. This ensures I never have to do that again.

Publishing

After all that, it’s time to publish.

If you’ve followed this workflow, you have content that’s structurally sound: You can drop it into any template in Word, Google Docs, InDesign, or on your website or blog. Your writing will adopt the template or CSS of the document or site. You can publish your content to many formats from a single source with no (or at least very little) time spent formatting.

Time saved: Gobs and gobs.

Exporting to HTML

You can export using Typora’s built-in tools one of three ways:

If You’re Publishing On WordPress (Or Another CMS)

If you’re publishing on WordPress or any other CMS that allows HTML input, you want to cut-and-paste HTML straight into the WordPress editor:

1. Select the entire piece. You can use Select All or whatever key combo selects all
2. Click Edit >> Copy As HTML Code
3. Paste the result into WordPress

You’ve just pasted in nice, clean HTML. Insert your images, and you’re good to go.

You’re going to ask about the new Gutenberg editor. It’s coming to WordPress. It doesn’t support Markdown all that well. But we’ll see: It’s still in very early Beta.

Saving HTML For Publishing Anywhere

If you’re publishing anywhere at all, you can export HTML:

1. Click File >> Export >> HTML (Without Styles)
2. Name the file
3. Poof. You have HTML. With images and all sorts of goodies:

The image is uncompressed and unsized because I left it that way. I know Repurposing Is Inevitable (Third Rule Of Content Workflow). For now, I’m leaving my images alone.

Typora generates stripped HTML: No CSS, no formatting of any kind.

Saving HTML With Formatting

You can also save HTML with CSS. Click File >> Export >> HTML.

Typora generates HTML using whatever theme you used.

“Themes” are different HTML templates you can apply to your writing right in Typora. Click Themes in the menubar. You’ll see different options. Try ’em. It won’t break anything.

If you export HTML with styles, Typora uses the theme as your template.

And yes, you can create custom themes. That’s a whole other post or six.

Advanced HTML Creation

If you want to get fussy, install Marked 2, then open your Markdown file in that and select Edit >> Copy HTML Source. That gets you the most pristine, publishing-ready HTML, complete with proper heading IDs and entities. So far the only person who’s ever noticed the difference was me, though. Unless you’re my kind of crazy, Typora will work just fine.

A Quick Note About Typora And “data-breakpage”

Typora inserts this weird bit of code into all H1s:

<h1 data-breakpage>

I’m honestly not sure what it is. I should probably know. I don’t. I don’t like loose ends, so I usually delete it. If anyone figures out what it’s for, let me know.

Exporting To Other Formats

Typora natively supports lots of formats. Click File >> Export and you can see a list. Notable formats include:

• PDF: Uses the theme you’ve selected. That’s rarely ideal, so I recommend exporting to Word. Apply whatever Word template you’re using, then save that as a PDF
• Word: Uses whatever your computer’s default Word template is (normal.dot). You can then copy-and-paste into another template, or use Word’s style management tools
• RTF (Rich Text Format): Great for pasting into Google Docs
• Open Office: If you’re a rebel
• Epub: Export straight to ebook format

Because your content is well-structured—headings are headings, bold is bold, lists are lists—you can apply whatever templates you’ve created.

Advanced Publishing With Pandoc

Pandoc is a super-advanced document converter. Here are a few things it can do:

• Publish to multiple formats at once: For example, you can generate PDF, HTML, and Word with one command
• Publish to Word using unique templates
• Publish to HTML using specific templates
• Publish lots of files to multiple formats

Here’s a quick example: I write lots of little documentation snippets for my team. These snippets are 5–10 sentences, with images. There are dozens, and I edit them all the time. I then provide them in Markdown, HTML, Word and Google Doc format. I use Pandoc to regenerate and export all four formats from a single set of files.

I also use Pandoc to publish to HTML and ebook format simultaneously.

Pandoc is complicated, though. It’s a command-line tool with a steep learning curve. Use with caution.

What You’ve Got

You’re now a publisher. From your single Markdown file, you can deliver HTML, Word, PDF and whatever else you need. You can do it without proprietary tools, and you can easily repurpose: Your publishing process follows Rules Of Content Workflow Two and Three.

Time Saved

Any time you move content from one format to another, you’ve got trouble:

• Publishing to HTML from Word, you have to resize images and clean up formatting
• Publishing to Word or PDF from HTML (it happens), you have to reformat and restructure your content to fit the target template

It’s a pain in the tuchus, and it wastes time. You save all of that by starting in Markdown and publishing to your various formats from there.

Repurposing

Beating this to death:

If I decide six months from now to publish this post as an ebook, I can do it from Typora by clicking File >> Export >> Epub or PDF. I won’t have to reformat anything.

If I want to republish on another website, I can do that, too, generating clean HTML that’s cut-and-paste ready.

I can generate a nice, neat outline in OPML.

I have pure, structural content I can move from format to format without breaking a sweat.

So What?

You just followed me down the nerdy rabbit hole, jumping from Markdown to Github and back again.

Why bother? Why not keep using Microsoft Word, and writing directly in WordPress?

Time.

No one gives us enough time to write. If they did give us enough time, we’d want more of it.

Once you settle into this workflow, you’ll be more efficient. You can write more and spend more time polishing what you write. You’ll create better stuff.

This is a content workflow that might take us from the Age of the Word Processor—the age of boldface and comic sans—to the age of digital-ready structured content. And it makes us better writers at the same time.

What’s not to like?

Get In Touch (Really)

I’m a digital marketer. I don’t earn a living setting up content workflows. Contact me with questions, and you’ll only get advice. No pitch: @portentint and https://www.linkedin.com/in/ianlurie/

Resources

Butterick’s Practical Typography
Little Things To Make Content Better
Markdown Syntax Guide
Typora

^* “Fucklebucket” is a rated PG version of f–k. I came up with it once when, in front of my six and eight-year-old kids, I burned my finger on dry ice and started to drop an f-bomb. It was a pretty good save, I thought.