Analysis of rendering on docs.typo3.org

I checked the rendering locally. Unfortunately my initial optimism was premature. Sorry about that. The rendering does not look good in some cases, specifically, in the tables with inline, code, e.g.

on Gitlab

Rendered locally

What is happening: the rendering with Docker does not directly render the Markdown, it converts the Markdown to .rst and then renders that. This does not get optimal results in all cases.

That is why .rst is also recommended to use .rst for rendering with the official docs Docker image for docs.typo3.org: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/GeneralConventions/Format.html

Also, there are warnings. To interpret the warnings, one must look, not in the markdown source, but in the generated .rst. (This would also make the workflow in the future tedious, I would not recommend that.)

cat Documentation-GENERATED-temp/Result/project/0.0.0/_buildinfo/warnings.txt
./Documentation/README.rst:37: WARNING: Field list ends without a blank line; unexpected unindent.
./Documentation/README.rst:201: WARNING: Inline interpreted text or phrase reference start-string without end-string.
./Documentation/README.rst:211: WARNING: Inline interpreted text or phrase reference start-string without end-string.
./Documentation/README.rst:251: WARNING: Definition list ends without a blank line; unexpected unindent.
./Documentation/README.rst:249: WARNING: Inline literal start-string without end-string.
./Documentation/README.rst:249: WARNING: Inline literal start-string without end-string.

$ cat -n Documentation-GENERATED-temp/Result/project/0.0.0/_sources/README.rst.txt | less

So, to sum it up, I would either convert to .rst or just render here (which also looks nice). I had just thought it might be good to render on docs.typo3.org to give the extension more visibility.

---

If you do get it rendered nicely locally, either by changing the formatting or converting to .rst (converting to .rst would propably be preferred for less hassle). These would be the steps:

• Add Documentation/Settings.cfg to show title in rendered project: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/GeneralConventions/DirectoryFilenames.html#settings-cfg
• Render locally to check rendering with Docker container: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/RenderingDocs/Index.html
• Add Documentation-GENERATED-temp to .gitignore (this should be done in local git configuration but putting this in the project avoids hassle later by accidentally committing the generated documenation
• When ready, add Webhook for rendering: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocForExtension/Migrate.html