My Markdown Workflow

01/29/2006 21:59:05

tags: MultiMarkdown, OmniOutliner, LaTeX, XHTML, PDF

This page is just to document how to fit all my Markdown related crap together in a useful manner… Works for me, might not fit your needs…

OmniOutliner

I like using OmniOutliner as an organizer/editor. My last top-level element is Metadata and it contains the metadata for the document (Title, Author, Date, Format, Copyright, and whatever else I might come up with down the road). The metadata can be used later in the workflow to automate creation of various document types.

Otherwise, I use the outline aspect to organize topics and subtopics. I use notes for the actual text of the document. The notes are written using Markdown. Well, more accurately, I suppose, it is MultiMarkdown.

You can do whatever you like within OmniOutliner (or the Pro version) to make your work environment easier. I like a monospaced font for the notes, so that it can look similar to the plain text file. I believe plain text files should be displayed in a monospaced font, but that is a totally idiosyncratic thing.

Export

I keep the document saved as a native OO file, but when ready to use it, will use my OmniOutlinerMarkdownPlugin to save the file as a plain text file using the MarkdownSyntax.

I make sure to set the Format metadata to complete so that a well-formed XHTML file is created that can be run through xsltproc. Additionally, this puts the metadata into meta items in the header.

If necessary, you can hand tweak things here, but ideally you should not have to.

At this point, I have a plain text file using the MarkdownSyntax.

Process Using Multimarkdown

(You can also start at this step with a Markdown text file created by any other means.)

I run it through MultiMarkdown, but you could use the vanilla Markdown as well (just not as many features).

I also run the text through SmartyPants in order to improve the punctuation for finished documents.

At the end of this step, I have an XHTML file.

XSLT

Now, I use xsltproc and either xhtml2memoir.xslt or xhtml2s5.xslt to convert the XHTML file into another format. These files are available on [[Markdown and XML]].

If using a latex version, I then run latexmk ¹ to generate a pdf, complete with parts, chapters, sections, and subsections (if desired). By using MultiMarkdown, there are automatic cross-references and other features available as well.

At the end of this step, I have a pdf file, or possibly an S5 slideshow, or whatever else I wanted.

End Result

From one OmniOutliner file, I can generate a plain text file, an OPML, an XHTML page, a LaTeX document, a pdf, and an S5 slideshow. Granted, you will likely want to reformat things somewhat for such disparate end-results, but it is theoretically possible to do it without changing anything at all…

Additionally, the Markdown formatted text is suitable for dumping directly into my wiki, since I use the WikiMarkdown module.

Why go through all this?

First, it’s easier than it sounds. I have a script set up that does the command-line stuff for me, so I just export my OO file to a Markdown text file, then run one command on it. But I really enjoy the benefits of being able to create one master source document, with minimal, easy-to-remember formatting, and then being able to use it to create a wide range of final document types. For me, this is much easier than having multiple versions of the same document, and having to hand synchronize them. Additionally, I like the fact that I can write a complex document without paying much attention to formatting, and then let LaTeX fix it up into a nicely formatted pdf.

Other options

You can also work with [[Markdown and RTF]].

Bugs

There appear to be some issues with S5 that I am attempting to resolve with Eric Meyer, and the xhtml2s5.xslt stylesheet isn’t very smart. But technically, it works. ;)

Automator

I have not used Automator (included with Mac OS 10.4) too much, but decided to play around with it to help with some processing workflow. When combined with OmniOutliner (or not), and with MarkdownDragAndDrop, it’s quite powerful. I have a few documents that I like to change the \HeaderLevel on when exporting from OmniOutliner, and I am able to do that automatically with Automator…. It takes some experimenting, but it can be quite powerful. I simply drop an outline onto the Automator application, and it exports it as Markdown text, processes it with MarkdownDragAndDrop (including any included images and bibliographies), and out pops a pdf. Not too bad!

The steps I use are:

Open Files in OmniOutliner
Find Related Rows - last child
Filter Rows by Text - topic begins with Metadata
Find Related Rows - every child
Filter Rows by Text - topic begins with \HeaderLevel
Set Value of Named Column in Rows - Note to New Value: #
Set Selected Rows
Outlines Containing Rows
Export Outlines - to my home folder named “Automatic Build Document” formated as Markdown (With Attachments)
Close Outlines - without saving
Get Specified Finder Items - “Automatic Build Document/index.txt” (set to Ignore Results from previous action)
Open Finder Items - with MultiMarkdown2PDF - Memoir

This is my most complicated version - to demonstrate what can be done. I don’t generally want my outlines to use “Parts” in the memoir format, so I bump the \HeaderLevel by 1 when using the memoir class. This Automator action does it automatically, and you can save it as a Finder Plugin for easy access…. I’ll have to keep looking into what can be done with this.

I use latexmk because it automatically runs pdflatex the proper number of times, based on what needs to be done. For instance, if you have cross–references, an index, a bibliography, and glossary, it's going to take a few passes to get everything straightened out. Rather than guessing at how many times to run pdflatex, latexmk runs it the proper number of times. ↩