Eksctl: Re-launch docs using MkDocs

[mhausenblas]

Why do you want this feature?
The current docs are hard to consume, especially for new users. Things like search (see #1143) are missing.

What feature/behavior/change do you want?
To have the docs (with the same content) re-launched using MkDocs. I've used it a couple of times, for example here and here and I think it would be beneficial to use it for eksctl docs as well. It's both powerful and easy to use, so we can hopefully expect community contribs as well. I volunteer to put together an PoC and if we can agree that we want this, take care of the migration.

[mhausenblas]

For a preview of the new docs, see http://mhausenblas.info/eksctl/

[martina-if]

Hi @mhausenblas , thanks for putting the PoC together. I would like to understand better what are the pros and cons of Mkdocs vs Hugo. Can you elaborate more on why you want this big change?

[mhausenblas]

Can you elaborate more on why you want this big change?

To simplify docs, make them searchable, get more contributions, spend less time re-inventing the wheel.

[marccarre]

FWIW, I'm not opposed to switching to a new tool, but would rather have a clear list of pros & cons to explain & document the rationale. (This is useful now, to understand the change, but also for posterity.)

At the moment, I'm not sure I understand why it simplifies docs, helps get more contributions, and helps spend less time re-inventing the wheel, sorry. 😅 Would you mind elaborating?
Moreover, it seems search can work with Hugo+Lunr too:

• https://gohugo.io/tools/search/
• https://codewithhugo.com/search/?q=lunrjs

Any reason for not using these @mhausenblas?

[mhausenblas]

OK folks, thanks a lot for all your feedback and questions. I believe that if we can make sure that none of Bianca's efforts is lost and we can sort out the "live preview" issue, we might have a way forward here.

For the live preview requirement, I see (at least) three options:

1. Zero option, that is, no live preview, only mkdocs serve locally
2. A home-grown, GitHub Actions-based solution
3. Keep Netlify as the publishing platform and leverage it as per now

WDYT?

[dholbach]

Since we just merged #2058 this is mostly resolved now.

Remaining AFAICS:

• [x] re-add 404 page #2061
• [ ] recover relevant parts of the previous CSS
• [x] add link checking #958 (PR: #2062)
• [x] search #1143

[dholbach]

I moved the last open task to #2090