Markdown All The Way

Improvements to how I use Vimwiki

I changed the syntax of my Player Information wiki from VimWiki to Markdown.

Pandoc flavoured Markdown has support for Header Identifiers; this helps keep internal links working when converting a wiki of several files into one EPUB book.

Pandoc syntax also allows better support for naming a file with no spaces in the file name, yet allowing titles that have spaces in the file name.

Where I started out

I have two wikis for my one campaign. Both run within VimWiki. One for GM eyes only used the traditional VimWiki syntax. The other, the Public Wiki filled with details for the players (a.k.a. Player Information Wiki), used MediaWiki syntax. In the Public Wiki, I intended to use the VimWiki "diary" function to build and maintain Chronicle entries.

(As a side note, when I say "Chronicle" what I mean is a record of what happened during the campaign session).

There are a few problems with this approach:

1. VimWiki has a "VimWiki to HTML" function. It only works with VimWiki native syntax. It does not work if you run your VimWiki with MediaWiki syntax. Since at the time that I started Pandoc did not have a VimWiki reader, this meant that for Pandoc to read wiki data, that "VimWiki to HTML" function was a hard requirement.
2. Running one wiki in one syntax and one in another is a headache.
3. The diary function creates a subdirectory for diary entries. Having some files in a subdirectory and others out is not an impossible issue. However dealing with links gets more complicated when your hierarchy is not flat.
4. VimWiki and MediaWiki can handle files with spaces in the name (like "Joe Smith.wiki") Shell scripting tools can, too, but it makes for an additional set of headaches.

While I love to create, edit, and delete data within VimWiki, it's not my final output. I have Vim but not VimWiki on my mobile phone. I wanted a way to review the Gamemaster notes on my phone.

I studied my use cases and decided there are three sets of output I want to create:

1. I want to collect the individual wiki files into one single ePub electronic book, for reference when the Internet is not available. I might also sell that ePub one day.
2. Most of the Public Wiki detail is going up to a MediaWiki site hosted on the Internet for my players. Maybe.
3. For the Non-Player Characters in the campaign, I have an idea for how I can create paper miniatures (or "pogs") that match print (PDF) NPC reference sheets.

All three of those I intend to treat in more detail in future blog posts. For now, I'll detail what I've changed to.

Where I am now

Today, both wikis are in Markdown syntax, specifically the Pandoc flavour of Markdown.

From Pandoc Markdown, using Pandoc, I can create any type of output I can think of with a minimum of transitions. Yes, there is a thread within Vimwiki development to using Markdown as the base markup language of Vimwiki. My best estimate is that will be a long time coming. Several of the people who use Vimwiki like the To Do List toggles in Vimwiki native syntax. To the best of my knowledge, Pandoc does not provide such a thing.

Related: As of the last two weeks, there is now a Vimwiki reader in pandoc. This is great for getting data from VimWiki to Markdown. It doesn't solve the potential problem that I might one day have something in HTML or MediaWiki format and I want to put it in to VimWiki. If that source HTML has lots of links, I don't want to break all of those transitioning from one format to another.

Thankfully:

1. VimWiki supports using a VimWiki in Markdown syntax.
2. Pandoc can read and write to Markdown
3. Pandoc can create any other format I can think of.

I toyed with using Vimwiki native syntax to turn the entire wiki into HTML, then using Calibre to take a directory of HTML files and turn that into an EPUB. I prefer to use Pandoc and Markdown, because:

1. Pandoc flavoured Markdown has great, straightforward support for internal links
2. Pandoc has great support for metadata blocks in YAML format.
3. Pandoc when creating an EPUB can create a Table of Contents with a --toc argument.
4. Pandoc can build the EPUB from the command line. With Calibre, I was launching a GUI tool.

I have a script that will sync one-way the Public Wiki content from files in MediaWiki format up to the MediaWiki site on the Internet. To get the VimWiki details from Markdown to MediaWiki, I use Pandoc. No muss, no fuss.

More

If you like what I've written here and want to help support future posts, please:

• Like or Retweet this page
• Follow me: on Twitter, FaceBook, or Google Plus
• Check out standardeyre.com
• Take a look at my contributions to the StackExchange collection of sites.
• Add a comment to this page