Open unixfox opened 3 years ago
MkDocs
If we decide to use Mkdocs, it looks like the mkdocs-material
theme is the standard for the Crystal ecosystem.
I'm posting here the message I wrote on matrix. The idea is to switch out from Markdown, because it's hardly standard an not suited for proper documentation. In all the options we have (RST, Dita, Docbook, AsciiDoc, (La)Tex), RST is the easiest to use and the most flexible.
roadmap for the docs, if you want to do it in a way that will be maintainable in the future, and flexible enough to be integrated into the website:
1) move the instance list to the instances-api repo & make it a YAML list, so we can easily parse it and render it to anything (and also we won't have to maintain the static HTML list anymore in that repo)
2) restructure the docs (folder structure) and convert it to RST at the same time
3) configure sphinx, select/make a simple theme for the docs
4) make the CI pipeline for auto build/deploy of docs
5) update docs (rewrite most of it)
6) add project to weblate, so we can have the docs in other languages, too.
We should use a static page generator instead of WikiJS for the documentation, it's much more stable and can be hosted on GitHub pages.
Candidates: