Move Documentation website to another documentation engine

[oleg-nenashev]

Currently the documentation uses Jekyll, and it is pretty weak when it comes to product-grade documentation (macros, external sourcing for docs-as-code, etc., etc.). I think it would be preferable to have another documentation engine, preferably Docusaurus or Hugo. I find Docusaurus much more powerful and sustainable if we must stick to Markdown, but IIUIC @tomakehurst prefers Hugo. If we want to have professional documentation with a lot of future scalability, we should probably adopt AsciiDoc and Antora right away. Subject for a discussion.

Preview

https://oleg-nenashev.github.io/wiremock.org/

TODOs

• Engines evaluation and selection
• Initial migration of documentation: Migrate documentation to MkDocs #228
• Restructuring of repositories to use documentation as code, e.g. moving Docker docs to https://github.com/wiremock/wiremock-docker
• TBD: Move main chunk of docs to https://github.com/wiremock/wiremock
• Update references in the documentation to reduce number of redirects

References

• Engine Evaluation Notes
• [MkDocs PoC] - https://github.com/wiremock/components-site/
• Antora PoC - see the notes
• https://docusaurus.io/
• https://gohugo.io/
• https://antora.org/ - for AsciiDoc hence more professional

[oleg-nenashev]

TL;DR: This week in my head

[SimonVerhoeven]

Antora's quite pleasant to work with

[oleg-nenashev]

@SimonVerhoeven Yes, indeed. The biggest problem there is need to have Markdown, and it creates quite a lot of issues with Antora. I have a pending discussion about this on Antora Zulip (here). You can find my evaluation notes here too. If I do not manage to sort Markdown support in a reasonable way, might end up with MkDocs + Multirepo recommendation