Browsed by
Month: July 2019

Moving to Markua

Moving to Markua

I decided to move Painless Git from “Leanpub-Flavored Markdown” to Leanpub’s newer, fancier Markdown variant Markua. This wasn’t a decision I made lightly. I’ve built up a fairly slick workflow around LFM and publishing from Scrivener to Leanpub and out to the world. But in the end the benefits far outweighed the costs. Especially since the effort-cost was fairly low.

What were the Benefits?

Glad you asked, imaginary question asker! Let’s go down the list:

Future Proofing

Leanpub is putting more effort into Markua than Leanpub-flavored Markdown, which makes sense. Markua is very focused on making it easy to write books and full-on courses using nothing but a markup language. They have put a lot of thought into streamlining all the “fiddly bits” of writing, things like including images, or text figures, or code snippets, or what have you. All of these includes have features in common, and Markua reduces the differences to where including a JavaScript file is really no different from including a picture.

Easier Publishing Through Better Markup

Using Markua means I no longer have to maintain three different meta-information files:

  • A book.txt to tell Leanpub which files were in the main, published book.
  • A sample.txt to create an abbreviated sample version, to give readers a taste but not the whole thing.
  • Optionally, a preview.txt file, which would just generate a tiny little preview for you to see if your formatting was working correctly.

My fancy Python/Git hybrid solution that I wrote about last year handled the book.txt file, but I had to maintain the other two by hand, which means that I didn’t. I never really did small previews, and I never had a sample version.

That whole system is no longer necessary! I now have one book.txt file and it has one line in it:

manuscript.txt

Since I can now use markings in the text itself to dictate which sections are included in the published book, or in the sample book, or neither, or both, I simply use Scrivener’s impressively powerful “Compile” feature to output a single manuscript.txt file.

A directory containing my manuscript and that one-line book.txt now lives in a shared folder. Leanpub can grab that file when I hit the “publish” button and it all just…works. All that stuff I used to have to do with numbering folders and files and auto-generating a book.txt file? Gone. All that file juggling to keep my images out of the manuscript directory while python was doing stuff, but putting them back when python was done? A thing of the past. Things just got a whole lot easier.

How Hard Was the Hard Part?

But this was an effort, right? There was some work involved in the change, right?

Well, yeah. But not really a ton. This is my list of tasks that I put together while working on the conversion:

Change my italics

In most Markdown variants, _this_ and *this* both make italic text. I’ve used both more or less interchangeably, but I tend to find underscores easier to type. In Markua, _this_ will be the markup for underlined text instead of italics. So I had to change all _underscore italics_ to *star italics*. I do like me some underlines, but over-using them is a bad plan. As of this writing Markua still seems to be treating _this_ as italics, but I don’t want to suddenly have that change on me.

Change “Part” Markers

Easy:

  • Old: -# Part name.
  • New: # Part name #.

The manual says this will change again soon, but I can live with that. There are only four “parts” in my book anyway.

Update Chapter Headings

I include ID tags for chapters so I can cross-link between parts of my book. I had to convert those id tags from # Chapter Name {#chapter-name} to:

{id: chapter-name, book: true, sample: false}
#Chapter Name

Which looks more complicated, but is far more useful. (And I’ve automated away the complexity, but we’ll get to that.) This new version is a large part of why I decided to switch to Markua, as I mentioned above. Handling it this way makes the management of the book so much easier, and allows me to keep unwritten sections out of the published book without doing any fancy trickery with exports and whatnot.

Fix Code Blocks

The old style:

{lang="java"}
~~~~~~~~
class Stupid{
public static void main (String[] args){

}
}
~~~~~~~~

Was never super popular, even in markdown variants that supported it. The new style is basically “fenced code blocks” as used by every Markdown variant:


```java class Stupid{ public static void main (String[] args){ } }

“`

Markua also has other plans to make the whole “text figure” system more consistent with images and imported code and all manner of cool stuff.

Miscellany

Actually, that’s all I had to change. All my other markup, like asides and tips totally still work. Best of all, footnotes still work as they always have. ✅

Markua adds a lot of enhancements to asides, but they’re non-breaking, so I can add them in as I get around to revising.
In addition to normal footnotes, they’ve added an endnote notation that, should I ever want to create endnotes, I can now do that. That’s right, I can two different kinds of witty little bits o’ text.

Updating TextExpander Snippets

I use TextExpander to automate some of the repetitive parts of books, like markdown links and chapter headings. The main change was to my “Create a new chapter” snippet, as previously mentioned.

In the update process I discovered that TextExpander has cool little macros that let you choose the state of the book and sample thing without all that tedious typing, saving me of four or possibly even five keystrokes. Fancy.

Display the TextExpander UI for creating a Markua Title.

Conclusion: If You’re Using Leanpub, You Should Be Using Markua

Overall the process took about four hours, and now I’m back to writing. Aside from the italics thing my writing has stayed the same. I use the same TextExpander snippets that I used to use, they just create Markua style output now.

And my publishing workflow is drastically easier. Here are the steps it used to take:

  1. Export the files, using Scrivener’s awesome defaults.
  2. Check the files into git
  3. Commit
  4. Push
  5. Ensure that book.txt was updated correctly by my Python script. (It always was, but I’m paranoid, even of my own code)
  6. Hit the publish button on Leanpub.

Versus the new workflow:

  1. Compile the manuscript using Scrivener’s awesome compile feature. Scrivener remembers all my settings so this is literally a single button press.
  2. Hit the publish button on Leanpub.

And now I can start looking forward to all the other things that Markua can do , once the text is complete…