Details
-
Task
-
Status: Open
-
Major
-
Resolution: Unresolved
-
None
-
None
-
None
Description
Follow up from https://issues.apache.org/jira/browse/KAFKA-2967
Creating this task to discuss the adoption of Markdown and Hugo, and replace the HTML code.
The reasons to move away from HTML are outlined in KAFKA-2967.
Markdown and Asciidoc are both alternatives, but Markdown has been used, as I found some blockers when trying to migrate to Asciidoc:
- Hugo requires Asciidoctor as additional binary (Markdown supported ootb)
- To use Asciidoctor some security policies need to be opened: https://stackoverflow.com/questions/71058236/hugo-with-asciidoctor
- I haven't managed to use shortcodes in Asciidoctor to inject versions, tables, etc.
Given the lower friction of Markdown and default support from Hugo, I would like to propose using these. Though I'm open to collaborate if someone has experience with Asciidoc and Hugo to make the migration as there is an existing interest to use Asciidoc if possible.
Draft repo: https://github.com/jeqo/ak-docs
Attachments
Issue Links
- supercedes
-
KAFKA-2967 Move Kafka documentation to ReStructuredText
- Open
- links to