Asciidoc rendering differs for files, wiki and gists

[powerman]

Comparing to Asciidoc files, wiki has these issues:

• "Table of Contents" contains extra bullets, which makes more than 1 level toc too ugly.
• Custom anchors [[anchor]] doesn’t work.

In addition to wiki issues, gist has these issues:

• Gist must have a file name with one of asciidoc’s extensions (just selecting file type in drop-down isn't enough).
• Document title is not rendered.
• Link in "Table of Contents" doesn’t work because generated links start with extra _.
• No syntax highlight for [source].

You can see live examples here:
https://github.com/powerman/asciidoc-cheatsheet
https://github.com/powerman/asciidoc-cheatsheet/wiki
https://gist.github.com/powerman/d56b2675dfed38deb298

[nikolay]

👍 I've been struggling with the lack of headers in gists as well.

[powerman]

Link in "Table of Contents" doesn’t work because generated links start with extra _.

Just noticed: they also use _ instead of - in the middle.

[mojavelinux]

@nikolay You can get a document title in a gist by using the showtitle attribute.

= Document Title
:showtitle:

content

It's supposed to be enabled by default, but this at least gets it working in the interim.

[powerman]

@mojavelinux Thanks for the hint, I've updated the cheatsheet!

[bkeepers]

Hi @powerman, thanks for reporting the issues. This repository is not actually responsible for those issues. Would you mind sending your report to support@github.com? That helps us both keep track of how many people it affects and route it to the right teams.

[powerman]

@bkeepers Sure, I'll do this now, thanks for reply.

[mojavelinux]

I want to chime in just to say that I have taken note of these issues and I'll do what I can on my part (in Asciidoctor core and/or the configuration of Asciidoctor on GitHub) to address them.

[mojavelinux]

Custom anchors [[anchor]] doesn’t work.

This happens because of the sanitization filter. All attributes (except for a minimal set that are whitelisted, such as src on img) are stripped prior to the HTML being displayed. The anchor elements that are used on GitHub are actually added by a postprocessing filter and are not the same as those generated by Asciidoctor. While there is some alignment for auto-generated ids, and custom anchors aren't going to work as a result of this policy.

[mojavelinux]

"Table of Contents" contains extra bullets, which makes more than 1 level toc too ugly.

I remember this being fixed recently. See https://github.com/JavaMoney/jsr354-api/blob/master/src/main/asciidoc/JavaMoneySpecification.adoc (thanks GitHub!)

[powerman]

@mojavelinux <a name=> should do the trick. Same for footnotes.

[mojavelinux]

Oops, I see now that the table of contents comment was about the wiki. Well, it's fixed in the main repo, so it needs to be migrated to gollum as well.

[mojavelinux]

@mojavelinux <a name=> should do the trick. Same for footnotes.

I've thought about taking that approach. That means a custom converter for GitHub and we haven't taken that plunge yet. I'm still hoping we can work out another arrangement.

[mojavelinux]

Aha! We might be able to address this with an extra filter that moves id attributes to the name attribute. That's actually a very reasonable idea. It will need to be added to this repo: https://github.com/asciidoctor/html-pipeline-asciidoc_filter

[mojavelinux]

Link in "Table of Contents" doesn’t work because generated links start with extra _.

This can be fixed by adding the following to the header:

:idprefix:
:idseparator: -

These defaults, along with showtitle are supposed to be set in gist like they are on GitHub repos, but for some reason the configuration didn't get used properly. That could also explain why source code highlighting isn't working.

Here's the configuration that's supposed to be set on gists.

https://github.com/github/markup/blob/master/lib/github/markups.rb#L29