DEV Community

Diego Carrasco Gubernatis
Diego Carrasco Gubernatis

Posted on • Originally published at diegocarrasco.com on

Yet another ASCIIDoc, Markdown and RestructuredText cheatsheet

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

AWS Security LIVE!

Tune in for AWS Security LIVE!

Join AWS Security LIVE! for expert insights and actionable tips to protect your organization and keep security teams prepared.

Learn More

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more