Blog Post Writing Workflow
07-12-17 Writing Workflow
When writing a blog post, my system (nascent as it is) uses several interesting technologies. This blog posting will discuss what I am using today, why I chose this particular technology stack, and what works / doesn’t work about it.
Updated 2007-12-20: Additional notes appended to the Scrivener and Graphics sections.
Sure, one could get away with doing nothing more than using the WordPress or Blogger web interfaces, or with using an offline application like Mars Edit.
Why not the Web Interface? A few reasons:
- Writing in a browser sucks.
- Nothing persists.
- I don’t get a local record of my writings (and have been bitten by website data loss too many times to just shrug and ignore this)
Why not use a program like Mars Edit? Another few reasons:
- Writing in the application tends to suck (I don’t particularly enjoy its brand of RTF editing)
- Local records are kept only until I publish them
- It costs extra money (not a deal breaker, which will become obvious when you see my chosen technology stack)
- Longer-form writing is nerve-wracking
Instead of either of these, I am using a set of tools I already had “lying around”, and know and love. This includes Scrivener and TextMate on the “pay” side, and MultiMarkdown, BibDesk on the open-source/freeware side.
Note, of course, that your mileage may well vary. TextMate is a great text editor, but you may instead go the route of Text Wrangler or even the built-in Text Edit for editing. Scrivener is an absolute godsend for dealing with the document at a high level, but you can do essentially the same thing using OmniOutliner if you have that laying around, or forego the outlining altogether and just manage large chunks of text in your chosen text editor.
Scrivener is a well-designed “writer’s application”. It allows a writer (ie, anyone who writes, defined without the pretense) to collect his thoughts, expand on them somewhat organically, rearrange them using a few different metaphors (outline or cork board), and eventually output a complete, cohesive work.
In Scrivener, I start writing on a topic by laying out a few points as they come to me, in the form of index cards on a corkboard. I might expand the “outline” by going into on of the index cards (which “contains” another cork board for index cards) and repeating the process. Eventually, I have what I am thinking of at first very roughly outlined out. It’s a bit aggressive to even call this an outline at this point; it is really little more than a scratch pad with some incomplete thoughts jotted down. The corkboard is a central hub: I return here again and again to jot down quick notes as I progress in fleshing out specific ideas.
With my plans, so far as they exist, down in bits, I then feel safe diving into the most “interesting” of the cards. I open it as a document and begin typing. I’ll discuss what I type and how later on, but suffice to say I’m hardly using Scrivener’s built-in RTF editing muscles here. Scrivener is my organizer, not my formatter.
Eventually, I will decide that a particular bit of text belongs somewhere else in the document. If it’s a short bit, I’ll open up the whole document as a unit and drag or cut/paste it to its proper location. If it’s a whole section, I move to the corkboard and rearrange it however makes sense. This two-layered approach is ideal for both sides: large restructuring tasks are as easy as they can be, and that facility doesn’t get in the way of more ordinary line-editing.
Once my post starts being more substantial, with text in various sections, I take advantage of Scrivener’s two “master document” features. First, to get a quick overview of the overall post, I select the post’s folder and click the “Edit Scrivenings” toolbar button. This allows me to see how the entire document flows together, and allows me to move small bits of text from section to section. On the downside, though, section headings don’t show up, and it is (obviously) not formatted like it will be when posted.
To see a more accurate representation of the document, I go to
File | Compile Draft, make sure the root folder is my current post (I keep many posts in a single Scrivener document, although I’m not sure if I’ll continue in this manner going forward), make sure both
Text are checked for
File Groups, and
Folders, and make sure the output format is “
MultiMarkdown”. All of the above settings are preserved from export to export, so this is generally just a matter of hitting the menu item then clicking “
Export”. Once I click Export, I get a standard File Save dialog; I save each blog posting in its own document in a folder, named after the title of the post; here, I either type in that title or click the file in the browser, then confirm that I really want to replace it. The exported document is then opened in TextMate for review and/or preview. Note that I can also export directly to HTML for preview via MultiMarkdown, and do this more often at the tail end of a post than otherwise.
Other more advanced features of Scrivener include status notes and keywords on each index card. I use the Status label to mark sections as “To Do”, “Skeleton”, “Preliminary”, “First Draft”, “Revised Draft”, and “Done”. These status labels appear as watermarks on the index card display, allowing a quick scan to find what parts of the document haven’t been thought through. Keywords can be used to track blogging tags with my current every-post-in-one-document approach, but otherwise haven’t found a use in this workflow.
Update 2007-12-20: I’ve taken to adding a section in each post, with “
Include in Draft” unchecked (an option in the Inspector), which houses any research notes for a particular project. When compiling drafts, the “
Include” checkbox for that section should be cleared, and I ensure that I am compiling sections “
Marked for Inclusion” (the default) as opposed to “
Not marked” or “
My writing is being done using “MultiMarkdown”.
“Markdown” is a play on “Markup” (the “M” in “HTML”). Unlike HTML, which often seems like a sea of tags with text interspersed here and there, Markdown is aimed at human-readable source code. A similar, but vexingly distinct, effort exists in Textile (which I unfortunately also have to work in as Confluence, our Wiki of choice internally at work, uses Textile as its authoring language). Someday I’ll write a pithy little sed program to translate from one to the other, perhaps.
“MultiMarkdown” is a slight expansion on Markdown. To be honest, I don’t think I’m using any of the “Multi” features here. They seem to be aimed at supporting longer documents. I only say I write in MultiMarkdown because Multi-Markdown is what Scrivener supports semi-natively, and I use its tools to compile my end drafts. For the sake of this article, consider “MultiMarkdown” a synonym to “Markdown”.
Markdown as a language was invented by John Gruber, and is most thoroughly documented at Daring Fireball. More or less, the most important bits are that it uses punctuation marks like asterisks (“*”) to denote emphasis and/or strong emphasis, allows easy list and link entry and reading, and also accepts inline HTML tags.
I use MultiMarkdown as a base format because it is:
- Easy to type in
- Easy to edit anywhere, yet supports formatting being entered while writing
- Well supported in TextMate (Command-B and Command-I do the “right thing” for instance)
- Well supported in Scrivener (index card titles get properly placed into the generated heading hierarchy)
- Future proof (text documents 4EVAR!)
In the image below, the back-most window is the source document; the middle window is a preview (opened directly in TextMate), and the front-most window is the same text in (much harder to read) HTML. The advantage of Markdown from a readability standpoint should be clear from this!
TextMate is a text editor for OS X. It is extensible, so anyone (with a bit of patience and a certain amount of programming know-how) can write a “bundle” to add custom support for just about any format of text document.
The folks behind MultiMarkdown have written just such a bundle. In fact, there is a serviceable Markdown plugin included in the default install of TextMate, although the MultiMarkdown bundle adds some niceties which make working with Markdown significantly easier.
I have installed the “Edit in TextMate” Input Manager from TextMate. So, in just about any application, I can hit Control-Command-E and the text of the document will open up in a new window in TextMate. From there, I can edit the text in TextMate, and when I hit “Save”, the text will get copied back into the main application window.
From Scrivener, I click on a section in the Binder area, then hit the shortcut to open this in TextMate. There, I type away with all the syntax highlighting, quote-matching, etc, of TextMate, until I’ve typed everything I wanted to type. Then, I close the window (Command-W), hit Enter to save, and in Scrivener, the entire contents of the section have been updated.
The process of creating WordPress graphics is fairly tedious.
In this post, I’ve included several screenshots. To take a screenshot, I use the built-in Command-Shift-4 shortcut, then hold down Control while dragging my selection rectangle. Then, I open up Graphic Converter, and use the
File | New > From Clipboard menu item. I then save this using
File | Save for Web twice: the first time as-is (with about 10% sharpening), and the second time with “Scale longest side to 200 pixel” checked and sharpening increased until the preview looks right. Each of these go into the post’s folder, with the larger image having a “-full” suffix.
In other instances, I’ll do much the same process, but with manufactured graphics from OmniGraffle. As with screenshots, I copy/paste the graphics into Graphic Converter, then save to the post’s folder in full res and (if necessary) reduced res.
No matter how the graphic is generated, I then upload to WordPress by clicking on “Write a Post”, then scrolling down the the Images area and clicking “Upload”. I upload each graphic in turn, then set “Show Thumbnail” and “Link to File”, and click “Send to editor”. Next, in the editor, I copy the link and image tags, and paste them into my working post text. Finally, I adjust the text so that the link is to the “-full” image and the shown image is to the thumbnail.
After all that, I then add an “align=” attribute to the IMG tag so that the image floats on the left or right, according to how the overall document is laying out.
Update 2007-12-20: I tend to have multiple writing projects “in flight” at a time. So, I don’t want to upload all the graphics for a particular project until I’m actually posting that project. Still, I want to be able to “preview” the posting with these images in place. Now, instead, I just save them locally to the blog post’s folder, and in the “
IMG” tag insert the local URL (which I get from the “
Copy Path > URL” menu item in Path Finder, although you could type it in manually otherwise). Since WordPress doesn’t like upper-case letters in uploaded graphics, I make sure they are all lower-case named at this point (otherwise none of the graphics will show up later on!) Then, when I’m about to post the whole thing to WordPress, I go through the process of uploading all images. At that point, I then go into Scrivener and use “
Edit | Find > Project Replace ...” and replace all occurrences of the project path URL with the WordPress base URL (not including the file name) for the images just uploaded. Finally, I move all these items to a sub-folder (“support”) of the project folder, generate the HTML locally, and verify that all the images still show up properly from WordPress. From there, the process continues as outlined below.
As I get more and more comfortable with the post as written, I start compiling drafts in Scrivener to test how it will all look on a web page. I pass through each section, making sure I haven’t left any ends untied.
Once I’m confident (enough) in the post, it is time to publish.
I compile the document to the post’s folder on my disk, first as MultiMarkdown. Then, I render the Markdown to XHTML source. Finally, I copy and paste the entire body of the post to the “code” tab of a WordPress browser window, and submit it.
Wrapping It All Up
This process seems to be working for me, at least for the time being. There are a lot of moving parts, and working with images is as far from drag-and-drop as it can be. I certainly wouldn’t recommend this for a photo-rich blog such as I keep on our family site!
Still, I enjoy the pure-text aspects of MultiMarkdown, and I really like the organizational help Scrivener affords.
Now, if only my writing were as well thought-out as the process around it!