Adventures in Yak Shaving: AsciiDoc with Visual Studio Code, Ruby, and Gem

February 02, 2017 mgroves 0 Comments
Tags: asciidoc asciidocfx visual studio code ruby gem

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.


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 asciidoc 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 which lead to me this page on 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 asciidoc 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.


Matthew D. Groves

About the Author

Matthew D. Groves lives in Central Ohio. He works remotely, loves to code, and is a Microsoft MVP.

Latest Comments