Skip to content

Instantly share code, notes, and snippets.

@powerman
Last active July 4, 2024 12:42
Show Gist options
  • Save powerman/d56b2675dfed38deb298 to your computer and use it in GitHub Desktop.
Save powerman/d56b2675dfed38deb298 to your computer and use it in GitHub Desktop.
Asciidoc cheatsheet for GitHub

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.

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

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

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

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]
// 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 home , second home Alt text .

home
Figure 1. Block image
Alt text
Thumbnail linked to full image

My screenshot

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

  2. number

    1. lower roman

    2. lower roman

  3. number

    1. lower roman

    2. lower roman

      1. lower alpha

      2. lower alpha

        1. lower alpha

        2. lower alpha

          1. lower alpha

          2. lower alpha

        3. lower alpha

      3. lower alpha

    3. lower roman

  4. 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
  1. lower alpha

  2. lower alpha

    1. lower roman

    2. lower roman

      1. lower alpha

      2. lower alpha

        1. lower alpha

        2. lower alpha

        3. lower alpha

        4. lower alpha

      3. lower alpha

    3. lower roman

  3. 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
  1. Question 1

    Answer 1

  2. 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
  1. number

  2. number

Independent paragraph break list.

  1. number

Header break list too
  1. number

  1. List block define list boundary too

  2. number

  3. number

  1. number

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

    1. number continuation

      • bullet

        literal continuation
        1. 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

    1. number

      1. lower alpha

        1. number

          1. lower alpha

      2. lower alpha

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

@frostbytten
Copy link

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?

@powerman
Copy link
Author

powerman commented Aug 5, 2022

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

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

@Frizlab
Copy link

Frizlab commented Nov 15, 2023

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

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

@powerman
Copy link
Author

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

Yes, and this cheatsheet has it.

@Frizlab
Copy link

Frizlab commented Nov 15, 2023

@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?

@powerman
Copy link
Author

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.

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