Asciidoc cheatsheet for GitHub

AsciidocCheatsheet.adoc

Asciidoc cheatsheet for GitHub

Table of Contents

• GitHub limitations
• Attributes
• Headers
• Level 1
• Paragraphs
• Blocks
• Text
• Macros: links, images
• Lists
• Tables

GitHub limitations

This cheatsheet contains small part of Asciidoc markup which works and looks fine on GitHub. There is also full cheatsheet, but for now it’s main use is to show bugs, design issues, GitHub limitations and other differences from how Asciidoc cheatsheet should really looks like.

You can try these browser add-ons to fix some issues:

• UserJS for GitHub: fix Asciidoc rendering

• UserCSS for GitHub: compact Markdown/Asciidoc lists

Note

This is copy of https://github.com/powerman/asciidoc-cheatsheet to see limitations of GitHub Gist. Here is current list: Gist must have a file name with one of asciidoc’s extensions. Document title is not rendered without :showtitle: attribute. "Table of Contents" contains extra bullets, which makes more than 1 level toc too ugly. Link in "Table of Contents" doesn’t work because generated links start with extra _. No syntax highlight for [source]. Custom anchors doesn’t work. Relative/absolute links works in different way.

Attributes

// Header of this document:

Asciidoc cheatsheet for GitHub
==============================
:toc:
:toc-placement: preamble
:toclevels: 1
:showtitle:
:Some attr: Some value

// Need some preamble to get TOC:
{empty}

Some attr's value is {someattr}. Escaped: \{someattr} and +++{someattr}+++.

Some attr’s value is Some value. Escaped: {someattr} and {someattr}.

Headers

== Level 1 Text. === Level 2 Text. ==== Level 3 Text. ===== Level 4 Text.

Level 1 Text. Level 2 Text. Level 3 Text. Level 4 Text.

Paragraphs

.Optional Title Usual paragraph. Second paragraph.	Optional Title Usual paragraph. Second paragraph.
.Optional Title Literal paragraph. Must be indented.	Optional Title Literal paragraph. Must be indented.
.Optional Title [source,perl] die 'connect: '.$dbh->errstr; Not a code in next paragraph.	Optional Title die 'connect: '.$dbh->errstr; Not a code in next paragraph.
.Optional Title NOTE: This is an example single-paragraph note.	Note Optional Title This is an example single-paragraph note.
.Optional Title [NOTE] This is an example single-paragraph note.	Note Optional Title This is an example single-paragraph note.
TIP: Some tip text. IMPORTANT: Some important text. WARNING: Some warning text. CAUTION: Some caution text.	Tip Some tip text. Important Some important text. Warning Some warning text. Caution Some caution text.

Blocks

.Optional Title ---- *Listing* Block Use: code or file listings ----	Optional Title *Listing* Block Use: code or file listings
.Optional Title [source,perl] ---- # *Source* block # Use: highlight code listings use DBI; my $dbh = DBI->connect('...',$u,$p) or die "connect: $dbh->errstr"; ----	Optional Title # *Source* block # Use: highlight code listings use DBI; my $dbh = DBI->connect('...',$u,$p) or die "connect: $dbh->errstr";
.Optional Title [NOTE] ==== *NOTE* Block Use: multi-paragraph notes. ====	Note Optional Title NOTE Block Use: multi-paragraph notes.
.Optional Title [quote, cite author, cite source] ____ *Quote* Block Use: cite somebody ____	Optional Title Quote Block Use: cite somebody — cite author cite source
//// *Comment* block Use: hide comments ////
++++ *Passthrough* Block <p> Use: GitHub-restricted subset of HTML markup <table border="1"> <tr><td>1</td><td>2</td></tr> </table> ++++	*Passthrough* Block Use: GitHub-restricted subset of HTML markup 1 2
.Optional Title .... *Literal* Block Use: workaround when literal paragraph (indented) like 1. First. 2. Second. incorrectly processed as list. ....	Optional Title *Literal* Block Use: workaround when literal paragraph (indented) like 1. First. 2. Second. incorrectly processed as list.

Text

forced + line break	forced line break
normal, 'italic', _italic_, *bold*. +mono *bold*+, `mono pass thru *bold*` ``double quoted'', `single quoted'. normal, ^super^, ~sub~.	normal, italic, italic, bold. mono bold, mono pass thru *bold* “double quoted”, ‘single quoted’. normal, super, sub.
Chars: n__i__**b**++m++n	Chars: nibmn
// Comment
(C) (R) (TM) -- ... -> <- => <= &#182;	© ® ™ — …​ → ← ⇒ ⇐ ¶
''''
Escaped: \_italic_, +++_italic_+++, t\__e__st, +++t__e__st+++, \&#182;	Escaped: _italic_, _italic_, t__e__st, t__e__st, &#182;

Macros: links, images

If you’ll need to use space in url/path you should replace it with %20.

[[anchor-1]] Paragraph or block 1. <<anchor-1>>, <<anchor-1,First anchor>>, xref:anchor-1[], xref:anchor-1[First anchor].	Paragraph or block 1. [anchor-1], First anchor, [anchor-1], First anchor.
link:README.adoc[This document] link:/README.adoc[]	This document /README.adoc
http://google.com http://google.com[Google Search] mailto:root@localhost[email admin]	http://google.com Google Search email admin
// Use attribute to shorten urls :repo: https://github.com/powerman/asciidoc-cheatsheet :img: {repo}/raw/master/images First home image:{img}/icons/home.png[] , second home image:{img}/icons/home.png[Alt text] . .Block image image::{img}/icons/home.png[] image::{img}/icons/home.png[Alt text] .Thumbnail linked to full image image:{img}/font/640-screen2.gif[ "My screenshot",width=128, link="{img}/font/640-screen2.gif"]	First home , second home . Figure 1. Block image Thumbnail linked to full image

Lists

.Bulleted * bullet * bullet - bullet - bullet * bullet ** bullet ** bullet *** bullet *** bullet **** bullet **** bullet ***** bullet ***** bullet **** bullet *** bullet ** bullet * bullet	Bulleted bullet bullet bullet bullet bullet bullet bullet bullet bullet bullet bullet bullet bullet bullet bullet bullet bullet
.Bulleted 2 - bullet * bullet ** bullet *** bullet	Bulleted 2 bullet bullet bullet bullet
.Ordered . number . number .. lower roman .. lower roman . number .. lower roman .. lower roman ... lower alpha ... lower alpha .... lower alpha .... lower alpha ..... lower alpha ..... lower alpha .... lower alpha ... lower alpha .. lower roman . number	Ordered number number lower roman lower roman number lower roman lower roman lower alpha lower alpha lower alpha lower alpha lower alpha lower alpha lower alpha lower alpha lower roman number
.Ordered 2 a. lower alpha b. lower alpha .. lower roman .. lower roman . lower alpha . lower alpha 1. lower alpha 2. lower alpha 3. lower alpha 4. lower alpha . lower alpha .. lower roman c. lower alpha	Ordered 2 lower alpha lower alpha lower roman lower roman lower alpha lower alpha lower alpha lower alpha lower alpha lower alpha lower alpha lower roman lower alpha
.Labeled Term 1:: Definition 1 Term 2:: Definition 2 Term 2.1;; Definition 2.1 Term 2.2;; Definition 2.2 Term 3:: Definition 3 Term 4:: Definition 4 Term 4.1::: Definition 4.1 Term 4.2::: Definition 4.2 Term 4.2.1:::: Definition 4.2.1 Term 4.2.2:::: Definition 4.2.2 Term 4.3::: Definition 4.3 Term 5:: Definition 5	Labeled Term 1 Definition 1 Term 2 Definition 2 Term 2.1 Definition 2.1 Term 2.2 Definition 2.2 Term 3 Definition 3 Term 4 Definition 4 Term 4.1 Definition 4.1 Term 4.2 Definition 4.2 Term 4.2.1 Definition 4.2.1 Term 4.2.2 Definition 4.2.2 Term 4.3 Definition 4.3 Term 5 Definition 5
.Labeled 2 Term 1;; Definition 1 Term 1.1:: Definition 1.1	Labeled 2 Term 1 Definition 1 Term 1.1 Definition 1.1
[horizontal] .Labeled horizontal Term 1:: Definition 1 Term 2:: Definition 2 Term 3:: Definition 3 Term 4:: Definition 4	Labeled horizontal Term 1 Definition 1 Term 2 Definition 2 Term 3 Definition 3 Term 4 Definition 4
[qanda] .Q&A Question 1:: Answer 1 Question 2:: Answer 2	Q&A Question 1 Answer 1 Question 2 Answer 2
.Break two lists . number . number Independent paragraph break list. . number .Header break list too . number -- . List block define list boundary too . number . number -- . number . number	Break two lists number number Independent paragraph break list. number Header break list too number List block define list boundary too number number number number
.Continuation - bullet continuation . number continuation * bullet literal continuation .. letter + Non-literal continuation. + ---- any block can be included in list ---- + Last continuation.	Continuation bullet continuation number continuation bullet literal continuation letter Non-literal continuation. any block can be included in list Last continuation.
.List block allow sublist inclusion - bullet * bullet + -- - bullet * bullet -- * bullet - bullet . number .. lower alpha + -- . number .. lower alpha -- .. lower alpha . number	List block allow sublist inclusion bullet bullet bullet bullet bullet bullet number lower alpha number lower alpha lower alpha number

Tables

.An example table [options="header,footer"] |======================= |Col 1|Col 2 |Col 3 |1 |Item 1 |a |2 |Item 2 |b |3 |Item 3 |c |6 |Three items|d |=======================	Table 1. An example table Col 1 Col 2 Col 3 1 Item 1 a 2 Item 2 b 3 Item 3 c 6 Three items d
.CSV data [format="csv",cols="4"] |====== 1,2,3,4 a,b,c,d A,B,C,D |======	Table 2. CSV data 1 2 3 4 a b c d A B C D
[format="csv"] [options="header",cols=",,s,,m"] |=========================== ID,FName,LName,Address,Phone 1,Vasya,Pupkin,London,+123 2,X,Y,"A,B",45678 |===========================	ID FName LName Address Phone 1 Vasya Pupkin London +123 2 X Y A,B 45678
.Multiline cells, row/col span |==== |Date |Duration |Avg HR |Notes |22-Aug-08 .2+^.^|10:24 | 157 | Worked out MSHR (max sustainable heart rate) by going hard for this interval. |22-Aug-08 | 152 | Back-to-back with previous interval. |24-Aug-08 3+^|none |====	Table 3. Multiline cells, row/col span Date Duration Avg HR Notes 22-Aug-08 10:24 157 Worked out MSHR (max sustainable heart rate) by going hard for this interval. 22-Aug-08 152 Back-to-back with previous interval. 24-Aug-08 none

Does anyone else notice that you cannot escape the processing of www.example.com? I've tried ++ and \ and Github seems to always link it. Ideas?

At a glance only code-like formatting works, e.g. `www.example.com` or

....
www.example.com
....

Is there a way to do note or warning blocks like in md?

> [!NOTE]
> This is an amazing note.

Is there a way to do note or warning blocks like in md?

Yes, and this cheatsheet has it.

@powerman You mean this?

.Optional Title
[NOTE]
====
*NOTE* Block

Use: multi-paragraph notes.
====

and

.Optional Title
NOTE: This is an example
      single-paragraph note.

The thing is the rendering is not the same. W/ extensions I can get icons I’ve seen, which is slightly better :)
But the exact one we have from md is not possible, right?

Yeah, rendering is different - no surprise, these are different formats so no reason to expect same rendering. You can try to manually embed some image if you want to simulate md rendering.