Upgrade Asciidoctor

looks like current version is 1.5.6.1 (Jul 2017):

markup/Gemfile

Line 14 in 8f436ff

gem "asciidoctor", "= 1.5.6.1"

since then, a few versions have dropped:

• 1.5.6.2 (Mar 2018)
• 1.5.7 (May 2018)
• 1.5.7.1 (May 2018)
• 1.5.8 (Oct 2018)

can we please get an update?

[mojavelinux]

I would recommend waiting for 2.0.0, which is about to be released.

[mojavelinux]

@cup This isn't related to the Rouge integration. On GitHub, syntax highlighting is performed after the AsciiDoc is converted to HTML. That's what the html-pipeline syntax highlighter is for. It outputs HTML that can be processed by GitHub's internal HTML processing pipeline. In effect, it outputs a <pre> tags marked with the language. That pipeline happens to use Rouge downstream, but that has nothing to do with the Rouge integration in Asciidoctor.

@mojavelinux if rouge is already being used, and the asciidoctor currently used by github doesnt support rouge... then what?

where is the missing piece? how would that even work? perhaps Pygments or
highlight.js is being used?

im not saying you are wrong, but if you are right what is the workflow they are using?

[mojavelinux]

Syntax highlighting of code blocks already works on GitHub. That syntax highlighting is performed by GitHub's (proprietary) HTML pipeline using Rouge (AFAIK) after Asciidoctor converts the AsciiDoc to HTML. Here's how it works.

Let's assume you have the following source block in your AsciiDoc file:

[source,ruby]
----
puts 'Hello, GitHub!'
----

Asciidoctor will convert that to the following HTML:

<div class="listingblock">
<div class="content">
<pre lang="ruby"><code>puts "Hello, GitHub!"</code></pre>
</div>
</div>

GitHub's pipeline will then use Rouge (AFAIK) to apply syntax highlighting. Here's what the browser sees:

<div class="highlight highlight-source-ruby"><pre><span class="pl-c1">puts</span> <span class="pl-s"><span class="pl-pds">'</span>Hello, GitHub!<span class="pl-pds">'</span></span></pre></div>

The last step is proprietary, so the exact details are unknown to me.

the asciidoctor currently used by github doesnt support rouge... then what?

What exactly are you asking about? What is it that you think doesn't work?

[mojavelinux]

@cup The source code between <code></code> is unescaped (since it was extracted from HTML), then passed to Rouge to be highlighted (using the specified language). The result is then inserted back into the HTML document.

Rouge is not highlighting HTML. Rouge is highlighting the source code you provided. It's the (post-Asciidoctor) pipeline that is giving Rouge the source code to highlight.

[mojavelinux]

my understanding is that rouge takes raw source code...and turns it into the final output that you presented.

That understanding is correct. And that is what is happening.

@mojavelinux that seems... convoluted.

but even if thats true (which is likely because AsciiDoc highlight does work
currently) that would mean that we dont need to wait for AsciiDoctor 2. We
could go ahead and just upgrade to 1.5.8, which fixes the callout issue i
linked above.

i didnt see you state a reason for waiting for version 2, perhaps you could name
a "bulletpoint" that would make sense waiting for?

[mojavelinux]

that seems... convoluted.

It is what it is. I'm just reporting the facts.

I see why you may have been confused. You thought my suggestion about waiting for 2.0 had to do with the Rouge integration. By now, it should be clear that it does not.

The reason for waiting for 2.0.0 is that a) it's about to be released and b) GitHub has a very thorough process for upgrades. I won't want them to have to go through that whole process for the 1.5.8 upgrade only to have to turn around and do the same thing for 2.0.0 (which will certainly lead to delays). (Besides, I will definitely have 2.0.0 released before GitHub would have a chance to do the 1.5.8 upgrade anyway, so this is not any longer of a wait).

Although 2.0 is mostly about dropping support for outdated versions of Ruby and switching the semantic versioning, there are several key enhancements, improvements, and bug fixes included as well. As always, you can find these in the CHANGELOG. See https://github.com/asciidoctor/asciidoctor/blob/master/CHANGELOG.adoc#unreleased

[mojavelinux]

I'll be sure to post here as soon as Asciidoctor 2.0 is out. I know many people are eager to see Asciidoctor be upgraded, and I want to make sure we land on the version that writers are expecting.

[mojavelinux]

Asciidoctor 2.0.0 is now available. See https://github.com/asciidoctor/asciidoctor/releases/tag/v2.0.0

If you'd like me to send a PR to upgrade, just let me know and I'll submit one.

CC @kivikakk as he not subscribed