Yet another ASCIIDoc, Markdown and RestructuredText cheatsheet

Diego Carrasco G. — Tue, 19 Dec 2023 15:00:00 GMT

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 AsciiDoc AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain text mark-up conventions. AsciiDoc documents can be created using any text editor and read “as-is”, or rendered to HTML or any other format supported by a DocBook tool-chain, i.e., PDF, TeX, Unix manpages, e-books, slide presentations, etc. Common file extensions for AsciiDoc files are adoc and historically txt (as encouraged by AsciiDoc's creator). , Markdown Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004 as an easy-to-read markup language. Markdown is widely used for blogging, instant messaging, and large language models, and also used elsewhere in online forums, collaborative software, documentation pages, and readme files. and ReStructuredText reStructuredText (RST, ReST, or reST) is a plain-text markup language primarily used for technical documentation and other textual data. It serves a role similar to that of Markdown but includes additional semantic features for more complex document structuring. Prominent, large-scale, open-source projects that rely on reStructuredText include the Python programming language community for its official documentation, the Linux kernel docs, CMake, and the LLVM compiler project. depending on the kind of text. Each Markup_language A markup language is a text-encoding system which specifies the structure and formatting of a document and potentially the relationships among its parts. Markup can control the display of a document or enrich its content to facilitate automated processing. 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.