Moved from Forge: Use Markdown and Gitbook instead of rst and Sphinx

[sypets]

Original issue #72729 by "Ingo Pfennigsdorf":https://forge.typo3.org/users/888

quote (Ingo Pfennigsdorf):

---

"As reStructured Text is quite uncommon to most people and markdown is a de-facto standard in this area, I suggest using markdown as documentation language.

Using sphinx also creates quite an overhead and needs to be installed locally in order to compile and view documentation. A great service taking care of this problem is https://www.gitbook.com where anyone can write documentation in markdown and add collaborators to a project.

This would rather simplify the process of writing documentation."

---

[sypets]

quote (Ingo Pfennigsdorf):

---

A tools for an automatic conversion of already existing documentations is pandoc (http://pandoc.org/)

Issues may be interlinking between manuals, but there may be ways to solve this. I guess some manual steps may be required to get everything to work, but it may be worth it. because of a much simpler way of writing manuals, that brings back the joy to writing documentation!

---

[sypets]

I agree partly. Using reST & Sphinx is not as simple to learn as we might like, Markdown is more common, there is definitely a trend to use simpler, easier to use tools in general (not just documentation), even using the current Docker image to render does require some getting used to (while there are WYSIWYG editors for Markdown available) and not everyone has Docker, there is no WYSIWYG editor or even automatic rendering while editing, GitHub preview will not work correctly for the Sphinx markup, etc..

I am very much in favor of simplifying the workflow as much as possible (as well as I would like to see TYPO3 simplified).

However, this is a really major change. And I don't know if it will be so simple.

Some remarks:

• "Using sphinx also creates quite an overhead and needs to be installed locally in order to compile and view documentation." That is no longer true. We now have the Docker image. (But of course now you have to install Docker locally, so that is still a burden for some, unfortunately). See https://github.com/t3docs/docker-render-documentation
• GitBook costs money: https://www.gitbook.com
• I am not sure of the implications. In my experience, just automatically converting stuff does not do it. It is a help, but must be edited manually. Additionally, I don't know if all features would be available, e.g. embedding YouTube images, syntax highlighting, intersphinx linking etc.

But I agree, the general idea deserves some looking into.

[sypets]

I really like this demo (online demo of WYSIWYG markdown editor): https://typora.io/ Never used the tool myself, though.

[sypets]

This suggest a change of the tools We had a number of discussion about Mardown vs reStructuredText. This is currently not helpful. The issue was migrated from forge a while ago.

Closing this now.