Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Demo of some useful tips for using Asciidoc on GitHub

GitHub Flavored Asciidoc (GFA)

3137042?v=3&s=200

This gist is to capture some of the semantics of GitHub-Flavored Asciidoc. GitHub uses Asciidoctor in safe mode to render files with the extension .adoc, .ad, and .asciidoc. This works in standard repositories as well as gists.

I think most people use Markdown when creating documentation on GitHub. Markdown is great and easy, but I often create technical documentation or training material where some of the additional semantics of Asciidoc are really helpful.

GitHub-Specific customizations

Often you might need to adjust some settings whether your document is being rendered on GitHub or offline using link::http://asciidoctor.org/[Asciidoctor] or similar. In your header simply use the ifdef preprocessor macro:

ifdef::env-github[]
:imagesdir: foo/
endif::[]

Everything within the ifdef and endif will only be processed if you are on GitHub.

Table of Contents

Often, I will write long documents that could use some extra organization (like this one). Asciidoc can automatically render a Table of Contents (TOC) for you, based upon the heading structure you have used. This is especially handy for web content or PDFs (when rendered offline).

To use TOC on GitHub, I use the following:

:toc:
:toc-placement!:

Here is my preamble paragraph, but I could really place the TOC anywhere! Lorem ipsum foo bar baz.

toc::[]

The :toc: directive states that I want to enable the :toc: processor. The :toc-placement!: directive undefines the current placement strategy, which doesn’t work on GitHub. This indicates that we will specify where the TOC should be placed.

Lastly, the toc::[] tells Asciidoctor to render a Table of Contents for the whole document here.

Admonitions

Admonitions are handy blocks that are rendered seperate from the rest of the content. This is really helpful for explaining something that doesn’t quite fit the flow, but you need to get the readers' attention. The ifdef portion and the rest of the lines that start with : go in your header.

The pre-processor directive ifdef checks to see if the GitHub environment is being used. To account for the opposite, create a block using ifndef. You can look at the header of this document to see how I managed it for this document.

Example conditional enabling of icons for admonitions
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

[NOTE]
====
A sample note admonition.
We can use gemoji icons in the Asciidoctor markup.
We assign an icon name to the document
attributes `tip-caption`, `note-caption` and `important-caption`.
====

TIP: It works!

IMPORTANT: Asciidoctor is awesome, don't forget!

CAUTION: Don't forget to add the `...-caption` document attributes in the header of the document on GitHub.

WARNING: You have no reason not to use Asciidoctor.

Will be rendered as:

ℹ️

A sample note admonition. We can use gemoji icons in the Asciidoctor markup. We assign an icon name to the document attributes tip-caption, note-caption and important-caption.

💡
It works!
Asciidoctor is awesome, don’t forget!
🔥
Don’t forget to add the …​-caption document attributes in the header of the document on GitHub.
⚠️
You have no reason not to use Asciidoctor.

Images

Images work as you would expect using the normal image syntax:

image::my_filename.png[]

You can also give an absolute URL:

image::https://avatars3.githubusercontent.com/u/3137042?v=3&s=200[]

There is a caveat, however. In order for them to be rendered inline, you must provide an absolute path to the :imagesdir: directive. On GitHub this consists of a full HTTPS path to the image’s parent directory. Once you have all of your images uploaded into your repository, look at the raw link for one of the images. Select just the directory portion of the URL and put that into:

ifdef::env-github[]
:imagesdir: https://gist.githubusercontent.com/path/to/gist/revision/dir/with/all/images
endif::[]
ℹ️
When writing a Gist, all files must be in a single, flat directory. To upload images, you must first create a file in the Gist and then you can clone it. Once you’ve cloned it locally, you can add anything you like as long as you do not create any subdirectories.

Callouts

Callouts are a great way to explain code segment and are, in fact, the one of the two main reasons I even looked into asciidoc (the other being the admonition blocks). Asciidoctor will place numbers in the code listing, which you can uses as references following the code listing.

[source]
 ----
\ifdef::env-github[] <1> (1)
:imagesdir: https://gist.githubusercontent.com/path/to/gist/revision/dir/with/all/images
endif::[]
\ifndef::env-github[] <2>
:imagesdir: ./
endif::[]
 ----
<1> Use the `ifdef` to customize for online rendering (2)
<2> Use the `ifndef` to customize for offline
  1. Callouts in the body of the listing appear as either an icon or within parentheses.

  2. The block underneath allows you to explain the code sample without getting in the way

What Next?

I’ll add more comments here as I write and find interesting nuances. In the meantime, the link::http://asciidoctor.org[Asciidoctor project] has GREAT link::http://asciidoctor.org/docs/user-manual/[user manual] and link::http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Quick Reference]!

@roman-yagodin

This comment has been minimized.

Copy link

@roman-yagodin roman-yagodin commented Sep 22, 2017

Great gist 👍

But how :imagesdir: should like for a project's wiki page? I've tried https://raw.githubusercontent.com/<username>/<repo>/master/doc/images but without success.

@chenrui333

This comment has been minimized.

Copy link

@chenrui333 chenrui333 commented Oct 7, 2017

very useful gist! But I think the reference links can be updated.

@sixdouglas

This comment has been minimized.

Copy link

@sixdouglas sixdouglas commented Oct 27, 2017

@roman-yagodin for the wiki image problem you mentioned, may be the problem is the sub-directories doc/images. I think that what you call wiki is what is refered to as Gist in this page.

@karthick-gururaj

This comment has been minimized.

Copy link

@karthick-gururaj karthick-gururaj commented Mar 11, 2018

Thanks for this gist!

One question: where do I need to direct any questions or bug reports on AsciiDoc support in Github? Specifically, it looks like the include:: directive is not supported correctly. The rendered page has a link to the included file - or, if a source file is being included, then just a plain message is shown. See: https://github.com/karthick-gururaj/asciidoc-expts/blob/master/Example.asciidoc for a demo.

Regards,
Karthick

@pkeller

This comment has been minimized.

Copy link

@pkeller pkeller commented May 23, 2018

@karthick-gururaj See github/markup#1095 for info about the asciidoctor include directive. Short answer: it may start working next year (2019)

@fsundermeyer

This comment has been minimized.

Copy link

@fsundermeyer fsundermeyer commented Jul 27, 2018

Regarding the includes, we use the following workaround:

// Links for GitHub
ifdef::env-github,backend-html5[]
  <<book_mgr_getting_started.adoc#getting-started, SUSE Manager Getting Started>>
  <<book_mgr_best_practices.adoc#best-practices, SUSE Manager Best Practices>>
  <<book_suma_reference_manual.adoc#reference-manual, SUSE Manager Reference Manual>>
  <<book_suma_advanced_topics.adoc#advanced-topics, SUSE Manager Advanced Topics>>
endif::[]
// includes for AsciiDoc processing
ifndef::env-github,backend-html5[]
  include::book_mgr_getting_started.adoc[]
  include::book_mgr_best_practices.adoc[]
  include::book_suma_reference_manual.adoc[]
  include::book_suma_advanced_topics.adoc[]
endif::[]

See https://github.com/SUSE/doc-susemanager/ (the example above is taken from adoc/MAIN-manager.adoc)

@MarkusMit

This comment has been minimized.

Copy link

@MarkusMit MarkusMit commented Sep 6, 2018

Is there or will there be support for diagrams, like with Asciidoctor Diagram (PlantUML in particular)?

@brunchboy

This comment has been minimized.

Copy link

@brunchboy brunchboy commented Sep 22, 2018

🎉 Thank you so much for letting me finally get graphical admonition captions in my GitHub-hosted documentation!

@DBuret

This comment has been minimized.

Copy link

@DBuret DBuret commented Feb 2, 2019

About plantUML: you can use plantUML proxy to show your diagrams on GitHub in AsciiDoc files. see https://github.com/DBuret/myjournal/blob/master/github-plantuml.adoc

@dcode

This comment has been minimized.

Copy link
Owner Author

@dcode dcode commented May 20, 2019

Holy cow! I just set it and forgot it. Didn't realize that so many people were referencing my gist. I'm just a guy, I have no affiliation with GitHub or Asciidoctor. I'll take a look at this gist tomorrow and update documentation as requested.

@abelsromero

This comment has been minimized.

Copy link

@abelsromero abelsromero commented Jun 12, 2019

Holy cow! I just set it and forgot it. Didn't realize that so many people were referencing my gist.

Congratz, I just found it googling and I just references again https://twitter.com/abelsromero/status/1138809819253678085

@potatoqualitee

This comment has been minimized.

Copy link

@potatoqualitee potatoqualitee commented Jun 12, 2019

and i just found it from abel's post :D

@valler

This comment has been minimized.

Copy link

@valler valler commented Nov 20, 2019

The :toc-placement!: directive undefines the current placement strategy, which doesn’t work on GitHub.

Default TOCs work for me. The :toc: attribute is a header attribute. Are you placing it correctly? Do you mean you don't like the way GitHub renders the toc?

@cburkins

This comment has been minimized.

Copy link

@cburkins cburkins commented Jan 19, 2020

Very handy doc, appreciate you creating it. Have you gotten automatic line numbering to work within a source code block ? I can't seem to get this to work:

[source,groovy,linenums]
----
// File: User.groovy
class User {
    String username
}
----
@av1m

This comment has been minimized.

Copy link

@av1m av1m commented Mar 22, 2020

Very useful document, you can also add this ;)

.see content
[%collapsible]
====
* Hello world
====
@av1m

This comment has been minimized.

Copy link

@av1m av1m commented May 10, 2020

Since emoji are part of unicode, why not add emojis directly like this ?

:tip-caption: 💡
:note-caption: ℹ️
:important-caption:
:caution-caption: 🔥
:warning-caption: ⚠️

@wimdeblauwe

This comment has been minimized.

Copy link

@wimdeblauwe wimdeblauwe commented Jul 4, 2020

For the table of contents, you can control how many levels will be shown in the toc, by setting the toclevels attribute. Example:

= My README
:toc: macro
:toclevels: 3

Welcome to my readme. This is the table of contents:

toc::[]

toclevels can be a number between 1 and 5

@astubbs

This comment has been minimized.

Copy link

@astubbs astubbs commented Aug 26, 2020

FYI for the includes, github/markup#1095 (comment)

Building on @zteater's great work:

Well, this is still open 2.5 years later. For anyone using Maven, I wrote a plugin to read the include:: syntax on a template file and generate a consolidated file. Not a fullly-baked asciidoctor tool, but enough to generate my readme.adoc file.

https://github.com/whelk-io/asciidoc-template-maven-plugin

Hey @zteater el al! I submitted a PR to your plugin to support tagged and untagged code includes =D Thanks for the wonderful quick workaround!

whelk-io/asciidoc-template-maven-plugin#25

@diguage

This comment has been minimized.

Copy link

@diguage diguage commented Nov 10, 2020

Nice

@yakryder

This comment has been minimized.

Copy link

@yakryder yakryder commented Nov 23, 2020

Awesome gist!

About the include directives:
Is this supported somehow without making use of a process-and-commit pipeline, whether by workaround or not?

@fsundermeyer
I spent a little chunk of time trying to find your workaround in both the project you mentioned and the project it was absorbed into. Naturally I had to backtrack a little with SUSE. I couldn't actually find a single instance in either of an include rendering properly in GitHub.

Is there a file from a SHA where this works that you could link to?

I've also tried using the AsciiDoc chrome plugin in Brave with no luck properly rendering adocs with include directives in them on GitHub either.

Does this work in GitLab? github/markup#1095 isn't stagnant, but I didn't see anything that looked especially promising at a glance.

@abelsromero

This comment has been minimized.

Copy link

@abelsromero abelsromero commented Nov 23, 2020

@SherSpock

Is this supported somehow without making use of a process-and-commit pipeline, whether by workaround or not?

Not in GitHub, but they do work in Gitlab. But with GH-Actions the procres is made really easy.

I've also tried using the AsciiDoc chrome plugin in Brave with no luck properly rendering adocs with include directives in them on GitHub either.

Just guessing, but if you are using something like include::my-part.adoc[] I doubt the plugin is able get the path. Overall, I'd recomend not to try to get a 100% accurate local preview or repository UI preview, complex doc builds just will require doing a full conversion.
Said that, on the bright side, intellij plugin offers the best experience so far in local, with a decent preview, autocomplete and refactor features.

Does this work in GitLab? github/markup#1095 isn't stagnant, but I didn't see anything that looked especially promising at a glance.

Yes, not a rant, just facts. It's true that GitLab team has been more open to imprevements that GitHub, work with the later is slower.

@fsundermeyer

This comment has been minimized.

Copy link

@fsundermeyer fsundermeyer commented Nov 23, 2020

I spent a little chunk of time trying to find your workaround in both the project you
mentioned and the project it was absorbed into. Naturally I had to backtrack a little
with SUSE. I couldn't actually find a single instance in either of an include rendering > properly in GitHub.

As far as I know including files in ASCIIDoc documents as well as resolving attributes is disabled for security reasons on GitHub.
However, it looks like a simple include statement at least results in a clickable link to the included document in the meantime, so the workaround I posted above is no longer needed (see https://github.com/SUSE/doc-caasp/blob/master/adoc/book_admin.adoc for an example).

Does this work in GitLab?

https://about.gitlab.com/releases/2019/06/22/gitlab-12-0-released/#support-for-asciidoc-include-directive
It at least works in an on premise Gitlab installation I am using (including resolving of attributes), haven't tested gitlab.com, though.

@yakryder

This comment has been minimized.

Copy link

@yakryder yakryder commented Nov 28, 2020

@abelsromero
Thank you much! Without understanding it better or having some clear examples of how it might work in my specific context, the idea of allowing an action to commit changes makes me nervous. I appreciate the GitLab and plugin tip!

@fsundermeyer
Ah, thank you! It's clear to me now I didn't understand what that workaround was for.

Looks like a self-hosted instance of GitLab isn't necessary to make this work. I have confirmed that includes and attributes appear to work just fine on GitLab. At least in a simple test case including text and an attribute from a single document into another with a reference to that attribute.

@abelsromero

This comment has been minimized.

Copy link

@abelsromero abelsromero commented Nov 28, 2020

@SherSpock

Thank you much! Without understanding it better or having some clear examples of how it might work in my specific context, the idea of allowing an action to commit changes makes me nervous. I appreciate the GitLab and plugin tip!

The publicaton in fact is trivial with https://github.com/JamesIves/github-pages-deploy-action. Here is an example of a GH-Action that publishes and Antora/Asciidoctor site on GH-Pages when a change on "main" branch is done, docs are in a folder called "docs" alongside the code. The tricky part is using upload-artifact and download-artifact to share the resulted converted docs in HTML between conversion and push steps.
The only thing to adapt is the "Generate site using antora site action", the rest is always the same.

To know more just drop by the asciidoctor gitter channels or the forum.

name: Build & publish docs
on:
  push:
    branches:
      - main

env:
  SITE_DIR: 'site'

jobs:
  build_site:
    name: "Build site with Antora"
    runs-on: [ubuntu-latest]
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: "Generate site using antora site action"
        uses: kameshsampath/antora-site-action@master
        with:
          antora_playbook: antora-playbook.yml
      - name: "Upload generated site"
        uses: actions/upload-artifact@v1.0.0
        with:
          name: site
          path: "${{ github.workspace }}/build/${{ env.SITE_DIR }}"
  deploy_site:
    runs-on: [ubuntu-latest]
    needs: [build_site]
    name: "Deploy GitHub Pages"
    steps:
      - name: Setup Node.js for use with actions
        uses: actions/setup-node@v1.4.4
        with:
          version: '14'
      - name: Checkout
        uses: actions/checkout@v2
      - name: Download generated site
        uses: actions/download-artifact@v1
        with:
          name: site
          path: "${{ github.workspace }}/${{ env.SITE_DIR }}"
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@3.7.1
        with:
          GITHUB_TOKEN: "${{ github.token}}"
          FOLDER: "${{ env.SITE_DIR }}"
          BRANCH: 'gh-pages'
          COMMIT_MESSAGE: "[CI] Publish Documentation for ${{ github.sha }}"
          CLEAN: true
@mojavelinux

This comment has been minimized.

Copy link

@mojavelinux mojavelinux commented Dec 5, 2020

As we work on revamping the docs site for Asciidoctor, I would love to see a section dedicated to succeeding with AsciiDoc on GitHub. There are certainly idiosyncrasies to understand and having a docs page on the topic will certainly help people who host their AsciiDoc files there. Perhaps consider submitting this to the new docs for Asciidoctor (which will live in the main asciidoctor repository).

My only objection is the term "GitHub Flavored AsciiDoc". There is no such thing. Please don't use this term as it suggests fragmentation that's simply not there (like there is with Markdown). There is only one AsciiDoc. The software GitHub uses to process it is the same software that's used throughout the ecosystem (Asciidoctor). What differs is how the rendered HTML is displayed. GitHub applies their own stylesheet to it, one that we have little control over. There is a somewhat unspoken API with the stylesheet in AsciiDoc that becomes visible when a different stylesheet is applied. I think those differences are certainly worth noting. GitHub also disables includes, but that is another matter.

(If any term applies here, it would be GitHub Limited AsciiDoc. But I'm concerned that would come across as unnecessarily critical.)

@mojavelinux

This comment has been minimized.

Copy link

@mojavelinux mojavelinux commented Dec 5, 2020

In order for [images] to be rendered inline, you must provide an absolute path to the :imagesdir: directive.

This is not a true assertion. Relative image paths do work. If the document is nested in a different structure than the images, you may need to use a different value compared to your publishing environment. But relative paths work even in this scenario.

@siddjain

This comment has been minimized.

Copy link

@siddjain siddjain commented Dec 23, 2020

what about math? math does not render for me on github.

@JoeArauzo

This comment has been minimized.

Copy link

@JoeArauzo JoeArauzo commented Dec 27, 2020

Thanks for the tip on how to get admonitions with icons working on GitHub. Take a look at my AsciiDoc README Template.

@Jeeppler

This comment has been minimized.

Copy link

@Jeeppler Jeeppler commented Feb 15, 2021

@mojavelinux thanks for pointing out that all includes are disabled in GitHub. Furthermore, the most important messages was, that there is no fragmentation and no GitHub Flavored Asciidoc (GFA).

@mojavelinux

This comment has been minimized.

Copy link

@mojavelinux mojavelinux commented Feb 15, 2021

what about math? math does not render for me on github.

It's true that math (i.e., STEM) does not render on GitHub. Though there are workarounds we could still explore, like using their image service to generate an SVG (e.g., https://render.githubusercontent.com/render/math?math=\displaystyle \text{b} = V D) But just because GitHub won't render something doesn't make it not AsciiDoc. It just means GitHub is not providing a full fidelity experience. And there's literally nothing we can do about it*. We have offered to help. But at the end of the day, it's their platform and their choice. And they simply refuse to implement certain display features, despite countless pleas from the community.

Where you do see these display features implemented is on GitLab. I think, in many ways, they are leading the way on what it means to support AsciiDoc properly in a repository browser, and hopefully others will follow.

* Perhaps the AsciiDoc WG can play an arbitration role. We'll have to see.

@mojavelinux

This comment has been minimized.

Copy link

@mojavelinux mojavelinux commented Feb 15, 2021

@JoeArauzo Nice!

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