Yet another ASCIIDoc, Markdown and RestructuredText cheatsheet
Tags: asciidoc, asciidoctor, cheatsheet, markdown
Published: 2024-01-17 17:25:20

---
title: Yet another ASCIIDoc, Markdown and RestructuredText cheatsheet
published: true
date: 2023-12-19 15:00:00 UTC
tags: asciidoc,asciidoctor,cheatsheet,markdown
canonical_url: https://diegocarrasco.com/markup-languages-cheatsheet/
---

![](https://diegocarrasco.com/images/social-images/markup-languages-cheatsheet.jpg)

 

Table of Contents

- [Context](https://diegocarrasco.com/markup-languages-cheatsheet/#_context)
- [Markdown: For Simplicity and Readability](https://diegocarrasco.com/markup-languages-cheatsheet/#_markdown_for_simplicity_and_readability)
- [RestructuredText: For Web Content Richness](https://diegocarrasco.com/markup-languages-cheatsheet/#_restructuredtext_for_web_content_richness)
- [ASCIIDoc: For long-form articles and books](https://diegocarrasco.com/markup-languages-cheatsheet/#_asciidoc_for_long_form_articles_and_books)
- [Comparison Table](https://diegocarrasco.com/markup-languages-cheatsheet/#_comparison_table)

| | This article is a cheatsheet/ summary on the (my) most used markup languages. It is not a tutorial, but a quick reference for those who already know the basics of each markup language. |

| | This article is a work-in-progress and has a long table with many columns. If you are reading this on a mobile device, you may want to switch to landscape mode or use a bigger screen. |

### Context

I write using , and depending on the kind of text. Each has its pros and contras, and I think that using the right tool for each job makes a lot of sense.

**This article is a cheatsheet of the most common elements I use in each markup language. I will be updating it as I find/ remember elements that I need to use.** == TLDR

Markdown is my go-to for simple articles, RestructuredText for complex web content, and ASCIIDoc for long-form, feature-rich projects. Understanding the strengths and limitations of each helps me optimize my content creation process.

Because of that my use of markup languages is usually as follows:

### Markdown: For Simplicity and Readability

- **When I Use It** : Ideal for articles that don’t require complex formatting. I often use it for posts without a Table of Contents or advanced code snippets. **That is the case in most of the articles I write and all my personal notes.**

- **Why** : Markdown’s simplicity and readability make it perfect for quick, clean content. It helps me **keep the structure lean and stay focused on the content**.

- **Limitations** : I avoid using Markdown for content needing advanced elements like admonitions or tables, as these are challenging to implement effectively in Markdown. For some of this features, I wrote some [shortcodes](https://diegocarrasco.com/nikola-custom-shortcodes) for Nikola (the static site generator I use).

### RestructuredText: For Web Content Richness

- **When I Use It** : Chosen for articles on my website that demand more sophisticated elements. I use it mainly for articles with admonitions.

- **Why** : Its support for directives like tables, admonitions, notes, and warnings makes RestructuredText versatile for web-centric content.

- **Flexibility** : It strikes a balance between simplicity and advanced formatting, filling the gap where Markdown falls short. (Although I have to admit that I am not a big fan of the syntax, such as the headings)

### ASCIIDoc: For long-form articles and books

- **When I Use It** : My preference for long-form articles, books, and other comprehensive documentation. I am using it for my [book on digital marketing](https://diegocarrasco.com/digital-marketing-playbook)

- **Why** : ASCIIDoc’s rich feature set allows for intricate structure and extensive customization. Its ability to include external files, define variables, and apply themes makes it unbeatable for complex projects.

- **Output Variety** : The flexibility to compile content into formats like EPUB, PDF, and HTML is particularly valuable for diverse publishing needs.

### Comparison Table

<caption>Table 1. Markup languages comparison and cheatsheet</caption>| Element | Markdown | Rest | ASCIIDoc |
| --- | --- | --- | --- |
| 

Headers

 | 

```
# Header 1

## Header 2

### Header 3

#### Header 4
```

 | 

```
Header 1
========

Header 2
--------

Header 3
~~~~~~~~

Header 4
$$$$$$$$
```

 | 

```
= Header 1

== Header 2

=== Header 3

==== Header 4
```

 |
| 

Links

 | 

```
This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.
```

 | 

```
`<http://www.python.org/>`_

`Python <http://www.python.org/>`_

`Internal and External links`_
```

 | 

```
https://asciidoctor.org[]

Ask questions in the https://chat.asciidoc.org[*community chat*].

he section <<anchors>> describes how automatic anchors work.
```

 |
| 

Bold text

 | 

```
**Bold text**
```

 | 

```
**Bold text**
```

 | 

```
**Bold text**
```

 |
| 

Italic text

 | 

```
*Italic text*
```

 | 

```
*Italic text*
```

 | 

```
_Italic text_
```

 |
| 

underlined text

 | 

```
N/A
```

 | 

```
N/A
```

 | 

```
[.underline]#underlined text#
```

underlined text

 |
| 

Strikethrough text

 | 

```
~~Strikethrough text~~
```

 | 

```
N/A
```

 | 

```
[.line-through]#line-through#
```

 |
| 

Custom style (role in Asciidoc)

 | 

 | 

 | 

```
[.myrole]#custom role# must be fulfilled by the theme.
```

 |
| 

Quotation (simple)

 | 

```
> Quotation
```

 | 

```
Quotation
---------
```

 | 

```
Quotation
```

 |
| 

Quotation (with author and title)

 | 

```
> Author
> Title
>
> Quotation
>
> -- Author
>
> ====
```

 | 

```
Quotation
=========
   Author
   Title
   -----

   Quotation

   -- Author
   ====
```

 | 

```
[quote,attribution,citation title and information]
Quote or excerpt text

[quote, Author, Title]
Quotation

Check https://docs.asciidoctor.org/asciidoc/latest/blocks/blockquotes/ for more information.
```

 |
| 

Code snippets

 | 

```
`this is an inline code`

```language
this is a block of code with highlighting
```
```

 | 

```
.. code-block:: ruby

   Some Ruby code.

.. code-block:: ruby
   :lineno-start: 10

   Some more Ruby code, with line numbering starting at 10.

.. code-block:: python
   :emphasize-lines: 3,5

   def some_function():
       interesting = False
       print('This line is highlighted.')
       print('This one is not...')
       print('...but this one is.')
```

This is a directive with many options. Check [https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block) for more information.

 | 

```
[source, python]
----
import pandas as pd

df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
# more code
----
```

if you want to put a code snippet in a bullet point list or similar, you have to add it in a new line after a +. This way it will have the same indentation and will be part of the same **div**

```
- point in bullet point list
+
[source, python]
----
# here goes your code
----
```

 |
| 

Image (simple)

 | 

```
![Alt text](/path/to/img.jpg)
```

 | 

```
.. image:: /path/to/img.jpg
```

 | 

```
.Image title
image::path/to/image.png[]
```

 |
| 

Variables

 | 

```
N/A
```

 | 

```
N/A
```

 | 

```
:url-feedback: http://practicalbooks.com/xyz

{url-feedback}
```

 |
| 

Table (simple)

 | 

[markdown-simple-table-example.md](https://diegocarrasco.com/listings/markdown-simple-table-example.md.html)[(Source)](https://diegocarrasco.com/listings/markdown-simple-table-example.md)

```
....
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Row 1 | Data 1 | Data 2 |
| Row 2 | Data 3 | Data 4 |
....

```

 | 

[rst-simple-table-example.rst](https://diegocarrasco.com/listings/rst-simple-table-example.rst.html)[(Source)](https://diegocarrasco.com/listings/rst-simple-table-example.rst)

```
.. table::
   :class: my-table

   +------------+------------+------------+
   | Header 1 | Header 2 | Header 3 |
   +============+============+============+
   | Row 1 | Data 1 | Data 2 |
   +------------+------------+------------+
   | Row 2 | Data 3 | Data 4 |
   +------------+------------+------------+

```

 | 

[asciidoc-simple-table-example.adoc](https://diegocarrasco.com/listings/asciidoc-simple-table-example.adoc.html)[(Source)](https://diegocarrasco.com/listings/asciidoc-simple-table-example.adoc)

```
[options="header"]
|===
| Header 1 | Header 2 | Header 3
| Row 1 | Data 1 | Data 2
| Row 2 | Data 3 | Data 4
|===

```

 |
| 

References in-document (simple)

 | 

```
[reference to a section](#section)

# Section
```

 | 

```
.. _my-reference-label:

Section Title
-------------

See :ref:`my-reference-label`
```

 | 

set the anchor

```
[#_what_is_an_advertising_channel_provider_a_channel_and_a_format]
```

call the anchor. Thsi will use the title of the section it refers to.

```
<<_anchor_to_section_or_content>>
```

 |
| 

Table (with code snippet)

 | 

```
N/A
```

 | 

```
N/A
```

 | 

[asciidoc-table-with-code-snippet.adoc](https://diegocarrasco.com/listings/asciidoc-table-with-code-snippet.adoc.html)[(Source)](https://diegocarrasco.com/listings/asciidoc-table-with-code-snippet.adoc)

```
|===
a| Source code example:

[source,python]
----
print("Hello, World!")
----
|===

```

 |
| 

Line/ Separator

 | 

```
---
```

 | 

```
.. line-block::

   ----------------
```

 | 

```
'''
```

 |

| | By the way, this article and cheatsheets were made using asciidoc and the Nikola Listings feature. |