-
Are there any plans of supporting reStructuredText instead of Markdown as the input format? Currently Quarto seems to support ReST as an output format only. However, ‘knitr’ actually has (rudimentary) support for ReST input. The tangible benefit of ReST is that the Markdown format trades power for simplicity and as a consequence is severely limited. For many documents this is obviously fine (though it did contribute to the proliferation of incompatible, competing Markdown flavours). But for more sophisticated documents it’s insufficient. As a motivating example, consider writing documentation. In R the weapon of choice for this is ‘roxygen2’. However, this is only available for code. Often, technical documentation goes beyond code, and ‘roxygen2’ becomes unsuitable. Alternatively documentation systems such as Sphinx use ReST as their underlying format, and Markdown wouldn’t work. Consider e.g. the following code snippet, which can’t really be expressed in Markdown at all, due to the lack of support for custom markup: Some example text.
.. note:: For use with |TLA| only
.. warning::
This :class:`Gadget` needs to be used with care. The direct equivalent of the above in Markdown would require using inline HTML or LaTeX (making it non-portable), and would require repeating (potentially verbose) markup at every use, instead of cleanly separating content and presentation, which is best practice across a wide variety of content editing systems (including HTML/CSS, LaTeX, MS Word … and, indeed, Markdown, albeit only for a fixed set of predefined types of markup). |
Beta Was this translation helpful? Give feedback.
Replies: 1 comment 1 reply
-
I think if you dig a little deeper you'll find that pandoc markdown + quarto gives you the same level of expressiveness and computability. The above would be written as: Some example text.
::: {.callout-note}
For use with {{< var TLA >}} only
:::
::: {.callout-warning}
This [Gadget]{.gadget} needs to be used with care.
::: I agree that ReST has an outstanding feature set for technical writing. The problem is that 97% of the user base is already familiar with markdown. When JupyterBook was created they wanted to build on the ReST/Sphinx infrastructure but created a new dialect of markdown (that effectively emits the ReST AST) instead: https://myst-parser.readthedocs.io/en/latest/. Trying to convince hordes of people to switch from markdown was viewed as too tall a task. |
Beta Was this translation helpful? Give feedback.
I think if you dig a little deeper you'll find that pandoc markdown + quarto gives you the same level of expressiveness and computability. The above would be written as:
I agree that ReST has an outstanding feature set for technical writing. The problem is that 97% of the user base is already familiar with markdown. When JupyterBook was created they wanted to build on the ReST/Sphinx infrastructure but created a new dialect of markdown (that effectively emits the ReST AST) instead: https://myst-parser.readthedocs.io/en/latest/. Trying…