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)