📖 (docs/infra): Migrate to mdBook v0.5.0

[vitorfloriano]

This PR migrates the Kubebuilder book from mdBook v0.4.40 to v0.5.0.

Since this is a breaking change, the custom preprocessors (literatego and markerdocs) had to be slightly adjusted. The mdBook parser also got stricter and some fixes were necessary. See the mdBook v0.5 migration guide.

mdBook v0.5.0 introduces fixes and a some nice features that could improve the book DX and UX. To name a few:

• Header navigation in the Table of Contents ("On this page")
• The TOC now follows and highlights the current page
• Support for definition lists in markdown (could be useful for the markers section)
• Support for admonitions in markdown (could be useful for highlighting important info, like tips, warnings, notes, etc)

Related to #4862

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: vitorfloriano
Once this PR has been reviewed and has the lgtm label, please assign kavinjsir for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

Hi @vitorfloriano. Thanks for your PR.

I'm waiting for a github.com member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[vitorfloriano]

@camilamacedo86 Now that mdBook v0.5.0 is out, I think this one is ready to ship.

I believe the deployment is failing right now due to another Cloudflare global network issue, so I guess we need to wait and see what happens when it's fixed.

[camilamacedo86]

Hi @vitorfloriano

That seems amazing 🎉
That only thing that is not playing nice for us is all sub-sections be render in the menu ie:

Is possible do not have that?
WDYT?

[vitorfloriano]

@camilamacedo86 Unfortunately, it's not possible to not fold deeply nested sections like those. See this comment from the maintainer.

I could, though, include more foldable sections, like this:

I could also make them foldable but open by default, but the deeply nested sections would still be folded:

This is simply a matter of config:

Suggested change

	[output.html.fold]
	enable = true
	level = 5 # 0 would be all folded

[camilamacedo86]

Could we not enable = false to not have this behaviour?

[vitorfloriano]

Could we not enable = false to not have this behaviour?

@camilamacedo86 This config defaults to false. That's how it currently is. But the deep nested headers will always be folded, no matter the config.

[camilamacedo86]

If you find any way of reduce that, I think it would be great already

[camilamacedo86]

That is really bad :-(

[camilamacedo86]

very confusing :-(

[vitorfloriano]

@camilamacedo86 I tweaked some CSS classes. See if you like it.

[vitorfloriano]

The deployment is not showing the changes in the last commit...🤔 Perhaps it's showing a cached version of the website?

[vitorfloriano]

With the latest tweaks I was able to show all sections in my localhost, but somehow the deploy preview is not updating...