DEV Community

Diego Carrasco Gubernatis
Diego Carrasco Gubernatis

Posted on • Originally published at diegocarrasco.com on

Yet another ASCIIDoc, Markdown and RestructuredText cheatsheet

#asciidoc #asciidoctor #cheatsheet #markdown

Table of Contents

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

  • 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

Table 1. Markup languages comparison and cheatsheet| Element | Markdown | Rest | ASCIIDoc |
| --- | --- | --- | --- |
|

Headers

|

# Header 1

## Header 2

### Header 3

#### Header 4
Enter fullscreen mode Exit fullscreen mode

|

Header 1
========

Header 2
--------

Header 3
~~~~~~~~

Header 4
$$$$$$$$
Enter fullscreen mode Exit fullscreen mode

|

= Header 1

== Header 2

=== Header 3

==== Header 4
Enter fullscreen mode Exit fullscreen mode

|
|

Links

|

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

[This link](http://example.net/) has no title attribute.
Enter fullscreen mode Exit fullscreen mode

|

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

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

`Internal and External links`_
Enter fullscreen mode Exit fullscreen mode

|

https://asciidoctor.org[]

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

he section <<anchors>> describes how automatic anchors work.
Enter fullscreen mode Exit fullscreen mode

|
|

Bold text

|

**Bold text**
Enter fullscreen mode Exit fullscreen mode

|

**Bold text**
Enter fullscreen mode Exit fullscreen mode

|

**Bold text**
Enter fullscreen mode Exit fullscreen mode

|
|

Italic text

|

*Italic text*
Enter fullscreen mode Exit fullscreen mode

|

*Italic text*
Enter fullscreen mode Exit fullscreen mode

|

_Italic text_
Enter fullscreen mode Exit fullscreen mode

|
|

underlined text

|

N/A
Enter fullscreen mode Exit fullscreen mode

|

N/A
Enter fullscreen mode Exit fullscreen mode

|

[.underline]#underlined text#
Enter fullscreen mode Exit fullscreen mode

underlined text

|
|

Strikethrough text

|

~~Strikethrough text~~
Enter fullscreen mode Exit fullscreen mode

|

N/A
Enter fullscreen mode Exit fullscreen mode

|

[.line-through]#line-through#
Enter fullscreen mode Exit fullscreen mode

|
|

Custom style (role in Asciidoc)

|

|

|

[.myrole]#custom role# must be fulfilled by the theme.
Enter fullscreen mode Exit fullscreen mode

|
|

Quotation (simple)

|

> Quotation
Enter fullscreen mode Exit fullscreen mode

|

Quotation
---------
Enter fullscreen mode Exit fullscreen mode

|

Quotation
Enter fullscreen mode Exit fullscreen mode

|
|

Quotation (with author and title)

|

> Author
> Title
>
> Quotation
>
> -- Author
>
> ====
Enter fullscreen mode Exit fullscreen mode

|

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

   Quotation

   -- Author
   ====
Enter fullscreen mode Exit fullscreen mode

|

[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.
Enter fullscreen mode Exit fullscreen mode

|
|

Code snippets

|

`this is an inline code`
Enter fullscreen mode Exit fullscreen mode


language
this is a block of code with highlighting

Enter fullscreen mode Exit fullscreen mode

|

.. 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.')
Enter fullscreen mode Exit fullscreen mode

This is a directive with many options. Check 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
----
Enter fullscreen mode Exit fullscreen mode

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
----
Enter fullscreen mode Exit fullscreen mode

|
|

Image (simple)

|

![Alt text](/path/to/img.jpg)
Enter fullscreen mode Exit fullscreen mode

|

.. image:: /path/to/img.jpg
Enter fullscreen mode Exit fullscreen mode

|

.Image title
image::path/to/image.png[]
Enter fullscreen mode Exit fullscreen mode

|
|

Variables

|

N/A
Enter fullscreen mode Exit fullscreen mode

|

N/A
Enter fullscreen mode Exit fullscreen mode

|

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

{url-feedback}
Enter fullscreen mode Exit fullscreen mode

|
|

Table (simple)

|

markdown-simple-table-example.md(Source)

....
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Row 1 | Data 1 | Data 2 |
| Row 2 | Data 3 | Data 4 |
....
Enter fullscreen mode Exit fullscreen mode

|

rst-simple-table-example.rst(Source)

.. table::
   :class: my-table

   +------------+------------+------------+
   | Header 1 | Header 2 | Header 3 |
   +============+============+============+
   | Row 1 | Data 1 | Data 2 |
   +------------+------------+------------+
   | Row 2 | Data 3 | Data 4 |
   +------------+------------+------------+
Enter fullscreen mode Exit fullscreen mode

|

asciidoc-simple-table-example.adoc(Source)

[options="header"]
|===
| Header 1 | Header 2 | Header 3
| Row 1 | Data 1 | Data 2
| Row 2 | Data 3 | Data 4
|===
Enter fullscreen mode Exit fullscreen mode

|
|

References in-document (simple)

|

[reference to a section](#section)

# Section
Enter fullscreen mode Exit fullscreen mode

|

.. _my-reference-label:

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

See :ref:`my-reference-label`
Enter fullscreen mode Exit fullscreen mode

|

set the anchor

[#_what_is_an_advertising_channel_provider_a_channel_and_a_format]
Enter fullscreen mode Exit fullscreen mode

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

<<_anchor_to_section_or_content>>
Enter fullscreen mode Exit fullscreen mode

|
|

Table (with code snippet)

|

N/A
Enter fullscreen mode Exit fullscreen mode

|

N/A
Enter fullscreen mode Exit fullscreen mode

|

asciidoc-table-with-code-snippet.adoc(Source)

|===
a| Source code example:

[source,python]
----
print("Hello, World!")
----
|===
Enter fullscreen mode Exit fullscreen mode

|
|

Line/ Separator

|

---
Enter fullscreen mode Exit fullscreen mode

|

.. line-block::

   ----------------
Enter fullscreen mode Exit fullscreen mode

|

'''
Enter fullscreen mode Exit fullscreen mode

|

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

Top comments (0)

Read next

scofieldidehen profile image

Call, Send, and Transfer: The Payment gateway for Web3

Scofield Idehen -

sashkan profile image

4 key skills to step up to Senior

Pierre Olivier TRAN -

prahladyeri profile image

The illusion of simplicity: how OOP can overcomplicate simple problems

Prahlad Yeri -

choir241 profile image

Low-Level Documentation

Richard Choi -