Improve collapsible code sections and formatting on book.kubebuilder.io

[danielskowronski]

I'd like to report a few issues with collapsible codeblock sections in book.kubebuilder.io that have the potential to confuse readers, especially new users.

1. Hidden instructional text: initially collapsed sections that appear to only contain code, actually contain instructions as well (https://book.kubebuilder.io/cronjob-tutorial/webhook-implementation - "Validate object name")
2. Misleading headers in code blocks: collapsible codeblocks have headers formatted as Golang comments and use font only slightly larger than the body of codeblock, which suggests that they are actual comments in code
3. Insufficient separation between blocks: consecutive code blocks (collapsed by default or not collapsible) appear as single code block, which makes it difficult to follow (https://book.kubebuilder.io/cronjob-tutorial/controller-implementation - especially "5: Get the next scheduled run")
4. Lack of highlighting for expanded sections: there's no visual indication of the section that was expanded, which is more problematic on very long pages
5. Verbose license notices: having "Apache License" block does not contribute to the guide (but it's understandably part of the source file) and may confuse users because licence text is shown as instruction text, not codeblock
6. Overly long lines and narrow layout: HTML template makes a hard limit on text (and codeblock) width, but there's no limit to line length in code; I could easily find a line with 390 characters, but it seems like only 89 characters fit into codeblock without horizontal scrolling
7. Lack of proper formatting of shell commands:
   1. none of shell commands use syntax highlighting
   2. some commands are presented as very long lines, making them hard to copy
   3. some commands are formatted like Golang comments (// )
8. Internal headers missing from TOC: if headers are originating from Golang comments, they are not included in TOC and are hard to distinguish from the main body; https://book.kubebuilder.io/cronjob-tutorial/controller-implementation
9. Code of function split into sections is unclear: when function body is split into multiple parts, it's not clear that the body continues

Many of those issues stack and increase cognitive load even more. They are present since v2, but v1 has significantly different contents to compare. I was able to figure out how to read the book only after spending an hour preparing this bug report.

I'd like to offer some improvement suggestions, but I'm not sure whether problems originate from comments in Golang code, tooling used (litgo.sh, mdBook) or HTML templates.

• consider disabling collapsible sections (quickest workaround, but it's already a book)
• clearly highlight codeblock boundaries - add borders and padding on bottom
• change style of codeblock title - invert colours, drop //
• format Golang code (of examples in book) for web readability (e.g. force 80 columns limit)
• add copy button to codeblocks in HTML
• highlight contents of collapsible sections - add borders, slightly different background or consider very subtle animation; additionally add extra padding on the bottom
• format Golang code with rendering inside HTML in mind - prefix separate chunks of functions with a comment containing "continuation of ..." or just function signature
• ensure that only codeblock collapses and that licence headers are skipped

As a test case, I propose giving this book to someone who's new to kubebuilder and internal k8s APIs it and verify if it's obvious to read.

I think that lowering the barrier to entry will attract new users and contributors :)

If you agree with my observations and those issues are caused mainly by the HTML template used, I can offer a contribution.

[camilamacedo86]

Hi @danielskowronski 👋

Thanks a lot for offering help! 🙌 Improving the docs is always appreciated.
Let me explain how things work, and then please feel free to send as many PRs as you want with improvements.

---

📚 Where are the docs?

• Main docs repo:
  https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book

• Tutorial pages and their code:
  https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src

Example:
The CronJob tutorial content comes from real code, in this folder:
https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/cronjob-tutorial/testdata/project

---

🤖 Why do we do it this way?

Because this setup:

✅ Keeps the tutorial code working and tested
✅ Makes sure the docs stay up to date with the latest changes
✅ Helps us automate updates when things change in the CLI

We run end-to-end (e2e) tests to make sure everything still works:
https://github.com/kubernetes-sigs/kubebuilder/blob/master/.github/workflows/test-e2e-book.yml

---

🛠️ When changing scaffolds

If you look at the contributing guide:
https://github.com/kubernetes-sigs/kubebuilder/blob/master/CONTRIBUTING.md

You’ll see that when we change scaffold code, we must run:

make generate

This command:

• Regenerates samples under the testdata/ folder
  (see: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata)
• Updates the code used in the tutorials automatically

More details in the Makefile:

kubebuilder/Makefile

Lines 69 to 73 in 59fbd4c

	.PHONY: generate
	generate: generate-testdata generate-docs update-k8s-version ## Update/generate all mock data. You should run this commands to update the mock data after your changes.
	go mod tidy
	make remove-spaces

kubebuilder/Makefile

Lines 90 to 92 in 59fbd4c

	.PHONY: generate-docs
	generate-docs: ## Update/generate the docs
	./hack/docs/generate.sh

---

📦 How do the examples get into the docs?

In this folder:
https://github.com/kubernetes-sigs/kubebuilder/tree/master/hack/docs/internal

We run the latest version of the CLI, scaffold projects, and automatically insert the code into the docs.

We use special markers like this:
// +kubebuilder:docs-gen:collapse=What this does

Example:

kubebuilder/docs/book/src/cronjob-tutorial/testdata/project/internal/controller/cronjob_controller.go

Line 69 in 59fbd4c

// +kubebuilder:docs-gen:collapse=Clock

Also, we pull text and doc content directly from comments in the code:
https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/src/cronjob-tutorial/testdata/project/internal/controller/cronjob_controller.go#L137-L160

---

🐛 About the issues you raised

Thank you for your detailed feedback! These are all great points.
You’re totally right that it increases the “cognitive load.” 🧠

All of these would really improve the experience. If you want to contribute and tweak the templates or tooling (like mdBook or HTML styles), that would be awesome!

Let me know if you'd like help getting started with that.
Thanks again for your help and thoughtful ideas! 🙏

[mayuka-c]

I could probably take a look into this, once I'm done with Unit tests :-). @danielskowronski Please do let me know if you have already started working on this.

[danielskowronski]

@mayuka-c I only reviewed the code and though about visual aspects. So far, I came to following conclusion:

1. tools involved in generating book work as expected
2. documentation in comments of source code of tutorials seems not to take into consideration how it'd be rendered in book
3. book styling can also be improved; I've seen some good example of how tutorial book should look like, but I didn't bookmark it :(

I'll try to find that example book and will be definitely able to help with styling once comments in code are improved/reorganized. I don't think I'm qualified to rework docs content as I'm still learning kubebuilder ;)

I also know at least one person who will be looking at kubebuilder fresh, so it could be a good test subject to verify if it's readable.