When I discovered that these platforms can render reStructuredText (rST) in their WebUIs, I was very excited!
However, there are limitations. Here's a summary.
The main reason of my excitement was that the support of both rST and Markdown rendering clearly showed that rST was a more expressive markup language than Markdown, just with one simple—yet really handy—feature: an auto-generated table of contents, which in Markdown takes additional scripting to produce.
As I started using this capability in my professional work, I inevitably stumbled upon various limitations of rendering and formatting in comparison to HTML output of the native Docutils interpreter.
I tried to find a summary of these limitations with no luck. So I decided to provide the summary from my own quill. For comparison, I attach links to the Docutils rST Demo where I can show examples of the originally intended interpretation of some elements.
Note: The order of presentation of the platforms doesn't endorse any preference on my part, I just sort them alphabetically. I think both these platforms are pretty great!
Supported
Good old news, both platforms support most features of explicit markup and the simple directives!
Common limitations
Both GitHub and GitLab limit the following features.
Settings
- Error output (inclusion of the auto-generated Docutils System Messages section).
- File inclusions – this poses security risk and is disabled (probably
file_insertion_enabled=False) – this probably means that even external-inclusion options in directives are disabled for the same reason (for example:fileandurloptions in csv-table directives). The only exception to this rule are image and figure directives.
Explicit markup
- Line blocks preserve line breaks but not indentation (both preserved in Docutils output).
- Grid tables (compare with Docutils' Tables).
Directives
- Include – disabled altogether, doesn't produce any output.
- Caption of contents is not rendered in bold – this can be fixed by adding in-line markup.
- Admonitions – rendered as basic paragraphs without special formatting (compare with Docutils output).
- Topics, Sidebars, and Rubrics – rendered as basic paragraphs without special formatting (compare with Docutils output).
Possibly also other more complex directives aren't rendered with proper formatting.
Limitations specific to GitHub
In addition to the aforementioned common limitations, GitHub limits the following.
In-line
- The default role of interpreted text isn't formatted (emphasized in Docutils in-line markup).
- Literals don't preserve whitespace (preserved in Docutils in-line markup).
Directives
- Raw – only text content is rendered as basic paragraphs, tags are stripped (Has GitHub modified the interpreter somehow? Anyway, tags are preserved in Docutils output).
Limitations specific to GitLab
In addition to the aforementioned common limitations, GitLab limits the following.
Directives
- Raw – no output (probably disabled in the interpreter, i.e.
raw_enabled=False).
Evaluation
This analysis of rendering and formatting limitations is far from exhaustive, but provides a basic idea of the differences between the native Docutils interpreter and the GH/GL rendering.
To summarize: rST rendering on these platforms serves the purpose of a simplified preview and it's okay that, as such, it doesn't provide the full set of rST features and capabilities.
What I personally miss are Admonitions with their emphasized formatting as, without it, they don't fulfill their purpose. Also, I would intuitively format the caption of Contents in strong emphasis by default. On the other hand, the user is free to format the caption as they please by adding in-line markup.
However, I was nicely surprised how beautifully both platforms format Option lists and they definitely deserve praise for it!
And kudos to GitLab for distinguished formatting of csv-table and list-table captions!