...

Leverage hugo  and docsy  toolchain to generate static html website from markdown source. Package the website as a docker container and host it behind existing website serving infrastructure.

Prototype

To demonstrate the feasibility of this transition, I created a working prototype of the Apache Kafka documentation using Hugo and Docsy. 

• Prototype : https://kafka-site-md-711970345036.us-central1.run.app/.  

• Source code for the website: https://github.com/hvishwanath/kafka-site-md . Specifically “content/en” directory shows the markdown source with some refactoring for improved maintainability.

I wrote some automation to help with this: https://github.com/hvishwanath/ak2md 

Compatibility, Deprecation, and Migration Plan

...

Write automation to ensure all html source files are converted to markdown. Manual testing to ensure completeness, correctness and required functionality is present in the new website. Run broken link checker to verify that internal links within the documentation are correct.

Rejected Alternatives

...

Alternative Static Site Generators: While other static site generators exist, Hugo was chosen for its popularity, maturity, and strong community support. The Docsy theme aligns well with the needs of technical documentation.