Repository: three.js
Issue: Manual: Conversion from custom HTML generated pages to regular Markdown generated pages.
Labels: Manual

### Description

Today the documentation is generated from custom tags in HTML, and makes it difficult to contribute to it (lot of friction). The documentation is already a topic that is a pain for most of the devs. It is often the neglected part, I think it would benefit to reduce the friction by returning to industry standards and common tooling.

Usage of markdown would benefit by being able to generate documentation with whatever we want, (like docusaurus, ...)

We would access to many new automatic features like table of contents, "Edit this page" type of buttons to be able to encourage the contribution. 
We could go further by supporting MDX in the future, to help craft wonderful documentation. It would be opening doors to new tools from there. 

The discussion is not clear in my head if we should go on a different repository for the documentation, or keep it with the main repository. 

Three.js is very popular among the 3D developers versus the rest of the frameworks like Babylon and stuffs. But the documentation does not live up to the popularity of our beloved lib, in my opinion.
If we take react-three-fiber, it takes advantages of the three.js documentation, by referencing it. So there is a whole ecosystem that would really benefit from a clearer, cleaner, modern documentation.


Also, I would take advantage of this modernisation to describe the documentation using Typescript convention of typing. This would enable syntax highlighting based on that for free, even if the underlying implementation is javascript. We would just use the ts code fences available with markdown.

### Solution

I began to work on a python script to convert our custom HTML to markdown files and took docusaurus as a test bed for this documentation. 

I used a separate repository to do so, just as a proof of concept. 
I added the typescript code fences from markdown to explicit the typing on the method and properties of each pages.

You can see a demo here : https://threejs-docs-markdown.vercel.app/docs/en/animation/AnimationAction
Link to the codebase : https://github.com/AxiomeCG/threejs-docs-reloaded


Basically the script is parsing the HTML and producing a markdown file from it. It converts most of the custom elements like [property: ...], [method: ...] and `<code>` tags.

The structure we know for the folders would be the same. 

The script is working by giving a folder in input and it produces an equivalent output by preserving the folder hierarchy and outputting the markdown equivalent files. I need to test on internalization files from other folders different from the `en` one. But as soon as it respects the same linking and convention on the custom elements (which I assumed true due to the automatic generation of the actual docs), I think it would not be troublesome. 

### Alternatives

We should examine the best alternative to a markdown system. Do we want to keep on going with this adhoc system or get back on an industry standard ?

### Additional context

There is some of the things that are known broken like linking in the current script. I just submit the first beta result as a proof of concept to see if it is validated to be continued, and not wasting time on a tool that would not be well received ! :)