Skip to content

Instantly share code, notes, and snippets.

@dcode
Last active March 27, 2024 12:38
Show Gist options
  • Save dcode/0cfbf2699a1fe9b46ff04c41721dda74 to your computer and use it in GitHub Desktop.
Save dcode/0cfbf2699a1fe9b46ff04c41721dda74 to your computer and use it in GitHub Desktop.
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, .asc, 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 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 Asciidoctor project has GREAT user manual and Quick Reference!

@jlisee
Copy link

jlisee commented Jul 6, 2021

@dcode thanks for putting this out there, it's a great demo of what Asciidoc can do in GitHub. I did notice that all of your links are broken, for example the first link should be link:http://asciidoctor.org/[Asciidoctor] not link::http://asciidoctor.org/[Asciidoctor]. The issue is that you are using link:: instead of the normal link: macro to start your links.

@kspurgin
Copy link

It looks like it might not be possible to have inline rendered images in an AsciiDoc file in a private repo.

I think it assumes the <img src= value used to render the image will be base url from imagesdir + image file name from image reference

But in a private repo, there is a token on the end of the URL for any raw file.

@b-layer
Copy link

b-layer commented Oct 30, 2021

Anyone else notice that sidebars don't render well on GH? I tried using it here https://github.com/b-layer/musecnav#popup (it starts with the text "Numerical Selection in the Popup"). No visual delineation...looks terrible. Looks fine locally.

@abelsromero
Copy link

@b-layer There's not much tha can be done. This is GitHub-Flavored Asciidoc, not all features are allowed and there are some style modifications. Using GH preview is nice for simple things, but not something to consider for a professional result.

@b-layer
Copy link

b-layer commented Nov 4, 2021

@abelsromero Yes, thanks, I'm aware of all that but I hadn't seen any mention of this particular failing before (e.g. in the gist we're commenting on) and was wondering if perhaps I'd missed something, if there is any known workaround and if no to both of those at least to note it for any future readers wondering the same thing.

@theAkito
Copy link

theAkito commented Nov 9, 2021

I've tested using the .ad file name extension several times, already. It simply does not work!

@diguage
Copy link

diguage commented Feb 17, 2022

How to use asciidoc in the issue?

@JoeArauzo
Copy link

@theAkito You must use either .asciidoc, .adoc, or .asc, per https://github.com/github/markup/blob/master/README.md#markups.

@prudhomm
Copy link

nice doc!
it is a pity that Github does not have the same level of support for asciidoc as gitlab
in particular supporting math

@donnels
Copy link

donnels commented May 17, 2022

Nice if statement helps me a lot. thank you.

@pepa65
Copy link

pepa65 commented Jul 23, 2023

I just created a README.ad but it is not rendered at all...
Edit: Turns out .ad is not recognized, so use .adoc.

@dcode Please correct this gist by replacing .ad with .asc!

@abelsromero
Copy link

abelsromero commented Jul 24, 2023

Leaving the list of official file extensions here because it always takes me some time to find 👉 https://github.com/github/markup/blob/master/README.md#markups (.asciidoc, .adoc, .asc)

@dcode
Copy link
Author

dcode commented Jul 24, 2023

file extension updated. It did used to be .ad. I never intended this gist to be an authoritative documentation source, but I'm glad it's helped so many people! Sorry it took so long to get the file extension edited.

@dcode
Copy link
Author

dcode commented Jul 24, 2023

Fixed the links, as well.

@Fred-Vatin
Copy link

About

:toc:
:toc-placement!:

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

toc::[]

This is deprecated.
If you want to position toc::[] anywhere, now use:

:toc: macro

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

toc::[]

If you want to position it after a preamble, use this:

:toc: preamble

Here is my preamble.
The toc will be inserted after the ''' (this insert a line) and before the first section.
No need to use the macro toc::[] anymore.

'''

== First section

source

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