My RST cheatsheet

Created on:
Tags: test, post
Reading time: 2 minutes

The reStructuredText Cheat Sheet: Syntax Reminders

Info

See <https://docutils.sourceforge.io/rst.html> for introductory docs.

Author

David Goodger <[email protected]>

Date

$Date: 2022-01-20 11:11:44 +0100 (Do, 20. Jän 2022) $

Revision

$Revision: 8956 $

Description

This is a "docinfo block", or bibliographic field list

Note

If you are reading this as HTML, please read cheatsheet.txt instead to see the input syntax examples!

〉 Section Structure

Section titles are underlined or overlined & underlined.

〉 Body Elements

Grid table:

Paragraphs are flush-left, separated by blank lines.

Block quotes are indented.

Literal block, preceded by "::": 

Indented

+--------------------------------+ or:: | | >>> print 'Doctest block' | | | Doctest block | > Quoted | +--------------------------------+-----------------------------------+ | | Line blocks preserve line breaks & indents. [new in 0.3.6] | | | Useful for addresses, verse, and adornment-free lists; long | | lines can be wrapped with continuation lines. | +--------------------------------------------------------------------+

Simple tables:

List Type Examples (syntax in the text source)
Bullet list * items begin with "-", "+", or "*"

Enumerated list

  1. items use any variation of "1.", "A)", and "(i)"
  2. also auto-enumerated

Definition list

Term is flush-left : optional classifier

Definition is indented, no blank line between

Field list
field name

field body

Option list -o at least 2 spaces between option & description
Explicit Markup Examples (visible in the text source)

Footnote

Citation

Hyperlink Target

Anonymous Target __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
Directive ("::")

image

Substitution Def
Comment

Empty Comment

(".." on a line by itself, with blank lines before & after, used to separate indentation contexts)

〉 Inline Markup

emphasis; strong emphasis; interpreted text; interpreted text with role; inline literal text; standalone hyperlink, https://docutils.sourceforge.io; named reference, reStructuredText; anonymous reference__; footnote reference,; citation reference, [CIT2002]; ; _inline internal target.

〉 Directive Quick Reference

See <https://docutils.sourceforge.io/docs/ref/rst/directives.html> for full info.

Directive Name Description (Docutils version added to, in [brackets])

attention

Specific admonition; also "caution", "danger", "error", "hint", "important", "note", "tip", "warning"

admonition Generic titled admonition: .. admonition:: By The Way
image .. image:: picture.png; many options possible
figure Like "image", but with optional caption and legend
topic .. topic:: Title; like a mini section
sidebar .. sidebar:: Title; like a mini parallel document
parsed-literal A literal block with parsed inline markup
rubric .. rubric:: Informal Heading
epigraph Block quote with class="epigraph"
highlights Block quote with class="highlights"
pull-quote Block quote with class="pull-quote"
compound Compound paragraphs [0.3.6]
container Generic block-level container element [0.3.10]
table Create a titled table [0.3.1]
list-table Create a table from a uniform two-level bullet list [0.3.8]
csv-table Create a table from CSV data [0.3.4]
contents Generate a table of contents
sectnum Automatically number sections, subsections, etc.
header, footer Create document decorations [0.3.8]
target-notes Create an explicit footnote for each external target
math Mathematical notation (input in LaTeX format)
meta Document metadata
include Read an external reST file as if it were inline
raw Non-reST data passed untouched to the Writer
replace Replacement text for substitution definitions
unicode Unicode character code conversion for substitution defs
date Generates today's date; for substitution defs
class Set a "class" attribute on the next element
role Create a custom interpreted text role [0.3.2]
default-role Set the default interpreted text role [0.3.10]
title Set the metadata document title [0.3.10]

〉 Interpreted Text Role Quick Reference

See <https://docutils.sourceforge.io/docs/ref/rst/roles.html> for full info.

Role Name Description
emphasis Equivalent to emphasis
literal Equivalent to literal but processes backslash escapes
math Mathematical notation (input in LaTeX format)
PEP Reference to a numbered Python Enhancement Proposal
RFC Reference to a numbered Internet Request For Comments
raw For non-reST data; cannot be used directly (see docs) [0.3.6]
strong Equivalent to strong
sub Subscript
sup Superscript
title Title reference (book, etc.); standard default role

Code blocks

Apparently HUGO does not allow you to set the fucking commands to rst2html. So I cant even enable fucking highlighting... (see https://baturin.org/blog/why-not-hugo/) --> Look into https://soupault.app/ 

For RST, you get hardcoded --leave-comments --initial-header-level=2 and that's it.

Also check rst2html vs pandoc. Pandoc looks like its way more flexible -> possibly a better starting point

〉 C++ 

int main() {
  throw std::runtime_error("You missed a semicolon somewhere")
  return 0;
}

〉 Python 

def my_function():
  "just a test"
  print 8/2

〉 HTML 

:linenos:

<h1>code block example</h1>

〉 Custom highlighting

An example of using Custom highlighting

Last modified: 2024-09-28