==========================================

Nim-flavored Markdown and reStructuredText

:Author: Andrey Makarov :Version: |nimversion|

.. default-role:: code .. include:: rstcommon.rst .. contents::

Both Markdown:idx: (md) and reStructuredText:idx: (RST) are markup languages whose goal is to typeset texts with complex structure, formatting and references using simple plaintext representation.

Command line usage

Usage (to convert Markdown into HTML):

  nim md2html markdown_rst.md

Output:

You're reading it!

The md2tex:option: command is invoked identically to md2html:option:, but outputs a .tex file instead of .html.

These tools embedded into Nim compiler; the compiler can output the result to HTML [#html] or Latex [#latex].

[#html] commands nim doc:cmd: for *.nim files and nim rst2html:cmd: for *.rst files

[#latex] commands nim doc2tex:cmd: for *.nim and nim rst2tex:cmd: for *.rst.

Full list of supported commands:

=================== ====================== ============ ============== command runs on... input format output format =================== ====================== ============ ============== nim md2html:cmd: standalone md files .md .html HTML nim md2tex:cmd: same same .tex LaTeX nim rst2html:cmd: standalone rst files .rst .html HTML nim rst2tex:cmd: same same .tex LaTeX nim doc:cmd: documentation comments .nim .html HTML nim doc2tex:cmd: same same .tex LaTeX nim jsondoc:cmd: same same .json JSON =================== ====================== ============ ==============

Basic markup

If you are new to Markdown/RST please consider reading the following:

1) [Markdown Basic Syntax] 2) a long specification of Markdown: [CommonMark Spec] 3) a short [quick introduction] to RST 4) an [RST reference]: a comprehensive cheatsheet for RST 5) a more formal 50-page [RST specification].

Features

A large subset is implemented with some [limitations] and [additional Nim-specific features].

Supported standard RST features:

body elements
- sections
- transitions
- paragraphs
- bullet lists using +, *, -
- enumerated lists using arabic numerals or alphabet characters: 1. ... 2. ... or a. ... b. ... or A. ... B. ...
- footnotes (including manually numbered, auto-numbered, auto-numbered with label, and auto-symbol footnotes) and citations
- definition lists
- field lists
- option lists
- indented literal blocks
- quoted literal blocks
- line blocks
- simple tables
- directives (see official documentation in [RST directives list]):
- image, figure for including images and videos
- code
- contents (table of contents), container, raw
- include
- admonitions: "attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning", "admonition"
- substitution definitions: replace and image
- comments
inline markup
- emphasis, strong emphasis, inline literals, hyperlink references (including embedded URI), substitution references, standalone hyperlinks, internal links (inline and outline)
- `interpreted text` with roles :literal:, :strong:, emphasis, :sub:/:subscript:, :sup:/:superscript: (see [RST roles list] for description).
- inline internal targets

Additional Nim-specific features

directives: code-block [cmp:Sphinx], title, index [cmp:Sphinx]
predefined roles
- :nim: (default), :c: (C programming language), :python:, :yaml:, :java:, :cpp: (C++), :csharp (C#). That is every language that highlite supports. They turn on appropriate syntax highlighting in inline code.
.. Note:: default role for Nim files is :nim:,
```
      for ``*.rst`` it's currently ``:literal:``.
```
- generic command line highlighting roles:
- :cmd: for commands and common shells syntax
- :console: the same for interactive sessions (commands should be prepended by $)
- :program: for executable names [cmp:Sphinx] (one can just use :cmd: on single word)
- :option: for command line options [cmp:Sphinx]
- :tok:, a role for highlighting of programming language tokens
triple emphasis (bold and italic) using ***
:idx: role for `interpreted text` to include the link to this text into an index (example: [Nim index]).
double slash // in option lists serves as a prefix for any option that starts from a word (without any leading symbols like -, --, /):

//compile compile the project //doc generate documentation

Here the dummy // will disappear, while options compile:option: and doc:option: will be left in the final document.

[cmp:Sphinx] similar but different from the directives of Python [Sphinx directives] and [Sphinx roles] extensions

Extra features

Optional additional features, by default turned on:

emoji / smiley symbols
Markdown tables
Markdown code blocks. For them the same additional arguments as for RST code blocks can be provided (e.g. test or number-lines) but with a one-line syntax like this:

nim test number-lines=10 echo "ok"
Markdown links
Markdown headlines
Markdown block quotes
using 1 as auto-enumerator in enumerated lists like RST # (auto-enumerator 1 can not be used with # in the same list)

.. Note:: By default Nim has roSupportMarkdown and roSupportRawDirective turned on.

.. warning:: Using Nim-specific features can cause other RST implementations to fail on your document.

Idiosyncrasies

Currently we do not aim at 100% Markdown or RST compatibility in inline markup recognition rules because that would provide very little user value. This parser has 2 modes for inline markup:

1) Markdown-like mode which is enabled by roPreferMarkdown option (turned on by default).

.. Note:: RST features like directives are still turned on

2) Compatibility mode which is RST rules.

.. Note:: in both modes the parser interpretes text between single

 backticks (code) identically:
 backslash does not escape; the only exception: ``\`` folowed by `
 does escape so that we can always input a single backtick ` in
 inline code. However that makes impossible to input code with
 ``\`` at the end in *single* backticks, one must use *double*
 backticks:

     `\`   -- WRONG
     ``\`` -- GOOD
     So single backticks can always be input: `\`` will turn to ` code

.. Attention:: We don't support some obviously poor design choices of Markdown (or RST).

no support for the rule of 2 spaces causing a line break in Markdown (use RST "line blocks" syntax for making line breaks)
interpretation of Markdown block quotes is also slightly different, e.g. case
```
 >>> foo
 > bar
 >>baz
```
is a single 3rd-level quote foo bar baz in original Markdown, while in Nim we naturally see it as 3rd-level quote foo + 1st level bar + 2nd level baz:

foo bar baz

Limitations

no Unicode support in character width calculations
body elements
- no roman numerals in enumerated lists
- no doctest blocks
- no grid tables
- some directives are missing (check official [RST directives list]): parsed-literal, sidebar, topic, math, rubric, epigraph, highlights, pull-quote, compound, table, csv-table, list-table, section-numbering, header, footer, meta, class
- no role directives and no custom interpreted text roles
- some standard roles are not supported (check [RST roles list])
- no generic admonition support
inline markup
- no simple-inline-markup
- no embedded aliases

Additional resources

See Nim DocGen Tools Guide for the details about nim doc:cmd: command and idiosyncrasies of documentation markup in .nim files and Nim programming language projects.
See also documentation for rst module -- Nim RST/Markdown parser.

.. _Markdown Basic Syntax: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax .. _CommonMark Spec: https://spec.commonmark.org/0.30 .. _quick introduction: https://docutils.sourceforge.io/docs/user/rst/quickstart.html .. _RST reference: https://docutils.sourceforge.io/docs/user/rst/quickref.html .. _RST specification: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html .. _RST directives list: https://docutils.sourceforge.io/docs/ref/rst/directives.html .. _RST roles list: https://docutils.sourceforge.io/docs/ref/rst/roles.html .. _Nim index: https://nim-lang.org/docs/theindex.html .. _Sphinx directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html .. _Sphinx roles: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html

markdown_rst.md 9.4 KB Historik Rå