full.adoc

Asciidoc cheatsheet for GitHub

Table of Contents

• Attributes
• Headers
• Level 1
• Level 1
• Paragraphs
• Blocks
• Text
• Macros: links, images & include
• Lists
• Tables

// Comments will be used to note differences from default Asciidoc behaviour,
// some may be bugs, others may be specifics of GitHub or AsciiDoctor.

// Below is header of this document:

Asciidoc cheatsheet for GitHub
==============================
Optional Author Name <optional@author.email>
:Revision: 1.0
:Some attribute: Some value
:toc:
:toclevels: 1

// Both author name/email, and even :Revision: attribute should be rendered
// under document title, but they're not.

Attributes

Author is "{author}" with email <{email}>, some attribute's value is {someattribute}. // Line with unknown attribute must be // removed, but it's not. Line with attribute like {nosuchattribute}. Escaped: \{author} and +++{author}+++	Author is "Optional Author Name" with email <optional@author.email>, some attribute’s value is Some value. Line with attribute like {nosuchattribute}. Escaped: {author} and {author}
//// TIP: You can use attributes to setup auto-generated table of contents, for ex.: :toc: :toclevels: 3 Then put this line where you want to insert table of contents: toc::[] In GitHub Wiki table of contents looks worse than in file, especially multi-level one, because it include list bullets. ////

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.
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

// Paragraph title is not highlighted. .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.
// Type of block (NOTE/TIP/…) should be // shown as an icon, not as text. .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.	Tip Some tip text.
IMPORTANT: Some important text.	Important Some important text.
WARNING: Some warning text.	Warning Some warning text.
CAUTION: Some caution 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 # (require `source-highlight` or `pygmentize`) use DBI; my $dbh = DBI->connect('...',$u,$p) or die "connect: $dbh->errstr"; ----	Optional Title # *Source* block # Use: highlight code listings # (require `source-highlight` or `pygmentize`) use DBI; my $dbh = DBI->connect('...',$u,$p) or die "connect: $dbh->errstr";
// Sidebar block isn't highlighted. .Optional Title **** *Sidebar* Block Use: sidebar notes :) ****	Optional Title Sidebar Block Use: sidebar notes :)
// Example block isn't highlighted. .Optional Title ========================== *Example* Block Use: examples :) ========================== // Example caption removed, not changed. [caption="Custom: "] ========================== Default caption "Example:" can be changed. ==========================	Example 1. Optional Title Example Block Use: examples :) Default caption "Example:" can be changed.
.Optional Title [NOTE] =============================== *NOTE* Block Use: multi-paragraph notes. ===============================	Note Optional Title NOTE Block Use: multi-paragraph notes.
//// *Comment* block Use: hide comments ////
++++ *Passthrough* Block <p> Use: backend-specific markup like <table border="1"> <tr><td>1</td><td>2</td></tr> </table> ++++	*Passthrough* Block Use: backend-specific markup like 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.
.Optional Title [quote, cite author, cite source] ____ *Quote* Block Use: cite somebody ____	Optional Title Quote Block Use: cite somebody — cite author cite source

Text

forced + line break	forced line break
normal, _italic_, *bold*, +mono+. ``double quoted'', `single quoted'. normal, ^super^, ~sub~.	normal, italic, bold, mono. “double quoted”, ‘single quoted’. normal, super, sub.
Command: `ls -al` +mono *bold*+ `passthru *bold*`	Command: ls -al mono bold passthru *bold*
Path: '/some/filez.txt', '.b'	Path: /some/filez.txt, .b
// Colors and font size doesn't change. [red]#red text# [yellow-background]#on yellow# [big]#large# [red yellow-background big]*all bold*	red text on yellow large all bold
Chars: n__i__**b**++m++[red]##r##	Chars: nibmr
// Comment
(C) (R) (TM) -- ... -> <- => <= &#182;	© ® ™ — …​ → ← ⇒ ⇐ ¶
''''
// Differs from Asciidoc, but it's hard to say who's correct. Escaped: \_italic_, +++_italic_+++, t\__e__st, +++t__e__st+++, +++<b>bold</b>+++, $$<b>normal</b>$$ \&#182; \`not single quoted' \`\`not double quoted''	Escaped: _italic_, _italic_, t__e__st, t__e__st, bold, <b>normal</b> &#182; ‘not single quoted’ `\`not double quoted''

Macros: links, images & include

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

[[anchor-1]] Paragraph or block 1. // This type of anchor doesn't work anchor:anchor-2[] Paragraph or block 2. <<anchor-1>>, <<anchor-1,First anchor>>, xref:anchor-2[], xref:anchor-2[Second anchor].	Paragraph or block 1. Paragraph or block 2. [anchor-1], First anchor, [anchor-2], Second anchor.
// Link "root" is root of repo. link:README.adoc[This document] link:README.adoc[] link:/[This site root]	This document README.adoc This site root
http://google.com http://google.com[Google Search] mailto:root@localhost[email admin]	http://google.com Google Search 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 , second home . Figure 1. Block image Thumbnail linked to full image
// include\:\: is replaced with link: This is example how files can be included. link:footer.txt[role=include] [source,perl] ---- link:script.pl[role=include] ----	This is example how files can be included. role=include link:script.pl[role=include]

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	Bulleted 2 bullet bullet
// Markers differs from Asciidoc. .Ordered . number . number .. letter .. letter . number .. loweralpha .. loweralpha ... lowerroman ... lowerroman .... upperalpha .... upperalpha ..... upperroman ..... upperroman .... upperalpha ... lowerroman .. loweralpha . number	Ordered number number letter letter number loweralpha loweralpha lowerroman lowerroman upperalpha upperalpha upperroman upperroman upperalpha lowerroman loweralpha number
.Ordered 2 a. letter b. letter .. letter2 .. letter2 . number . number 1. number2 2. number2 3. number2 4. number2 . number .. letter2 c. letter	Ordered 2 letter letter letter2 letter2 number number number2 number2 number2 number2 number letter2 letter
.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 lists looks wrong. [horizontal] .Labeled horizontal Term 1:: Definition 1 Term 2:: Definition 2 [horizontal] Term 2.1;; Definition 2.1 Term 2.2;; Definition 2.2 Term 3:: Definition 3 Term 4:: Definition 4 [horizontal] Term 4.1::: Definition 4.1 Term 4.2::: Definition 4.2 [horizontal] 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 horizontal 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
[qanda] .Q&A Question 1:: Answer 1 Question 2:: Answer 2	Q&A Question 1 Answer 1 Question 2 Answer 2
// Bug: (B) should be same level as (A) .Indent is optional - bullet * another bullet 1. number . again number (A) a. letter .. again letter .. letter . number (B) * bullet - bullet	Indent is optional bullet another bullet number again number (A) letter again letter letter number (B) bullet bullet
.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 .. letter + -- . number .. letter -- .. letter . number	List block allow sublist inclusion bullet bullet bullet bullet bullet bullet number letter number letter letter number

Tables

You can fill table from CSV file using include:: macros inside table.

// Table footer doesn't highlighted. .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
// Table width, frame and grid control doesn't work. .CSV data, 15% each column [format="csv",width="60%",cols="4"] [frame="topbot",grid="none"] |====== 1,2,3,4 a,b,c,d A,B,C,D |======	Table 2. CSV data, 15% each column 1 2 3 4 a b c d A B C D
// Table column align doesn't work. [grid="rows",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