WIP: migrate to mdbook 0.5.0

Author: vitorfloriano

docs/book/book.toml

@@ -1,10 +1,10 @@
 [book]
 authors = ["The Kubebuilder Maintainers"]
-multilingual = false
 src = "src"
 title = "The Kubebuilder Book"
 
 [output.html]
+theme="theme/css"
 smart-punctuation = true
 additional-css = ["theme/css/markers.css", "theme/css/custom.css", "theme/css/version-dropdown.css"]
 git-repository-url = "https://github.com/kubernetes-sigs/kubebuilder"
@@ -15,9 +15,3 @@ command = "./litgo.sh"
 
 [preprocessor.markerdocs]
 command = "./markerdocs.sh"
-
-[context.environment]
-  environment = { GO_VERSION = "1.23" }
-
-[context.deploy-preview.environment]
-  environment = { GO_VERSION = "1.23" }

docs/book/install-and-build.sh

@@ -39,7 +39,7 @@ if [[ ${arch} == "amd64" ]]; then
 elif [[ ${arch} == "x86" ]]; then
     arch="i686"
 elif [[ ${arch} == "arm64" ]]; then
-    # arm64 is not supported for v0.4.40 mdbook, so using x86_64 type. 
+    # arm64 is not supported for v0.4.40 mdbook, so using x86_64 type.
     # Once the mdbook is upgraded to latest, use 'aarch64'
     arch="x86_64"
 fi
@@ -58,7 +58,7 @@ case ${os} in
         ;;
     linux)
         # works for linux, too
-        target="unknown-${os}-gnu"
+        target="unknown-${os}-musl"
         ;;
     *)
         target="unknown-${os}"
@@ -67,7 +67,7 @@ esac
 
 # grab mdbook
 # we hardcode linux/amd64 since rust uses a different naming scheme and it's a pain to tran
-MDBOOK_VERSION="v0.4.40"
+MDBOOK_VERSION="v0.5.0-beta.2" # TODO: using beta just for the migration (wait for 0.5.0 stable)
 MDBOOK_BASENAME="mdBook-${MDBOOK_VERSION}-${arch}-${target}"
 MDBOOK_URL="https://github.com/rust-lang/mdBook/releases/download/${MDBOOK_VERSION}/${MDBOOK_BASENAME}.${ext}"
 

docs/book/src/migration/multi-group.md

@@ -60,7 +60,9 @@ mv internal/webhook/* internal/webhook/batch/
 For any new webhook created for a new group, the respective functions will be created under subdirectory `internal/webhook/<group>/`.
 
 <aside class="note">
+
 <h1>If you are using the deprecated layout go/v3</h1>
+
 Then, your layout has not the internal directory. So, you will move the controller(s) under a directory with the name of the API group which it is responsible for manage.
 
 ```bash
@@ -127,6 +129,8 @@ The [CronJob tutorial][cronjob-tutorial] explains each of these changes in
 more detail (in the context of how they're generated by Kubebuilder for
 single-group projects).
 
+</aside>
+
 [multi-group-issue]: https://github.com/kubernetes-sigs/kubebuilder/issues/923 "Kubebuilder Issue #923"
 [cronjob-tutorial]: /cronjob-tutorial/cronjob-tutorial.md "Tutorial: Building CronJob"
 [migration-guide]: /migration/migration_guide_gov3_to_gov4.md "Migration from go/v3 to go/v4"

docs/book/src/reference/platform.md

@@ -18,7 +18,7 @@ The following covers what you need to do to provide the support for one or more
 
 The images used in workloads such as in your Pods/Deployments will need to provide the support for this other platform.
 You can inspect the images using a ManifestList of supported platforms using the command
-[docker manifest inspect <image>][docker-manifest], i.e.:
+[`docker manifest inspect <image>`][docker-manifest], i.e.:
 
 ```shell
 $ docker manifest inspect myregistry/example/myimage:v0.0.1

docs/book/theme/index.hbs

@@ -49,7 +49,12 @@ func (Literate) SupportsOutput(_ string) bool { return true }
 
 // Process implements plugin.Plugin
 func (l Literate) Process(input *plugin.Input) error {
-	bookSrcDir := filepath.Join(input.Context.Root, input.Context.Config.Book.Src)
+	srcDir := input.Context.Config.Book.Src
+	if srcDir == "" {
+		srcDir = "src" // mdBook 0.5.0 no longer populates this field
+	}
+	bookSrcDir := filepath.Join(input.Context.Root, srcDir)
+
 	return plugin.EachCommand(&input.Book, "literatego", func(chapter *plugin.BookChapter, relPath string) (string, error) {
 		chapterDir := filepath.Dir(chapter.Path)
 		pathInfo := filePathInfo{

docs/book/utils/litgo/literate.go

@@ -164,7 +164,7 @@ func (p MarkerDocs) Process(input *plugin.Input) error {
 		content := new(strings.Builder)
 
 		// NB(directxman12): wrap this in a div to prevent the markdown processor from inserting extra paragraphs
-		_, err := fmt.Fprintf(content, "<div><input checked type=\"checkbox\" class=\"markers-summarize\" id=\"markers-summarize-%[1]s\"></input><label class=\"markers-summarize\" for=\"markers-summarize-%[1]s\">Show Detailed Argument Help</label><dl class=\"markers\">", categoryAlias)
+		_, err := fmt.Fprintf(content, "<div><input checked type=\"checkbox\" class=\"markers-summarize\" id=\"markers-summarize-%[1]s\"><label class=\"markers-summarize\" for=\"markers-summarize-%[1]s\">Show Detailed Argument Help</label><dl class=\"markers\">", categoryAlias)
 		if err != nil {
 			return "", fmt.Errorf("unable to render marker documentation summary: %v", err)
 		}

docs/book/utils/markerdocs/main.go

@@ -40,7 +40,7 @@ type BookConfig struct {
 
 // Book is an mdBook book.
 type Book struct {
-	Sections      []BookItem `json:"sections"`
+	Items         []BookItem `json:"items"`
 	NonExhaustive *struct{}  `json:"__non_exhaustive"`
 }
 
@@ -176,8 +176,8 @@ func EachItem(parentItem *BookItem, visitor ChapterVisitor) error {
 // all chapters in the book.
 func EachItemInBook(book *Book, visitor ChapterVisitor) error {
 	// pass a pointer to the structure, not the iteration variable
-	for i := range book.Sections {
-		if err := EachItem(&book.Sections[i], visitor); err != nil {
+	for i := range book.Items {
+		if err := EachItem(&book.Items[i], visitor); err != nil {
 			return err
 		}
 	}