Markup Mapping
This page describes the mapping from tbwiki markup language to reStructuredText for the conversion of documentation to Sphynx and readthedocs. (see Issue_0046)
references [edit section]
- TBWIKI:
- ReStructuredText:
mapping [edit section]
headers [edit section]
item | tbwiki | reStructuredText
____________________|_____________________|____________________
| |
| | ##########
Page Title | | Title
| | ##########
____________________|_____________________|____________________
| | =========
1st level heading | = Heading 1 = | Heading 1
| | =========
____________________|_____________________|____________________
| |
2nd level heading | == heading 2 == | Heading 2
| | =========
____________________|_____________________|____________________
| |
3rd level heading | === Heading 3 === | Heading 3
| | ---------
____________________|_____________________|____________________
| |
4th level heading | ==== Heading 4 ==== | Heading 4
| | ~~~~~~~~~
____________________|_____________________|____________________
| |
In rst, Heading order must be consistent, and you can't skip headings. For example, you can't do H1 followed by H3. You must be consistent with the heading underline styles. Sphinx autodetects the level associated with the headings styles, so if you skip a style or use it differently it will cause errors.
inline markup [edit section]
item | tbwiki | reStructuredText
_________________|___________________|____________________
| |
bold | '''bold''' | **bold**
| |
italic | ''italic'' | *italic*
| |
external link | http://foo | http://foo
| |
heading anchor | (automatic) | .. _name:
| | (automatic with sphinx.ext.autosectionlabel configured)
| |
| |
explicit anchor | {{HTML(<a name="#<name></a>)}} | .._name:
| |
| |
| |
page link | [[Page Name]] | :doc:`page_name`
| |
| |
| |
bullet | * item | * item
| (first level must | (first level must follow an empty line)
| be indented) |
| |
dir or filename | ``filename`` | ``filename``
| |
command | 'command' | ``command``
|(no markup, but |
| convention was |
| single quotes) |
other items (definition lists, comments) [edit section]
item | tbwiki | reStructuredText
_________________|____________________|____________________
| |
definition | ; term: definition | term
| | definition description
| |
| | use same indent to continue
_________________|____________________|____________________
| |
| |
comment | {{{# comment here | .. comment here
| }}} |
| |
| |
blocks and quoted [edit section]
item | tbwiki | reStructuredText
_____________|________________________________|____________________
| |
block | {{{ | previous paragraph
| indented | indented
| content | content
| }}} | previous indentation level
_____________|________________________________|____________________
| |
| | .. note:: content in
colored | {{{#!YellowBox | note block
block | content | .. tip:: content in
| }}} | note block (also warning:, error: important: caution:)
| |
| | last part of preceding paragraph ::
| |
| | stuff in block
_____________|________________________________|____________________
| |
labeled | |
offset block | (not available) | .. note:: content in note block
_____________|________________________________|____________________
| |
links [edit section]
note labels and anchors are case-insensitive in rst.By convention, explicit declarations of labels are lower case.
item | tbwiki | reStructuredText
_____________|________________________________|____________________
| |
URL | http://example.com/ | http://example.com/
_____________|________________________________|____________________
| |
URL with | [[http://example.com|Example]] | `Example http://example.com/`_
cover text | |
_____________|________________________________|____________________
| |
internal | [[#Section Name]] | `section_name`_
_____________|________________________________|____________________
| |
page | [[Page Name]] | :doc:`Page Name`
| | (depends on whether first
| | section heading matches
| | page name)
| |
| | :ref:`Page Name <page_nm>`
| | (when a separate anchor has
| | been created for a page,)
| |
_____________|________________________________|____________________
| |
page with | [[Page Name|Cover text]] | :doc:`Cover Text <page name>`
cover text | |
_____________|________________________________|____________________
| |
define |{{HTML(<a name="new_lbl"></a>)}}| .. _new_label:
anchor | |
_____________|________________________________|____________________
| |
define | (not available) | `Example`_
URL separate | | ...
from cover | |
text | | .. _Example: http://example.com/
| |
_____________|________________________________|____________________
| |
See https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref for recommendations on using :ref: It's still a bit unclear to me how to force it to a specific cover text. It appears that it uses a section name following the anchor definition as the cover text, unless overridden. The purpose of this appears to be to let the :ref: handle section renames, without the user having to go to all references and fix them up.
Macros and directives [edit section]
item | tbwiki | reStructuredText
_____________|________________________________|____________________
| |
include | {{Include(page-or-ref)}} | .. include: included-file.txt
_____________|________________________________|____________________
| |