Adventures in Yak Shaving: AsciiDoc with Visual Studio Code, Ruby, and Gem
Tags: ruby, visualstudio
Published: 2017-02-07 17:24:08

---
title: "Adventures in Yak Shaving: AsciiDoc with Visual Studio Code, Ruby, and Gem"
published: true
tags: ruby, visual-studio
---

<p><em>This is a repost from Cross Cutting Concerns: <a href="http://crosscuttingconcerns.com/Adventures-in-Yak-Shaving-AsciiDoc-with-Visual-Studio-Code-Ruby-and-Gem">Adventures in Yak Shaving: AsciiDoc with Visual Studio Code, Ruby, and Gem</a></em></p>

<p>I <a href="http://crosscuttingconcerns.com/AsciiDoc-and-AsciiDocFX">blogged last year about my switch from Markdown to AsciiDoc</a>, and that I was using <a href="http://asciidocfx.com/">AsciiDocFX</a>.</p>
<p>I still like AsciiDoc, but AsciiDocFX has been getting on my nerves:</p>
<ul>
<li>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.</li>
<li>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.</li>
</ul>
<p>Still, I used it.</p>
<p>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 <a href="https://code.visualstudio.com/">Visual Studio Code</a>. And, of course there was, because apparently the Code extension ecosystem is booming!</p>
<p>So, I installed <a href="https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode">AsciiDoc by Joao Pinto</a>, since it came with a live preview. But, it requires me to actually install the asciidoc command line tool.</p>
<p><img src="https://crosscuttingconcerns.blob.core.windows.net/images/asciidoc%20prereq.jpg" alt="" width="345" height="102" /></p>
<p>See?</p>
<p>So, I thought, that should be easy enough. I went to the <a href="http://asciidoctor.org/docs/install-toolchain/">AsciiDoc site</a>&nbsp;and started following the directions for Windows installation.</p>
<p><strong>Install Ruby</strong></p>
<p>Okay, well now I need to install Ruby. Should be easy enough. I already have Chocolatey NuGet, so I'll just run <code>choco install ruby</code>. No problem. I know that ruby comes with gem, so I should be all set.</p>
<p><strong>Install AsciiDoc</strong></p>
<p>According to AsciiDoc... docs... I just use <code>gem install asciidoctor</code> and that should do the trick.</p>
<p>But, no. It's not that easy. Otherwise I wouldn't be writing this blog. I got an error message:</p>
<p><code>SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed</code></p>
<p>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 <a href="https://gist.github.com/luislavena/f064211759ee0f806c88">some random guy's Gist and SSL upgrades on rubygems.org</a>&nbsp;which lead to me<a href="http://guides.rubygems.org/ssl-certificate-update/#installing-using-update-packages"> this page on rubygems.org about SSL updates</a>.</p>
<p><strong>Fixing RubyGems Certificate Thingy</strong></p>
<p>So, following that literally:</p>
<p><code>gem install --local C:\rubygems-update-2.6.7.gem</code></p>
<p>and then</p>
<p><code>update_rubygems --no-ri --no-rdoc</code></p>
<p>and finally</p>
<p><code>gem uninstall rubygems-update -x</code></p>
<p>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!</p>
<p><strong>Okay, now Install AsciiDoc</strong></p>
<p>So now <code>gem install asciidoctor</code> works. And now I get a live preview of AsciiDoc in Visual Studio Code.</p>
<p><img src="https://crosscuttingconcerns.blob.core.windows.net/images/asciidoc%20with%20visual%20studio.jpg" alt="" width="700" height="167" /></p>
<p>I'll report back after some more time blogging to see if I like this, or if I eventually go back to AsciiDocFx.</p>