Restructuredtext Markdown
ReStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. ReStructuredText is designed for extensibility for specific application domains. Writing content in reStructuredText is only recommended for users who are already familiar with it. For others, we recommend using MyST Markdown, which has all of the same features of rST and Sphinx, but with a Markdown flavour. “reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. ReStructuredText is designed for extensibility for specific application domains.
In addition to writing your content in Markdown, Jupyter Book also supportswriting content in reStructuredText,another markup language that is common in the Python documentation community.
Warning
Writing content in reStructuredText is only recommended for users who are alreadyfamiliar with it.For others, we recommend using MyST Markdown,which has all of the same features of rST and Sphinx, but with a Markdown flavour.
Because Jupyter Book uses Sphinx under the hood, any document that is written in rSTfor the Sphinx ecosystem should also work with Jupyter Book. This is particularlyuseful if you’ve already got a significant amount of documentation written in rSTand you’d like to try it out with Jupyter Book.
For more information on writing content with reStructuredText, we recommendreading the Sphinx rST documentation.
Markdown Vs Restructuredtext
Including reStructuredText in Markdown¶
To insert rST into Markdown, you can use the eval-rst directive:
Note
A note written in reStructuredText.
Hallo I’m from an rST file, myst-parser:with a reference about using autodoc.
markup:text style | grouping and alignment | images | tables, code, and math
tools:pandoc
| markdown | restructured text | mediawiki | asciidoc | org-mode | |
|---|---|---|---|---|---|
| sandbox | daringfireball.net/projects/markdown/dingus johnmacfarlane.net/pandoc/try | rst.ninjs.org | en.wikipedia.org/wiki/Wikipedia:Sandbox | asciidoc.wiki.com/wiki/Template:Sandbox | |
| command line tool | $ apt install markdown $ markdown foo.txt > foo.html $ apt install pandoc $ pandoc foo.txt -o foo.html | $ pip install rst2html5 $ rst2html5 foo.rst > foo.html | run at root of MediaWiki source tree: $ php maintenance/parse.php foo.txt > foo.html | $ apt install asciidoc $ asciidoc foo.txt | |
| autolinks url? | no | yes | yes | yes | yes |
| can use html entities? | yes; they are passed to output html | no, the ampersand will be html entity escaped | yes; they are replaced by UTF-8 | yes; they are passed to output html | |
| encoding | markdown and pandoc assume UTF-8 for input and output. | default output is UTF-8; default input is system dependent $ rst2html5 --input-encoding=utf-8 --output-encoding=iso8859-1 < foo.rst > foo.html | MediaWiki specifies UTF-8 in the response header and the HTML document. It handles UTF-8 POST requests, and may handle other encodings correctly. | assumes UTF-8 for input and output | |
| link offsite | [Website](http://website.com) | `Website <http://website.com>`_ | [http://website.com Website] | http://website.com[Website] | [[http://www.google.com][Google]] |
| link with url in footnote | link: [Website][u1] footnote: [u1]: http://website.com | link: Website_ footnote: .. _Website: http://website.com | |||
| link onsite | <a href='page'>Pipe Trick</a> | [[page|Pipe Trick]] | link:page.html[Pipe Trick] | ||
| define anchor | <a name='foo'/> | .. _foo: | Headers automatically get anchors. Also: <div></div> | anchor:foo[] | #+NAME: foo |
| link to anchor | <a href='#foo'>Foo</a> pandoc extension: [Foo](#foo) | Links to '_foo'; 'foo' is used for text: foo_ | [[#foo|Foo]] | <<anchor:foo,Foo>> | [[foo][Foo]] |
| comment | <!-- comment --> | .. comment another comment blank line terminates comment | <!-- comment --> | // comment | whitespace only before number sign: # comment |
| HTML | set off block level html tags with blank lines: <h1>My Header</h1> | |my_header| this must exist elsewhere in document: .. |my_header| raw:: html <h1>foo</h1> | some HTML tags are permitted | ||
| text style | |||||
| markdown | restructured text | mediawiki | asciidoc | org-mode | |
| italic text | *italic text* _italic text_ | *italic text* | two single quotes: 'italic text' | 'italic text' _italic text_ | /italic text/ |
| bold text | **bold text** __bold text__ | **bold text** | three single quotes: ''bold text'' | *bold text* | *bold text* |
| small caps text | <span> small caps text </span> | {{smallcaps|small caps text}} | |||
| fixed width text | `fixed width text` | ``fixed width text`` | <tt>fixed width text</tt> | +fixed width text+ | ~fixed wdith text~ |
| underlined text | <span>underlined text</span> | <u>underlined text</u> | [underline]#underlined text# | _underlined text_ | |
| striketrhough text | <del>strikethough text</del> | <del>strikethough text</del> | +strikethrough text+ | ||
| literal text | *not italics* `*not italics*` | *not italics* | <nowiki>'not italics'</nowiki> | +++_not italics_+++ | |
| superscript2 | superscript<sup>2</sup> | superscript<sup>2</sup> | superscript^2^ | ||
| subscript2 | subscript<sub>2</sub> | subscript<sub>2</sub> | subscript~2~ | ||
| font color | <span>font color</span> | <font color='red'>font color</font> | [red]#font color# | ||
| font size | <font size=16>foo</font> | <font size='16'>foo</font> | |||
| span w/ class | <span> text </span> | .. role:: foo :foo:`text` | <span> text </span> | ||
| grouping and alignment | |||||
| markdown | restructured text | mediawiki | asciidoc | org-mode | |
| line break | space, space, newline | all lines in paragraph with line breaks must start with pipe: | the line breaks | here | <br/> | space, plus, newline + | backslash, backslash, newline i.e putat the end of the line |
| horizontal rule | three or more asterisks, hyphens, or underscores: *** --- ___ | four or more punctuation characters set off by blank lines: ---- | four or more hyphens: ---- | three or more single quotes '' | five or more hyphens on a line by themselves: ----- |
| document title | pandoc extension: % document title | document title | = document title = document title | ||
| document header | % document title % John Doe; Jane Roe % August 16, 2001 | :Date: 2001-08-16 :Version: 1 :Authors: - John Doe - Jane Roe | document title John Doe August 16, 2001 | ||
| section header | pandoc requires blank line before header, markdown doesn't: # section header section header | Other punctuation can be used for title and headers. Whatever punctuation is used must be used consistently in the document. An n+1 level section must be contained in an n level section. section header | =section header= | section header section header -------------- | no indentation before asterisk: * section header |
| subsection header | ## subsection header subsection header ----------------- | subsection header ----------------- | subsection header | subsection header subsection header ~~~~~~~~~~~~~~~~~ | no indentation before asterisk: ** subsection header |
| subsubsection header | ### subsubsection header | subsubsection header ~~~~~~~~~~~~~~~~~~~~ | subsubsection header | subsubsection header subsubsection header ^^^^^^^^^^^^^^^^^^^^ | no indentation before asterisk: *** subusbsection header |
| level 4 header | #### level 4 header | level 4 header `````````````` | level 4 header | ||
| headers automatically anchored? | markdown no, pandoc yes pandoc header identifiers are the same as the header with (1) all punctuation except hyphens, underscores, periods removed, (2) spaces and newlines replaced by hyphens, (3) lowercase, (4) everything before first letter removed | yes | yes | yes, with id attribute on header element | yes, with id attribute on header element example: <h4> |
| list item | pandoc requires sublists be indented 4 spaces: * list item * sublist item plus signs + or hyphens - may be used in place of asterisks | sublist must be set off by a blank line: - list item - sublist item asterisks * or plus signs + may be used in place of hyphens - | * list item ** sublist item | * list item ** sublist item | + list item + sublist item + sublist item Hyphens and asterisks can also be used for bullets. If asterisks are used, they must be indented to distinguish them from section headers. |
| list item with multiple paragraphs | pandoc requires 4 space indent: * 1st list item 2nd paragraph * 2nd list item | * 1st list item<br/><br/>2nd paragraph * 2nd list item | + 1st list item 2nd paragraph + 2nd list item | ||
| numbered list item | markdown ignores actual numeric values; pandoc uses first value only: 1. numbered one 2. numbered two pandoc supports other formats: 1) numbered one 2) numbered two i. roman numeral one ii. roman numeral two | numbers in source are used: 1. numbered one 2. numbered two 1) numbered one 2 ) numbered two i) roman numeral one ii) roma numberal two | # numbered one # numbered two | error if values in markup are not sequential starting from one: 1. numbered one 2. numbered two | |
| definition list | <dl> <dd>one <dt>the 1st cardinal <dd>two <dt>the 2nd cardinal </dl> pandoc extension; 4 spaces after colon: one :the 1st cardinal two :the 2nd cardinal | one the 1st cardinal two the 2nd cardinal | ; one : the 1st cardinal ; two : the 2nd cardinal | one:: the 1st cardinal two:: the 2nd cardinal | |
| block quote | > Four score and twenty > years ago… pandoc also has lazy block quotes: > Four score and twenty years ago… pandoc requires blank line before a block quote | Main body text. Four score and twenty years ago… More main body text. | <blockquote> Four score and twenty years ago… </blockquote> | **** Four score and twenty years ago… **** | #+BEGIN_QUOTE Four score and twenty years ago… #+END_QUOTE |
| div w/ class | <div> markup </div> | <div> markup </div> | |||
| images | |||||
| markdown | restructured text | mediawiki | asciidoc | org-mode | |
| image | <img src='foo.jpg'> | .. image:: foo.jpg | [[File:foo.jpg]] | image:foo.jpg[] | [[foo.jpg]] |
| image link | <a href='http://foo.com'></a> | .. image:: foo.jpg :target: http://foo.com | [[File:foo.jpg|link=http://foo.com]] | image:foo.jpg[link='http://foo.com'] | |
| image with alt |  | .. image:: foo.jpg :alt: Foo | [[File:foo.jpg|alt=Foo]] | image:foo.jpg[Foo] | |
| image size | height can also be specified; height proportionate if not: <img width='300px' src='foo.jpg'> | height can also be specified; height proportionate if not: _ .. image:: foo.jpg :width: 300px | specify width; height will be proportionate: [[File:foo.jpg|300px]] | specify width; height will be proportionate: image:foo.jpg[width='300px'] | |
| tables, code, and math | |||||
| markdown | restructured text | mediawiki | asciidoc | org-mode | |
| table | <table> <tr><th>A<th>B <tr><td>1<td>2 <tr><td>3<td>4 </table> pandoc extensions: AB ---- 12 34 pandoc extension: +---+---+ | A | B | +---+---+ | 1 | 2 | +---+---+ | 3 | 4 | +---+---+ | AB 12 34 +---+---+ | A | B | +++ | 1 | 2 | +---+---+ | 3 | 4 | +---+---+ | {|border='1' !A!!B |- |1||2 |- |3||4 |} one cell per row of markup: {|border='1' !A !B |- |1 |2 |- |3 |4 |} | [width='20%', options='header'] | |A|B |1|2 |3|4 | | |A|B| |-+-| |1|2| |3|4| |
| multiple column cell | <table> <tr><th colspan=2>title <tr><td>1<td>2 </table> | +-------+ | title | +++ | 1 | 2 | +---+---+ | {|border='1' !colspan='2'|title |- |1||2 |} | [width='20%', options='header'] | 2+|title |1|2 | | |
| cell alignment | <table><tr> <td align='left'>left <td align='center'>center <td align='right'>right </tr></table> | {|border='1' |align='left'|left |align='center'|center |align='right'|right |} | |||
| pre-formatted fixed-width block with no need to escape markup or < and & | set off from surrounding blocks with blank lines and indent each line at least 4 spaces: int add(int a, int b) { return (a+b); } pandoc delimited code block uses 3 or more tildes or backticks: ~~~ int add(int a, int b) { return (a+b); } ~~~ | If the preceding paragraph ends with two colons, it renders as a single colon. Two colons on a line by themselves are removed. Preformatted text is indented. :: int add(int a, int b) { return (a+b); } | <pre> int add(int a, int b) { return (a+b); } </pre> | ---- int add(int a, int b) { return (a+b); } ---- | #+BEGIN_EXAMPLE int add(int a, int b) { return (a+b); } #+END_EXAMPLE |
| highlighted code | pandoc extension: ~~~c int add(int a, int b) { return (a+b); } ~~~ | Adds classes, but a style sheet is necessary to get the colors: .. code-block:: c int add(int a, int b) { return (a+b); } | <source lang=c> int add(int a, int b) { return (a+b); } </source> | source-hightlight must be installed: [source,c] ---- int add(int a, int b) { return (a+b); } ---- | |
| languages which can be highlighted | lists the supported languages: $ pandoc --version | $ pygmentize -L lexers | 100+ languages | 150+ languages | |
| latex math | pandoc extension: $ int_0^pi cos (x) dx $ | .. math:: int_0^pi cos (x) dx | <math>int_0^pi cos (x) dx</math> | ||
| ________________ | ______________________________________________ | ___________________________________________ | ___________________________________________ | ___________________________________________ | ___________________________________________ |
Markdown was developed in 2004, initially in Perl. It is used by Tumblr, Stackoverflow, GitHub, and Reddit. Here is a sandbox.
On Ubuntu you can install a script which converts Markdown to HTML with the following command:
The command line script converts Markdown to HTML. Invoke it like this:
Pandoc User's Guide
Pandoc's Markdown
There are installers for Windows and Mac. On Ubuntu Pandoc can be installed with
Pandoc can read Markdown, LaTeX, HTML, and a few other formats. It can output HTML, RTF, MediaWiki Syntax, groff man page format, Emacs Org-Mode, AsciiDoc, EPub, GNU Texinfo, Word docx, Slidy, and some other formats.
Pandoc's version of Markdown has extensions. Using the extensions avoids HTML and makes it easier for Pandoc to target other formats.
Converting Markdown to HTML:
Converting HTML to Markdown:
pdf from markdown
A tool such as pdflatex must be in the search path:
epub from markdown
word document from markdown
man page from markdown
groff_man(7)(ubuntu.com)
The markup used for man pages is described in groff_man(7).
slideshow from markdown
pydoc and rst2html5
MediaWiki powers Wikipedia. The source code is freely available.
Wikipedia was launched in January 2001. The site initially used wiki software implemented in Perl called UseModWiki. In January 2002 the site switched to custom software written in PHP. The PHP code was rewritten for scalability in July 2002. It was given the name MediaWiki in 2003 and was eventually open sourced.
UseModWiki had a spare set of markup which did not expand much on the markup used by Wiki Base, the original wiki software used by WikiWikiWeb.
| Wiki Base (1995) | UseModWiki (1999) | MediaWiki (2002) | Markdown (2004) | |
|---|---|---|---|---|
| link | CamelCase | CamelCase [[Double Bracket]] | [[Double Bracket]] | [Single Bracket](url) |
| italic | 'italic' | 'italic' | 'italic' | *italic* |
| bold | ''bold'' | ''bold'' | ''bold'' | **bold** |
| horizontal rule | ---- | ---- | ---- | --- |
| top level header | none | none | =top level header= | # top level header |
| second level header | none | none | second level header | ## second level header |
| bullet list item | * list item | * list item | * list item | * list item |
| numbered list item | none | # list item | # list item | 1. list item |
| image | can be URL: foo.jpg | can be URL: foo.jpg | [[File:foo.jpg]] MediaWiki permits raw URL images like its predecessors but the feature is turned off on Wikipedia | <img src='foo.jpg'> |
| table | none | added in 2003: ||A||B|| ||1||2|| | {| !A!!B |- |1||2 |} | <table> <tr><td>A<td>B <tr><td>1<td>2 </table> |
Markdown Viewer Online
For those who like to experiment, here are sandboxes for Wiki Base and UseModWiki.
In Wiki Base the way to prevent a camel case word from becoming a link was to insert six single quotes into the word like this: C'''amelCase. The odd markup was not intentional. The six single quotes actually parse as a bold empty string.
UseModWiki had a feature called 'free links' which was attractive to the founders of Wikipedia. It permitted page titles to have spaces, commas, periods, or hyphens in them. These pages could be linked with double brackets: e.g. [[Los Angeles]]. In the URL the spaces are replaced with underscores. UseModWiki is case insensitive but MediaWiki is case sensitive except for the first letter.
AsciiDoc User Guide
HTML Slidy: Slide Shows in HTML and XHTML
AsciiDoc can be installed by a variety of package managers. On Ubuntu:
On a Mac with MacPorts:
AsciiDoc documents have a .txt suffix by default. The following command will create a file called foo.html:
Restructured Text Markdown
slideshow