Asciidoc cheatsheet for GitHub
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.
GitHub Wiki has own limitations, check
this cheatsheet in wiki.
GitHub Gist has own limitations, check
this cheatsheet in gist.
You can try these browser add-ons to fix some issues:
Attributes
// Header of this document:
Asciidoc cheatsheet for GitHub
==============================
:toc:
:toc-placement: preamble
:toclevels: 1
: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}. |
Section titles
== Level 1 Text. === Level 2 Text. ==== Level 3 Text. ===== Level 4 Text. |
Level 1Text. Level 2Text. Level 3Text. Level 4Text. |
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.
|
| ||||||||
.Optional Title [NOTE] This is an example single-paragraph note. |
| ||||||||
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. ==== |
| ||
.Optional Title [quote, cite author, cite source] ____ *Quote* Block Use: cite somebody ____ |
Optional Title
— 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
| ||
.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 |
normal, 'italic', _italic_, *bold*. +mono *bold*+, `mono pass thru *bold*` ``double quoted'', `single quoted'. normal, ^super^, ~sub~. |
normal, italic, italic, bold.
“double quoted”, ‘single quoted’. normal, super, sub. |
Chars: n__i__**b**++m++n |
Chars: nib |
// Comment | |
(C) (R) (TM) -- ... -> <- => <= ¶ |
© ® ™ — … → ← ⇒ ⇐ ¶ |
'''' |
|
Escaped: \_italic_, +++_italic_+++, t\__e__st, +++t__e__st+++, \¶ |
Escaped: _italic_, _italic_, t__e__st, t__e__st, ¶ |
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. |
link:README.adoc[This document] link:/README.adoc[] | |
http://google.com http://google.com[Google Search] mailto:root@localhost[email admin] | |
First home image:images/icons/home.png[] , second home image:images/icons/home.png[Alt text] . .Block image image::images/icons/home.png[] image::images/icons/home.png[Alt text] .Thumbnail linked to full image image:/images/font/640-screen2.gif[ "My screenshot",width=128, link="/images/font/640-screen2.gif"] |
First 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
| ||||||||
.Bulleted 2
- bullet
* bullet
** bullet
*** bullet
|
Bulleted 2
| ||||||||
.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
| ||||||||
.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
| ||||||||
.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
| ||||||||
.Labeled 2
Term 1;;
Definition 1
Term 1.1::
Definition 1.1
|
Labeled 2
| ||||||||
[horizontal]
.Labeled horizontal
Term 1:: Definition 1
Term 2:: Definition 2
Term 3::
Definition 3
Term 4:: Definition 4
|
Labeled horizontal
| ||||||||
[qanda]
.Q&A
Question 1::
Answer 1
Question 2:: Answer 2
|
Q&A
| ||||||||
.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
Independent paragraph break list.
Header break list too
| ||||||||
.Continuation - bullet continuation . number continuation * bullet literal continuation .. letter + Non-literal continuation. + ---- any block can be included in list ---- + Last continuation. |
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
|
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
| |||||||||||||||
.CSV data [format="csv",cols="4"] |====== 1,2,3,4 a,b,c,d A,B,C,D |====== |
Table 2. CSV data
| |||||||||||||||
[format="csv"] [options="header",cols=",,s,,m"] |=========================== 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
| |||||||||||||||