levovix
/
Nim
mirror de https://github.com/nim-lang/Nim


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294
							<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--  This file is generated by Nim. -->
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Nim-flavored Markdown and reStructuredText</title>

<!-- Google fonts -->
<link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>

<!-- Favicon -->
<link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">

<!-- CSS -->
<link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">

<!-- JS -->
<script type="text/javascript" src="dochack.js?v=2.3.1"></script>
</head>
<body>
  <div class="document" id="documentId">
    <div class="container">
      <h1 class="title">Nim-flavored Markdown and reStructuredText</h1>
      <div class="row">
  <div class="three columns">
    <div class="theme-select-wrapper">
      <label for="theme-select">Theme:&nbsp;</label>
      <select id="theme-select" onchange="setTheme(this.value)">
        <option value="auto">🌗 Match OS</option>
        <option value="dark">🌑 Dark</option>
        <option value="light">🌕 Light</option>
      </select>
    </div>
    <div id="global-links">
      <ul class="simple-boot">
        <li><a href="manual.html">Manual</a></li>
        <li><a href="lib.html">Standard library</a></li>
        <li> <a id="indexLink" href="theindex.html">Index</a></li>
        <li><a href="compiler/theindex.html">Compiler docs</a></li>
        <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
        <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
      </ul>
    </div>
    <div id="searchInputDiv">
      Search: <input type="search" id="searchInput"
        oninput="search()" />
    </div>
    <div class="search-groupby">
  Group by:
  <select onchange="groupBy(this.value)">
    <option value="section">Section</option>
    <option value="type">Type</option>
  </select>
</div>

    <ul class="simple simple-toc" id="toc-list">
  <li><a class="reference" id="command-line-usage_toc" href="#command-line-usage">Command line usage</a></li>
<li><a class="reference" id="basic-markup_toc" href="#basic-markup">Basic markup</a></li>
<ul class="simple"><li><a class="reference" id="basic-markup-features_toc" href="#basic-markup-features">Features</a></li>
<li><a class="reference" id="basic-markup-rst-mode-only-features_toc" href="#basic-markup-rst-mode-only-features">RST mode only features</a></li>
<li><a class="reference" id="basic-markup-markdownminusspecific-features_toc" href="#basic-markup-markdownminusspecific-features">Markdown-specific features</a></li>
<li><a class="reference" id="basic-markup-additional-nimminusspecific-features_toc" href="#basic-markup-additional-nimminusspecific-features">Additional Nim-specific features</a></li>
</ul><li><a class="reference" id="referencing_toc" href="#referencing">Referencing</a></li>
<ul class="simple"><li><a class="reference" id="referencing-markup-local-referencing_toc" href="#referencing-markup-local-referencing">Markup local referencing</a></li>
<li><a class="reference" id="referencing-markup-external-referencing_toc" href="#referencing-markup-external-referencing">Markup external referencing</a></li>
</ul><li><a class="reference" id="other_toc" href="#other">Other</a></li>
<ul class="simple"><li><a class="reference" id="other-idiosyncrasies_toc" href="#other-idiosyncrasies">Idiosyncrasies</a></li>
<li><a class="reference" id="other-limitations_toc" href="#other-limitations">Limitations</a></li>
<li><a class="reference" id="other-additional-resources_toc" href="#other-additional-resources">Additional resources</a></li>
</ul>
</ul>

  </div>
  <div class="nine columns" id="content">
    <a href="https://github.com/nim-lang/Nim/tree/devel/doc/markdown_rst.md#L1" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
<a href="https://github.com/nim-lang/Nim/edit/devel/doc/markdown_rst.md#L1" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;

    <div id="tocRoot"></div>
    
    <p class="module-desc"><table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Author:</th><td>Andrey Makarov</td></tr>
<tr><th class="docinfo-name">Version:</th><td>2.3.1</td></tr>
</tbody></table><p>Both <span id="markdown_1">Markdown</span> (md) and <span id="restructuredtext_1">reStructuredText</span> (RST) are markup languages whose goal is to typeset texts with complex structure, formatting and references using simple plaintext representation.</p>

<h1><a class="toc-backref" id="command-line-usage" href="#command-line-usage">Command line usage</a></h1><p>Usage (to convert Markdown into HTML):</p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">md2html</span> <span class="Identifier">markdown_rst.md</span></pre></p>
<p>Output:</p>
<pre>You're reading it!</pre>
<p>The <tt class="docutils literal"><span class="pre option">md2tex</span></tt> command is invoked identically to <tt class="docutils literal"><span class="pre option">md2html</span></tt>, but outputs a <tt class="docutils literal"><span class="pre">.tex</span></tt> file instead of <tt class="docutils literal"><span class="pre">.html</span></tt>.</p>
<p>These tools embedded into Nim compiler; the compiler can output the result to HTML <sup><strong><a class="reference internal" href="#footnote-html">[1]</a></strong></sup> or Latex <sup><strong><a class="reference internal" href="#footnote-latex">[2]</a></strong></sup>.</p>
<hr class="footnote"><div class="footnote-group">
<div id="footnote-html"><div class="footnote-label"><sup><strong><a href="#footnote-html">[1]</a></strong></sup></div> &ensp; commands <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc</span></span></tt> for <tt class="docutils literal"><span class="pre">*.nim</span></tt> files and <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">rst2html</span></span></tt> for <tt class="docutils literal"><span class="pre">*.rst</span></tt> files
</div>
<div id="footnote-latex"><div class="footnote-label"><sup><strong><a href="#footnote-latex">[2]</a></strong></sup></div> &ensp; commands <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc2tex</span></span></tt> for <tt class="docutils literal"><span class="pre">*.nim</span></tt> and <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">rst2tex</span></span></tt> for <tt class="docutils literal"><span class="pre">*.rst</span></tt>.
</div>
</div>
<p>Full list of supported commands:</p>
<table border="1" class="docutils"><tr><th>command</th><th>runs on...</th><th>input format</th><th>output format</th></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">md2html</span></span></tt></td><td>standalone md files</td><td><tt class="docutils literal"><span class="pre">.md</span></tt></td><td><tt class="docutils literal"><span class="pre">.html</span></tt> HTML</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">md2tex</span></span></tt></td><td>same</td><td>same</td><td><tt class="docutils literal"><span class="pre">.tex</span></tt> LaTeX</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">rst2html</span></span></tt></td><td>standalone rst files</td><td><tt class="docutils literal"><span class="pre">.rst</span></tt></td><td><tt class="docutils literal"><span class="pre">.html</span></tt> HTML</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">rst2tex</span></span></tt></td><td>same</td><td>same</td><td><tt class="docutils literal"><span class="pre">.tex</span></tt> LaTeX</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc</span></span></tt></td><td>documentation comments</td><td><tt class="docutils literal"><span class="pre">.nim</span></tt></td><td><tt class="docutils literal"><span class="pre">.html</span></tt> HTML</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc2tex</span></span></tt></td><td>same</td><td>same</td><td><tt class="docutils literal"><span class="pre">.tex</span></tt> LaTeX</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">jsondoc</span></span></tt></td><td>same</td><td>same</td><td><tt class="docutils literal"><span class="pre">.json</span></tt> JSON</td></tr>
</table>
<h1><a class="toc-backref" id="basic-markup" href="#basic-markup">Basic markup</a></h1><p>If you are new to Markdown/RST please consider reading the following:</p>
<ol class="simple"><li><a class="reference external" href="https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax">Markdown Basic Syntax</a></li>
<li>a long specification of Markdown: <a class="reference external" href="https://spec.commonmark.org/0.30">CommonMark Spec</a></li>
<li>a short <a class="reference external" href="https://docutils.sourceforge.io/docs/user/rst/quickstart.html">quick introduction</a> to RST</li>
<li>an <a class="reference external" href="https://docutils.sourceforge.io/docs/user/rst/quickref.html">RST reference</a>: a comprehensive cheatsheet for RST</li>
<li>a more formal 50-page <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html">RST specification</a>.</li>
</ol>

<h2><a class="toc-backref" id="basic-markup-features" href="#basic-markup-features">Features</a></h2><p>A large subset is implemented with some <a class="reference internal" href="#other-limitations">limitations</a> and <a class="reference internal" href="#basic-markup-additional-nimminusspecific-features">additional Nim-specific features</a>.</p>
<p>Supported common RST/Markdown features:</p>
<ul class="simple"><li>body elements<ul class="simple"><li>sections</li>
<li>transitions</li>
<li>paragraphs</li>
<li>bullet lists using +, *, -</li>
<li>enumerated lists using arabic numerals or alphabet characters:  1. ... 2. ... <em>or</em> a. ... b. ... <em>or</em> A. ... B. ...</li>
<li>footnotes (including manually numbered, auto-numbered, auto-numbered with label, and auto-symbol footnotes) and citations</li>
<li>field lists</li>
<li>option lists</li>
<li>quoted literal blocks</li>
<li>line blocks</li>
<li>simple tables</li>
<li>directives (see official documentation in <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html">RST directives list</a>):<ul class="simple"><li><tt class="docutils literal"><span class="pre">image</span></tt>, <tt class="docutils literal"><span class="pre">figure</span></tt> for including images and videos</li>
<li><tt class="docutils literal"><span class="pre">code</span></tt></li>
<li><tt class="docutils literal"><span class="pre">contents</span></tt> (table of contents), <tt class="docutils literal"><span class="pre">container</span></tt>, <tt class="docutils literal"><span class="pre">raw</span></tt></li>
<li><tt class="docutils literal"><span class="pre">include</span></tt></li>
<li>admonitions: &quot;attention&quot;, &quot;caution&quot;, &quot;danger&quot;, &quot;error&quot;, &quot;hint&quot;, &quot;important&quot;, &quot;note&quot;, &quot;tip&quot;, &quot;warning&quot;, &quot;admonition&quot;</li>
<li>substitution definitions: <tt class="docutils literal"><span class="pre"><span class="Identifier">replace</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">image</span></span></tt></li>
</ul>
</li>
<li>comments</li>
</ul>
</li>
<li>inline markup<ul class="simple"><li><em>emphasis</em>, <strong>strong emphasis</strong>, <tt class="docutils literal"><span class="pre">inline literals</span></tt>, hyperlink references (including embedded URI), substitution references, standalone hyperlinks, internal links (inline and outline)</li>
<li>`interpreted text` with roles <tt class="docutils literal"><span class="pre">:literal:</span></tt>, <tt class="docutils literal"><span class="pre">:strong:</span></tt>, <tt class="docutils literal"><span class="pre">emphasis</span></tt>, <tt class="docutils literal"><span class="pre">:sub:</span></tt>/<tt class="docutils literal"><span class="pre">:subscript:</span></tt>, <tt class="docutils literal"><span class="pre">:sup:</span></tt>/<tt class="docutils literal"><span class="pre">:superscript:</span></tt> (see <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/roles.html">RST roles list</a> for description).</li>
<li>inline internal targets</li>
</ul>
</li>
</ul>

<h2><a class="toc-backref" id="basic-markup-rst-mode-only-features" href="#basic-markup-rst-mode-only-features">RST mode only features</a></h2><ul class="simple"><li>RST syntax for definition lists (that is additional indentation after a definition line)</li>
<li>indented literal blocks starting from <tt class="docutils literal"><span class="pre">::</span></tt></li>
</ul>

<h2><a class="toc-backref" id="basic-markup-markdownminusspecific-features" href="#basic-markup-markdownminusspecific-features">Markdown-specific features</a></h2><ul class="simple"><li>Markdown tables</li>
<li>Markdown code blocks. For them the same additional arguments as for RST code blocks can be provided (e.g. <tt class="docutils literal"><span class="pre"><span class="Identifier">test</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">number</span><span class="Operator">-</span><span class="Identifier">lines</span></span></tt>) but with a one-line syntax like this:<pre>```nim test number-lines=10
echo &quot;ok&quot;
```</pre>
</li>
<li>Markdown links <tt class="docutils literal"><span class="pre">[...](...)</span></tt></li>
<li>Pandoc syntax for automatic links <tt class="docutils literal"><span class="pre">[...]</span></tt>, see <a class="reference internal" href="#referencing">Referencing</a> for description</li>
<li>Pandoc syntax for footnotes, including <tt class="docutils literal"><span class="pre">[^10]</span></tt> (manually numbered) and <tt class="docutils literal"><span class="pre">[^someName]</span></tt> (auto-numbered with a label)</li>
<li>Markdown literal blocks indented by 4 or more spaces</li>
<li>Markdown headlines</li>
<li>Markdown block quotes</li>
<li>Markdown syntax for definition lists</li>
<li>using <tt class="docutils literal"><span class="pre">1</span></tt> as auto-enumerator in enumerated lists like RST <tt class="docutils literal"><span class="pre">#</span></tt> (auto-enumerator <tt class="docutils literal"><span class="pre">1</span></tt> can not be used with <tt class="docutils literal"><span class="pre">#</span></tt> in the same list)</li>
</ul>

<h2><a class="toc-backref" id="basic-markup-additional-nimminusspecific-features" href="#basic-markup-additional-nimminusspecific-features">Additional Nim-specific features</a></h2><ul class="simple"><li>referencing to definitions in external files, see <a class="reference internal" href="#referencing-markup-external-referencing">Markup external referencing</a> section</li>
<li>directives: <tt class="docutils literal"><span class="pre">code-block</span></tt> <sup><strong><a class="reference internal" href="#footnote-sphinx">[3]</a></strong></sup>, <tt class="docutils literal"><span class="pre">title</span></tt>, <tt class="docutils literal"><span class="pre">index</span></tt> <sup><strong><a class="reference internal" href="#footnote-sphinx">[3]</a></strong></sup></li>
<li>predefined roles<ul class="simple"><li><tt class="docutils literal"><span class="pre">:nim:</span></tt> (default), <tt class="docutils literal"><span class="pre">:c:</span></tt> (C programming language), <tt class="docutils literal"><span class="pre">:python:</span></tt>, <tt class="docutils literal"><span class="pre">:yaml:</span></tt>, <tt class="docutils literal"><span class="pre">:java:</span></tt>, <tt class="docutils literal"><span class="pre">:cpp:</span></tt> (C++), <tt class="docutils literal"><span class="pre">:csharp</span></tt> (C#). That is every language that <a class="reference external" href="highlite.html">highlite</a> supports. They turn on appropriate syntax highlighting in inline code.<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
default role for Nim files is <tt class="docutils literal"><span class="pre">:nim:</span></tt>, for <tt class="docutils literal"><span class="pre">*.rst</span></tt> it's currently <tt class="docutils literal"><span class="pre">:literal:</span></tt>.</div>
</li>
<li>generic command line highlighting roles:<ul class="simple"><li><tt class="docutils literal"><span class="pre">:cmd:</span></tt> for commands and common shells syntax</li>
<li><tt class="docutils literal"><span class="pre">:console:</span></tt> the same  for interactive sessions (commands should be prepended by <tt class="docutils literal"><span class="pre">$</span></tt>)</li>
<li><tt class="docutils literal"><span class="pre">:program:</span></tt> for executable names <sup><strong><a class="reference internal" href="#footnote-sphinx">[3]</a></strong></sup> (one can just use <tt class="docutils literal"><span class="pre">:cmd:</span></tt> on single word)</li>
<li><tt class="docutils literal"><span class="pre">:option:</span></tt> for command line options <sup><strong><a class="reference internal" href="#footnote-sphinx">[3]</a></strong></sup></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">:tok:</span></tt>, a role for highlighting of programming language tokens</li>
</ul>
</li>
<li><strong><em>triple emphasis</em></strong> (bold and italic) using ***</li>
<li><tt class="docutils literal"><span class="pre">:idx:</span></tt> role for `interpreted text` to include the link to this text into an index (example: <a class="reference external" href="https://nim-lang.org/docs/theindex.html">Nim index</a>).</li>
<li>double slash <tt class="docutils literal"><span class="pre"><span class="Operator">//</span></span></tt> in option lists serves as a prefix for any option that starts from a word (without any leading symbols like <tt class="docutils literal"><span class="pre"><span class="Operator">-</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">--</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">/</span></span></tt>):<pre>//compile   compile the project
//doc       generate documentation</pre>
<p>Here the dummy <tt class="docutils literal"><span class="pre"><span class="Operator">//</span></span></tt> will disappear, while options <tt class="docutils literal"><span class="pre option">compile</span></tt> and <tt class="docutils literal"><span class="pre option">doc</span></tt> will be left in the final document.</p>
</li>
<li>emoji / smiley symbols</li>
</ul>
<hr class="footnote"><div class="footnote-group">
<div id="footnote-sphinx"><div class="footnote-label"><sup><strong><a href="#footnote-sphinx">[3]</a></strong></sup></div> &ensp; similar but different from the directives of Python <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html">Sphinx directives</a> and <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html">Sphinx roles</a> extensions
</div>
</div>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
By default Nim has <tt class="docutils literal"><span class="pre">roSupportMarkdown</span></tt> and <tt class="docutils literal"><span class="pre">roSupportRawDirective</span></tt> turned <strong>on</strong>.</div>
<div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Warning:</b></span>
Using Nim-specific features can cause other Markdown and RST implementations to fail on your document.</div>

<h1><a class="toc-backref" id="referencing" href="#referencing">Referencing</a></h1><p>To be able to copy and share links Nim generates anchors for all main document elements:</p>
<ul class="simple"><li>headlines (including document title)</li>
<li>footnotes</li>
<li>explicitly set anchors: RST internal cross-references and inline internal targets</li>
<li>Nim symbols (external referencing), see <a class="reference external" href="./docgen.html">Nim DocGen Tools Guide</a> for details.</li>
</ul>
<p>But direct use of those anchors have 2 problems:</p>
<ol class="simple"><li>the anchors are usually mangled (e.g. spaces substituted to minus signs, etc).</li>
<li>manual usage of anchors is not checked, so it's easy to get broken links inside your project if e.g. spelling has changed for a heading or you use a wrong relative path to your document.</li>
</ol>
<p>That's why Nim implementation has syntax for using <em>original</em> labels for referencing. Such referencing can be either local/internal or external:</p>
<ul class="simple"><li>Local referencing (inside any given file) is defined by RST standard or Pandoc Markdown User guide.</li>
<li>External (cross-document) referencing is a Nim-specific feature, though it's not really different from local referencing by its syntax.</li>
</ul>

<h2><a class="toc-backref" id="referencing-markup-local-referencing" href="#referencing-markup-local-referencing">Markup local referencing</a></h2><p>There are 2 syntax option available for referencing to objects inside any given file, e.g. for headlines:</p>
<pre>Markdown                  RST

Some headline             Some headline
=============             =============

Ref. [Some headline]      Ref. `Some headline`_</pre>

<h2><a class="toc-backref" id="referencing-markup-external-referencing" href="#referencing-markup-external-referencing">Markup external referencing</a></h2><p>The syntax is the same as for local referencing, but the anchors are saved in <tt class="docutils literal"><span class="pre">.idx</span></tt> files, so one needs to generate them beforehand, and they should be loaded by an <tt class="docutils literal"><span class="pre"><span class="Operator">..</span> <span class="Identifier">importdoc</span><span class="Punctuation">:</span><span class="Punctuation">:</span></span></tt> directive. E.g. if we want to reference section &quot;Some headline&quot; in <tt class="docutils literal"><span class="pre">file1.md</span></tt> from <tt class="docutils literal"><span class="pre">file2.md</span></tt>, then <tt class="docutils literal"><span class="pre">file2.md</span></tt> may look like:</p>
<p><pre class="listing">.. importdoc:: file1.md

Ref. [Some headline]</pre></p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">md2html</span> <span class="option">--index:only</span> <span class="Identifier">file1.md</span>  <span class="Comment"># creates ``htmldocs/file1.idx``</span>
<span class="program">nim</span> <span class="option">md2html</span> <span class="Identifier">file2.md</span>               <span class="Comment"># creates ``htmldocs/file2.html``</span></pre></p>
<p>To allow cross-references between any files in any order (especially, if circular references are present), it's strongly recommended to make a run for creating all the indexes first:</p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">md2html</span> <span class="option">--index:only</span> <span class="Identifier">file1.md</span>  <span class="Comment"># creates ``htmldocs/file1.idx``</span>
<span class="program">nim</span> <span class="option">md2html</span> <span class="option">--index:only</span> <span class="Identifier">file2.md</span>  <span class="Comment"># creates ``htmldocs/file2.idx``</span>
<span class="program">nim</span> <span class="option">md2html</span> <span class="Identifier">file1.md</span>               <span class="Comment"># creates ``htmldocs/file1.html``</span>
<span class="program">nim</span> <span class="option">md2html</span> <span class="Identifier">file2.md</span>               <span class="Comment"># creates ``htmldocs/file2.html``</span></pre></p>
<p>and then one can freely reference any objects as if these 2 documents are actually 1 file.</p>

<h1><a class="toc-backref" id="other" href="#other">Other</a></h1>
<h2><a class="toc-backref" id="other-idiosyncrasies" href="#other-idiosyncrasies">Idiosyncrasies</a></h2><p>Currently we do <strong>not</strong> 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:</p>
<ol class="simple"><li>Markdown-like mode which is enabled by <tt class="docutils literal"><span class="pre"><span class="Identifier">roPreferMarkdown</span></span></tt> option (turned <strong>on</strong> by default).<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
RST features like directives are still turned <strong>on</strong></div>
</li>
<li>Compatibility mode which is RST rules.</li>
</ol>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
in both modes the parser interpretes text between single backticks (code) identically: backslash does not escape; the only exception: <tt class="docutils literal"><span class="pre">\</span></tt> folowed by ` does escape so that we can always input a single backtick ` in inline code. However that makes impossible to input code with <tt class="docutils literal"><span class="pre">\</span></tt> at the end in <em>single</em> backticks, one must use <em>double</em> backticks:<pre>`\`   -- WRONG
``\`` -- GOOD
So single backticks can always be input: `\`` will turn to ` code</pre>
</div>
<div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Attention:</b></span>
We don't support some obviously poor design choices of Markdown (or RST).<ul class="simple"><li>no support for the rule of 2 spaces causing a line break in Markdown (use RST &quot;line blocks&quot; syntax for making line breaks)</li>
<li>interpretation of Markdown block quotes is also slightly different, e.g. case<pre>&gt;&gt;&gt; foo
&gt; bar
&gt;&gt;baz</pre>
<p>is a single 3rd-level quote <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span> <span class="Identifier">bar</span> <span class="Identifier">baz</span></span></tt> in original Markdown, while in Nim we naturally see it as 3rd-level quote <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt> + 1st level <tt class="docutils literal"><span class="pre"><span class="Identifier">bar</span></span></tt> + 2nd level <tt class="docutils literal"><span class="pre"><span class="Identifier">baz</span></span></tt>:</p>
<blockquote class="markdown-quote"><blockquote class="markdown-quote"><blockquote class="markdown-quote"><p>foo</p></blockquote></blockquote><p>bar</p><blockquote class="markdown-quote"><p>baz</p></blockquote></blockquote>
</li>
</ul>
</div>

<h2><a class="toc-backref" id="other-limitations" href="#other-limitations">Limitations</a></h2><ul class="simple"><li>no Unicode support in character width calculations</li>
<li>body elements<ul class="simple"><li>no roman numerals in enumerated lists</li>
<li>no doctest blocks</li>
<li>no grid tables</li>
<li>some directives are missing (check official <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html">RST directives list</a>): <tt class="docutils literal"><span class="pre">parsed-literal</span></tt>, <tt class="docutils literal"><span class="pre">sidebar</span></tt>, <tt class="docutils literal"><span class="pre">topic</span></tt>, <tt class="docutils literal"><span class="pre">math</span></tt>, <tt class="docutils literal"><span class="pre">rubric</span></tt>, <tt class="docutils literal"><span class="pre">epigraph</span></tt>, <tt class="docutils literal"><span class="pre">highlights</span></tt>, <tt class="docutils literal"><span class="pre">pull-quote</span></tt>, <tt class="docutils literal"><span class="pre">compound</span></tt>, <tt class="docutils literal"><span class="pre">table</span></tt>, <tt class="docutils literal"><span class="pre">csv-table</span></tt>, <tt class="docutils literal"><span class="pre">list-table</span></tt>, <tt class="docutils literal"><span class="pre">section-numbering</span></tt>, <tt class="docutils literal"><span class="pre">header</span></tt>, <tt class="docutils literal"><span class="pre">footer</span></tt>, <tt class="docutils literal"><span class="pre">meta</span></tt>, <tt class="docutils literal"><span class="pre">class</span></tt><ul class="simple"><li>no <tt class="docutils literal"><span class="pre">role</span></tt> directives and no custom interpreted text roles</li>
<li>some standard roles are not supported (check <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/roles.html">RST roles list</a>)</li>
<li>no generic admonition support</li>
</ul>
</li>
</ul>
</li>
<li>inline markup<ul class="simple"><li>no simple-inline-markup</li>
<li>no embedded aliases</li>
</ul>
</li>
</ul>

<h2><a class="toc-backref" id="other-additional-resources" href="#other-additional-resources">Additional resources</a></h2><ul class="simple"><li>See <a class="reference external" href="docgen.html">Nim DocGen Tools Guide</a> for the details about <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc</span></span></tt> command and idiosyncrasies of documentation markup in <tt class="docutils literal"><span class="pre">.nim</span></tt> files and Nim programming language projects.</li>
<li>See also documentation for <a class="reference external" href="rst.html">rst module</a> -- Nim RST/Markdown parser.</li>
</ul>
</p>
    
  </div>
</div>

      <div class="twelve-columns footer">
        <span class="nim-sprite"></span>
        <br>
        <small style="color: var(--hint);">Made with Nim. Generated: 2025-02-06 22:27:31 UTC</small>
      </div>
    </div>
  </div>
      <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    
</body>
</html>