Yet another ASCIIDoc, Markdown and RestructuredText cheatsheet

5 min read. | 22670 words.

Comments

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
 
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 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 (Source)

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

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

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

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 (Source)

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

Comments

Comments powered by Disqus