Content Workflow Using Github And Markdown

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.

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.

Other Options

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.

One Last Gadget

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.

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

Open Typora

Click File >> New

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?

Outline View In Typora

Step 2: Create Your Github Repository

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

Open Github Desktop

Click File >> Add Local Repository

Choose your work folder

If Github Desktop asks, click create a repository here

Create a new repository in Github Desktop

Click Create Repository or Add Repository as relevant

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:

Ignore these

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

Git repository, added to Github Desktop

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.

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

Publish repository from Github Desktop

Check Keep this code private

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

Click Publish Repository

If you’re not logged into Github, you’ll get a login prompt.

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:

Your content project, on Github

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:

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

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)

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:

Outline view shows me where I'm at in the content structure

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

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:

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:

Adding an image in Markdown

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

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, &lsquo; 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 &lsquo; 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 &ldquo;. 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

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:

Open Github Desktop

Make sure you’ve selected your project as the current repository:

The current repository

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):

Current Repository

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

Entering a summary into Github

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.

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.

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:

Deleting a section, then committing the change so i don't forget

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:

In Github Desktop, click Push Origin:

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:

Share your project with your teammates

Create a branch for each teammate

Let them do their work

Compare branches with flagged changes

Accept or reject them, branch by branch

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:

Select the entire piece. You can use Select All or whatever key combo selects all

Click Edit >> Copy As HTML Code

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:

Click File >> Export >> HTML (Without Styles)

Name the file

Poof. You have HTML. With images and all sorts of goodies:

HTML exported from Markdown, using Typora

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:

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.

Resources

* “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.

CEO & Founder

Ian Lurie is CEO and founder of Portent and the EVP of Marketing Services at Clearlink. He's been a digital marketer since the days of AOL and Compuserve (25 years, if you're counting). He's recorded training for Lynda.com, writes regularly for the Portent Blog and has been published on AllThingsD, Smashing Magazine, and TechCrunch.Ian speaks at conferences around the world, including SearchLove, MozCon, Seattle Interactive Conference and ad:Tech. He has published has published several books about business and marketing: One Trick Ponies Get Shot, available on Kindle, The Web Marketing All-In-One Desk Reference for Dummies, and Conversation Marketing.Follow him on Twitter at portentint, and on LinkedIn at LinkedIn.com/in/ianlurie. Read More

You Might Also Like

14 Little Things to Make Your Content Better

Why I Use Markdown, & You Should Too

Making amazing content: The links

1 Comments

Hi Ian, nice writeup. Given your interest in modern tools, modern workflows, markdown and Git I thought you might like to take a look at https://gitpitch.com. The Markdown Presentation Service on Git. It mirrors and extends many of the ideas you explore in your article. Cheers, David.