Skip to content

Instantly share code, notes, and snippets.

@jessfraz

jessfraz/include.toml

Last active Nov 20, 2020
Embed
What would you like to do?
GitHub asciidoc mishaps
[[includes]]
name = "thing"

Asciidoc rendering mishaps

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:

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:

asciidoctor2
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[]

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/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment