GitHub asciidoc mishaps

include.toml

[[includes]]
name = "thing"

sample.adoc

Asciidoc rendering mishaps

Table of Contents

• 1. Source code blocks with annotations
• 2. Includes
• 3. Links
• 4. Diagrams

There is some weird stuff going on with the GitHub Asciidoc renderer.

There is a great gist covering a lot of these as well: link: gist GitHub Flavored Asciidoc. In my opinion, it’s sad that asciidoc itself does not just work correctly natively. I understand the need for GitHub Flavored Markdown since markdown was lacking features GitHub needed. Asciidoc does not lack those features and it would be nice for practitioners if there was not a special GitHub flavored asciidoc.

1. Source code blocks with annotations

This is a ruby code block with annotations:

require 'sinatra' // (1)

get '/hi' do // (2)
  "Hello World!" // (3)
end

1. Library import

2. URL mapping

3. HTTP response body

This is what it looks like when rendered by asciidoctor:

Figure 1: An image of the asciidoctor ruby rendering

Now this paragraph under the image is way too closely aligned with the image and caption above. This is broken as well…​

This is a json code block with annotations:

{
  "name": "jess-global-admin", (1)
  "description": "Adds jessfraz as a global admin.", (2)
  "bindings": [
    {
      "identities": [
        "user:jessfraz" (3)
      ],
      "role": "roles/global.admin" (4)
    }
  ],
  "etag": "aGVsbG8K=", (5)
  "version": 1 (6)
}

1. A name, must be unique.

2. An optional description.

3. A user

4. The role

5. The etag

6. The version

It is vomiting…​ likely because json doesn’t support comments.

However, asciidoctor is like "yo I got this." This is what it looks like when rendered by asciidoctor:

Figure 2: An image of the asciidoctor json rendering

Now this paragraph under the image is way too closely aligned with the image and caption above. This is broken as well…​

2. Includes

Using an include in a source code block should work.

link:include.toml[role=include]

3. Links

So asciidoc does links like reference. But If I link to something internal I want to do Source code blocks with annotation (←- THIS SHOULD BE A CODE LITERAL, instead it is resolving it) but let’s see what happens: Source code blocks with annotation.

It’s broken because GitHub is doing markdown like header links not asciidoc which starts with an and uses `’s between words. Now all these inline code blocks are vomiting as well…​.

So there are two problems here:

1. the link doesn’t work: should be #_source_code_blocks_with_annotation NOT #source-code-blocks-with-annotation

2. my literal inline code snippet should be shown as just that, not the rendered link and then all the following inline code snippets should not be terrible

4. Diagrams

Some support for diagrams would be nice: https://asciidoctor.org/docs/asciidoctor-diagram/