[DISCUSS] Migrating documentation to Markdown/Hugo

[Jorge Esteban Quilcate Otoya <qu...@gmail.com>]

Hi all,

I wanted to share on the mailing list a follow up from
https://issues.apache.org/jira/browse/KAFKA-2967 to gather feedback from a
wider audience:

I put together a static-site generation with Hugo, and migrated most of the
documentation under `docs/` to Markdown using Pandoc:
https://github.com/jeqo/ak-docs

Hopefully the readme is good enough for anyone who wants to test it. Did
some initial integration with kafka-site to check how that would look.

There are some style minor details (e.g. URLs, image sizing, kafka streams
navigation, generate JSON instead of HTML on Config/Metrics, etc) that
could be discussed in a following issue, but I'd like to get feedback at
this point to see if the migration seems promising and what the next steps
could be.

Original HTMLs are kept to diff with current repo and align any diff, and
potentially the content of the repo could go under kafka/docs directory.

Looking forward to your feedback!

Jorge.

Re: [DISCUSS] Migrating documentation to Markdown/Hugo

[Luke Chen <sh...@gmail.com>]

Hi Jorge,

Maintaining the HTML doc is pretty troublesome.
So, I'm +1 to have this migration!

My thought is that we can have old version and new(Hugo) version co-existed
in kafka-site for a period of time, and then replace the old one.

Thank you.
Luke

On Wed, Mar 8, 2023 at 5:25 AM Jorge Esteban Quilcate Otoya <
quilcate.jorge@gmail.com> wrote:

> Hi all,
>
> I wanted to share on the mailing list a follow up from
> https://issues.apache.org/jira/browse/KAFKA-2967 to gather feedback from a
> wider audience:
>
> I put together a static-site generation with Hugo, and migrated most of the
> documentation under `docs/` to Markdown using Pandoc:
> https://github.com/jeqo/ak-docs
>
> Hopefully the readme is good enough for anyone who wants to test it. Did
> some initial integration with kafka-site to check how that would look.
>
> There are some style minor details (e.g. URLs, image sizing, kafka streams
> navigation, generate JSON instead of HTML on Config/Metrics, etc) that
> could be discussed in a following issue, but I'd like to get feedback at
> this point to see if the migration seems promising and what the next steps
> could be.
>
> Original HTMLs are kept to diff with current repo and align any diff, and
> potentially the content of the repo could go under kafka/docs directory.
>
> Looking forward to your feedback!
>
> Jorge.
>