1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
================
Built-in markups
================
These markups are available by default:
Markdown markup
===============
Markdown_ markup uses Python-Markdown_ as a backend (version 2.6 or later
is required).
There are several ways to enable `Python-Markdown extensions`_.
* List extensions in a file named :file:`markdown-extensions.yaml` or
:file:`markdown-extensions.txt` in the :ref:`configuration directory
<configuration-directory>`. The extensions will be automatically applied
to all documents.
* If :file:`markdown-extensions.yaml` or :file:`markdown-extensions.txt`
is placed into working directory, all documents in that directory will
get extensions that are listed in that file.
* If first line of a document contains ":samp:`Required extensions:
{ext1 ext2 ...}`", that list will be applied to a document.
* Finally, one can programmatically pass list of extension names to
:class:`markups.MarkdownMarkup` constructor.
The YAML file should be a list of extensions, possibly with configuration
options, for example:
.. code-block:: yaml
- smarty:
substitutions:
left-single-quote: "‚"
right-single-quote: "‘"
smart_dashes: False
- toc:
permalink: True
separator: "_"
toc_depth: 3
- sane_lists
Or using a JSON-like syntax:
.. code-block:: yaml
["smarty", "sane_lists"]
YAML support works only when the PyYAML_ module is installed.
The txt file is a simple list of extensions, separated by newlines. Lines
starting with ``#`` are treated as comments and ignored. It is possible to
specify string options in brackets, for example::
toc(title=Contents)
sane_lists
The same syntax to specify options works in the ``Required extensions``
line. You can put it into a comment to make it invisible in the output::
<!-- Required extensions: toc(title=Contents) sane_lists -->
The `Math Markdown extension`_ is enabled by default. This extension
supports a syntax for LaTeX-style math formulas (powered by MathJax_).
The delimiters are:
================ ===============
Inline math Standalone math
================ ===============
``$...$`` [#f1]_ ``$$...$$``
``\(...\)`` ``\[...\]``
================ ===============
.. [#f1] To enable single-dollar-sign delimiter, one should add
``mdx_math(enable_dollar_delimiter=1)`` to the extensions list.
The `Python-Markdown Extra`_ set of extensions is enabled by default.
To disable it, one can enable virtual ``remove_extra`` extension
(which also completely disables LaTeX formulas support).
The default file extension associated with Markdown markup is ``.mkd``,
though many other extensions (including ``.md`` and ``.markdown``) are
supported as well.
.. _Markdown: https://daringfireball.net/projects/markdown/
.. _Python-Markdown: https://python-markdown.github.io/
.. _MathJax: https://www.mathjax.org/
.. _`Python-Markdown extensions`: https://python-markdown.github.io/extensions/
.. _PyYAML: https://pypi.org/project/PyYAML/
.. _`Math Markdown extension`: https://github.com/mitya57/python-markdown-math
.. _`Python-Markdown Extra`: https://python-markdown.github.io/extensions/extra/
.. autoclass:: markups.MarkdownMarkup
reStructuredText markup
========================
This markup provides support for reStructuredText_ language (the language
this documentation is written in). It uses Docutils_ Python module.
The file extension associated with reStructuredText markup is ``.rst``.
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Docutils: https://docutils.sourceforge.io/
.. autoclass:: markups.ReStructuredTextMarkup
Textile markup
==============
This markup provides support for Textile_ language. It uses python-textile_
module.
The file extension associated with Textile markup is ``.textile``.
.. _Textile: https://textile-lang.com
.. _python-textile: https://github.com/textile/python-textile
.. autoclass:: markups.TextileMarkup
AsciiDoc markup
===============
This markup provides support for AsciiDoc_ language. It uses asciidoc-py_
module.
The file extension associated with AsciiDoc markup is ``.adoc``.
.. _AsciiDoc: https://asciidoc.org
.. _asciidoc-py: https://asciidoc-py.github.io
.. autoclass:: markups.AsciiDocMarkup
|
