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

This is a repost from Cross Cutting Concerns: Adventures in Yak Shaving: AsciiDoc with Visual Studio Code, Ruby, and 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.

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.

Comments

[Aaron Pfalzgraf]

I'm not a huge fan of the syntax highlighting of Asciidoctor in Visual studio code.

It seems, just like the sublime plugin for asciidoc, to get hung up on what it thinks are unescaped sequences. (Or I just don't know how to write asciidoc lol). Using the Atom One Dark syntax theme and the plugin from Joao Pinto, the following code breaks the syntax highlighting for the rest of the document. I'm not sure if the language or the color theme is at fault.

It highlights from the _git__ps1 all the way through the end of the code block as purple/italics

== .bashrc Modifications
I actually had to modify my existing bashrc file to get git and gitk working.
**Plus**, the `_git__ps1` substitution doesn't work by default.
Your bashrc can be found in your `%HOME%` directory.

**NOTE**, this is just an example PS1, please modify yours to avoid losing content.  The change here is the insertion of a `'$'` before any `\n` in the PS1.

[source, bash]
----
# To make available the __git_ps1 substitution command
source /c/msys64/mingw64/share/git/completion/git-prompt.sh
export PS1='\e[0m\e[0;96m[\w]\e[0m\e[0;33m$(__git_ps1) \e[0m\e[1;37m'$'\n-> \e[0m'
----

[Matthew D. Groves]

As best I can tell, the AsciiDoc plugin for Code uses the asciidoctor command line to generate HTML. So it's possible there is some issue in the AsciiDoc markup that you're writing. Maybe give it a try with the command line tool directly?

If the command line works fine, you may want to open an issue on Github, so that Joao is at least aware: github.com/joaompinto/asciidoctor-...

[Aaron Pfalzgraf]

I actually did just drop an issue on github regarding this: github.com/joaompinto/asciidoctor-....

After working with the owner of the color theme, he determined that the language plugin was not exposing scopes correctly (or not at all).

I checked the html output with asciidoctor -o, and all is well.

[Matthew D. Groves]

Oh, I see, it's the syntax highlighting of the asciidoctor markup itself, not the plugin that I'm using. Cool, glad you got it resolved :)