I blogged last year about my switch from Markdown to AsciiDoc, and that I was using AsciiDocFX.

I still like AsciiDoc, but AsciiDocFX has been getting on my nerves:

• It doesn't have a very good update system. It checks for new versions, but it seems like I have to a) uninstall the old version, b) reinstall the new version, otherwise I get problems. I may be doing it wrong, but this made me want to update less.
• The UI is a little wonky. The live preview sometimes seem to keep its update a few keystrokes behind, meaning that the preview and the document are out of sync. It also tends to get locked up, until I click the Restore button and then Maximize button.

Still, I used it.

But, I built a new computer this week. And I've been setting up my softwares on it. I thought it might be worthwhile to see if there's an AsciiDoc plugin for Visual Studio Code. And, of course there was, because apparently the Code extension ecosystem is booming!

So, I installed AsciiDoc by Joao Pinto, since it came with a live preview. But, it requires me to actually install the asciidoc command line tool.

See?

So, I thought, that should be easy enough. I went to the AsciiDoc site and started following the directions for Windows installation.

Install Ruby

Okay, well now I need to install Ruby. Should be easy enough. I already have Chocolatey NuGet, so I'll just run choco install ruby. No problem. I know that ruby comes with gem, so I should be all set.

Install AsciiDoc

According to AsciiDoc... docs... I just use gem install asciidoctor and that should do the trick.

But, no. It's not that easy. Otherwise I wouldn't be writing this blog. I got an error message:

SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

I'm sure all you Ruby people or Mac people or whatever already know where this is going, but I had no clue. So I googled it. I found a whole bunch of suggestions on StackOverflow. Some solutions made sense but weren't for Windows, and vice versa. I eventually hit upon some random guy's Gist and SSL upgrades on rubygems.org which lead to me this page on rubygems.org about SSL updates.

Fixing RubyGems Certificate Thingy

So, following that literally:

gem install --local C:\rubygems-update-2.6.7.gem

and then

update_rubygems --no-ri --no-rdoc

and finally

gem uninstall rubygems-update -x

So, I guess that fixed... something? It's described in the gist I linked above. But I don't really understand why it's still a problem for a brand new install of ruby. Not complaining! It worked!

Okay, now Install AsciiDoc

So now gem install asciidoctor works. And now I get a live preview of AsciiDoc in Visual Studio Code.

I'll report back after some more time blogging to see if I like this, or if I eventually go back to AsciiDocFx.

UPDATE: As of early April 2017, I've been blogging this way and I'm extremely happy with it. Visual Studio Code keeps getting better, the preview plugin keeps getting better. I've had to introduce a few tweaks in my process, but I've got the whole pipeline semi-automated. It's easy to bring in code samples (thanks to AsciiDoc), easy to post to both the Couchbase blog and this blog, easy to run Yoast on it, and so on. Some day I'll write a blog post explaining the whole process (and hopefully get some good suggestions for streamlining!)

Since I'm a professional blogger now, I decided that I need to use a tool with a bit more functionality than a standard TinyMCE or CKEditor box.

I decided that Markdown was the way to go, so I installed MarkdownPad 2 (choco install markdownpad2). This worked fine for a bit, but there are a couple of issues:

• In order to embed images and preview them, I had to actually put them on a public dropbox folder and use the public dropbox URLs
• Embedding code is just a copy and paste. I can't reference another file and import the code. This means I have to manually update my md file whenever I tweak code samples.
• I had to install Awesomium in order to use MarkdownPad 2's preview feature (why?!)

THERE ARE PROBABLY SOLUTIONS to these gripes.

But what I've found is that I like the AsciiDoc format as much as Markdown, and I like AsciiDocFX way better than MarkdownPad 2.

Embed images

In markdown, what I did was put images into a public dropbox folder, and link to the public URLs. This felt darn hacky, but I couldn't figure out how to get it to point to local files (at least not in MarkdownPad 2).

With Asciidoc, I simply specify a local folder with a metadata tag: :imagesdir: images - and that tells AsciidocFX to look for images in that subfolder.

To include an image then, I just use image::filename.png[alt text goes here]. And that does it.

Import code from source files

This is a great feature that I wish I had when I was writing my book. To include a source code file right in your document, just use include::path/to/sourcecode.cs.

That will include the entire file in your document. If you just want part of a file, you can add a comment with "tags" in it. In C#, for example:

// tag::Example1[]
public void MyCode() {
}
// end::Example1[]

And then, back in AsciiDoc, use include::path/to/sourcecode.cs[tags=Example1]. Now only the code that sits between those comments will appear in the document.

This is such a great feature, because I'm always tweaking code up until the last minute before I publish. Now I don't have to worry about the blog post getting out of sync with the actual code!

Awesomium

Not needed for AsciiDocFX. So, even if you decide to stay with Markdown, AsciiDocFX still seems like the superior tool to me.

Conclusion

I'm sure there is much more to learn about AsciiDocFX and Markdown, but I'm pretty convinced at this point. I'm going to start using AsciiDocFX for blogging (and, heaven forbid, if I write another book).