[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17698118#comment-17698118
]
Jorge Esteban Quilcate Otoya commented on KAFKA-2967:
-----------------------------------------------------
thanks Tom!
Agree. The fragmentation brings the cost of breaking the old references to
`/documentation#...` . Probably some redirection will be possible (e.g. to H2
headers), but some of these will start getting complex to map (e.g.
docs#brokerconfigs_bootstrap.servers to
docs/configuration#brokerconfigs_bootstrap.servers).
It goes outside my experience on how the Apache server we use to host the
documentation is able to cope with these redirections. If someone from the
community has experience tweaking this for our website, I'd be happy to pair
and see how we can make this work as close as possible to the current links.
Another consideration is that static-site will have links to the specific
version (e.g. /35/documentation), so as soon as you get into /documentation all
internal links will refer to /<latest, eg. 35>/documentation. – something
similar to Flink docs [https://nightlies.apache.org/flink/flink-docs-stable/]
About Markdown and Asciidoc, I did a quick try migrating docs from Markdown to
Asciidoc using Pandoc and worked fine, though the website with Hugo had some
small glitches -- but all in all seems easy to migrate. The approach to start
with Markdown and let the doors open for Asciidoc if we found enough reasons to
move sounds good to me as well.
> Move Kafka documentation to ReStructuredText
> --------------------------------------------
>
> Key: KAFKA-2967
> URL: https://issues.apache.org/jira/browse/KAFKA-2967
> Project: Kafka
> Issue Type: Bug
> Reporter: Gwen Shapira
> Assignee: Gwen Shapira
> Priority: Major
> Labels: documentation
>
> Storing documentation as HTML is kind of BS :)
> * Formatting is a pain, and making it look good is even worse
> * Its just HTML, can't generate PDFs
> * Reading and editting is painful
> * Validating changes is hard because our formatting relies on all kinds of
> Apache Server features.
> I suggest:
> * Move to RST
> * Generate HTML and PDF during build using Sphinx plugin for Gradle.
> Lots of Apache projects are doing this.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
