I love Leanpub. I think it’s one of the greatest offerings presented to authors since we stopped locking people up in towers for heliocentrism.
I have had this one nagging little problem with not being able to get previews in Visual Studio Code, though.
And it turns out to be my own fault.
Structure
I’m a developer. So, obviously, I’m going to prefer to use the GitHub style of writing.
Another consequence of being a developer is a penchant for structure…
I like my methods in classes. I like my classes in modules. And so on…
I also want to be able to structure the parts of a book… Separate frontmatter from backmatter, one chapter from another.
The logical way to do this is with directories, but that messes with you in a subtle way.
One Markua File to Rule them All
Leanpub does support subdirectories, but not in the way that I thought.
A developer working in Visual Studio Code on a Git Repo expects the paths for references to other files in the same source repo to be relative to the file.
That is not the case for a Leanpub repo. I suspect that this is because a single Markua document is generated by concatenation and then that document is turned into a book. I seem to recall that being written somewhere, but I can’t find it, now.
Anyway, whatever the actual reason, the paths to resources are processed relative to the manuscript/ folder (or relative to manuscript/resources/, if you don’t include resources/ in the path.
A Simple Solution
The solution was to flatten my directory structure and use filename prefixes to create the kind of structure I need.
Once I did that, and made sure all of my paths included the resources/ element, the previews in Visual Studio Code started working and the book kept compiling just fine.
Doing so has made my life a little easier. If you’re reading this post, you must have the same problem I did. So I hope it makes your life a little easier, too.