Skip to content

📖 Improve collapsible code sections and formatting of tutorials #5175

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

📖 Improve collapsible code sections and formatting of tutorials #5175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion docs/book/book.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,3 @@ command = "./markerdocs.sh"

[context.deploy-preview.environment]
environment = { GO_VERSION = "1.23" }

5 changes: 3 additions & 2 deletions docs/book/src/cronjob-tutorial/testdata/project/cmd/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ func main() {
os.Exit(1)
}

// +kubebuilder:docs-gen:collapse=old stuff
// +kubebuilder:docs-gen:collapse=Remaining code from main.go

if err := (&controller.CronJobReconciler{
Client: mgr.GetClient(),
Expand Down Expand Up @@ -239,5 +239,6 @@ func main() {
setupLog.Error(err, "problem running manager")
os.Exit(1)
}
// +kubebuilder:docs-gen:collapse=old stuff
}

// +kubebuilder:docs-gen:collapse=Remaining code from main.go
2 changes: 1 addition & 1 deletion docs/book/src/cronjob-tutorial/testdata/project/internal/controller/cronjob_controller.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ type Clock interface {
Now() time.Time
}

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

// Definitions to manage status conditions
const (
Expand Down
2 changes: 2 additions & 0 deletions ...book/src/cronjob-tutorial/testdata/project/internal/controller/cronjob_controller_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,8 @@ var _ = Describe("CronJob controller", func() {

})

// +kubebuilder:docs-gen:collapse=Remaining code from cronjob_controller_test.go

/*
After writing all this code, you can run `go test ./...` in your `controllers/` directory again to run your new test!
*/
2 changes: 2 additions & 0 deletions docs/book/src/cronjob-tutorial/testdata/project/internal/controller/suite_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,8 @@ var _ = AfterSuite(func() {
Expect(err).NotTo(HaveOccurred())
})

// +kubebuilder:docs-gen:collapse=Remaining code from suite_test.go

/*
Now that you have your controller running on a test cluster and a client ready to perform operations on your CronJob, we can start writing integration tests!
*/
Expand Down
4 changes: 2 additions & 2 deletions docs/book/src/cronjob-tutorial/testdata/project/internal/webhook/v1/cronjob_webhook.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ import (
batchv1 "tutorial.kubebuilder.io/project/api/v1"
)

// +kubebuilder:docs-gen:collapse=Go imports
// +kubebuilder:docs-gen:collapse=Imports

/*
Next, we'll setup a logger for the webhooks.
Expand Down Expand Up @@ -279,4 +279,4 @@ func validateCronJobName(cronjob *batchv1.CronJob) *field.Error {
return nil
}

// +kubebuilder:docs-gen:collapse=Validate object name
// +kubebuilder:docs-gen:collapse=validateCronJobName() Code Implementation
4 changes: 2 additions & 2 deletions docs/book/src/multiversion-tutorial/testdata/project/api/v1/cronjob_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ type CronJobStatus struct {
Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:docs-gen:collapse=old stuff
// +kubebuilder:docs-gen:collapse=Remaining code from cronjob_types.go

/*
Since we'll have more than one version, we'll need to mark a storage version.
Expand Down Expand Up @@ -183,4 +183,4 @@ func init() {
SchemeBuilder.Register(&CronJob{}, &CronJobList{})
}

// +kubebuilder:docs-gen:collapse=old stuff
// +kubebuilder:docs-gen:collapse=Remaining code from cronjob_types.go
6 changes: 2 additions & 4 deletions docs/book/src/multiversion-tutorial/testdata/project/api/v2/cronjob_conversion.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,7 @@ func (src *CronJob) ConvertTo(dstRaw conversion.Hub) error {
dst.Status.Active = src.Status.Active
dst.Status.LastScheduleTime = src.Status.LastScheduleTime

// +kubebuilder:docs-gen:collapse=rote conversion

// +kubebuilder:docs-gen:collapse=rest of conversion Code Implementation
return nil
}

Expand Down Expand Up @@ -141,7 +140,6 @@ func (dst *CronJob) ConvertFrom(srcRaw conversion.Hub) error {
dst.Status.Active = src.Status.Active
dst.Status.LastScheduleTime = src.Status.LastScheduleTime

// +kubebuilder:docs-gen:collapse=rote conversion

// +kubebuilder:docs-gen:collapse=rest of conversion Code Implementation
return nil
}
5 changes: 2 additions & 3 deletions docs/book/src/multiversion-tutorial/testdata/project/api/v2/cronjob_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,11 +83,10 @@ type CronJobSpec struct {
// +optional
// +kubebuilder:validation:Minimum=0
FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`

// +kubebuilder:docs-gen:collapse=The rest of Spec

}

// +kubebuilder:docs-gen:collapse=CronJobSpec Full Code

/*
Next, we'll need to define a type to hold our schedule.
Based on our proposed YAML above, it'll have a field for
Expand Down
9 changes: 5 additions & 4 deletions docs/book/src/multiversion-tutorial/testdata/project/cmd/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,6 @@ func main() {
setupLog.Error(err, "unable to create controller", "controller", "CronJob")
os.Exit(1)
}
// +kubebuilder:docs-gen:collapse=existing setup

/*
Our existing call to SetupWebhookWithManager registers our conversion webhooks with the manager, too.
Expand All @@ -225,8 +224,7 @@ func main() {
}
// +kubebuilder:scaffold:builder

/*
*/
// +kubebuilder:docs-gen:collapse=Remaining code from main.go

if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
setupLog.Error(err, "unable to set up health check")
Expand All @@ -242,5 +240,8 @@ func main() {
setupLog.Error(err, "problem running manager")
os.Exit(1)
}
// +kubebuilder:docs-gen:collapse=existing setup
}

// +kubebuilder:docs-gen:collapse=Remaining code from main.go

// +kubebuilder:docs-gen:collapse=Remaining code from main.go
2 changes: 1 addition & 1 deletion ...book/src/multiversion-tutorial/testdata/project/internal/controller/cronjob_controller.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ type Clock interface {
Now() time.Time
}

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

// Definitions to manage status conditions
const (
Expand Down
2 changes: 2 additions & 0 deletions ...src/multiversion-tutorial/testdata/project/internal/controller/cronjob_controller_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,8 @@ var _ = Describe("CronJob controller", func() {

})

// +kubebuilder:docs-gen:collapse=Remaining code from cronjob_controller_test.go

/*
After writing all this code, you can run `go test ./...` in your `controllers/` directory again to run your new test!
*/
2 changes: 2 additions & 0 deletions docs/book/src/multiversion-tutorial/testdata/project/internal/controller/suite_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,8 @@ var _ = AfterSuite(func() {
Expect(err).NotTo(HaveOccurred())
})

// +kubebuilder:docs-gen:collapse=Remaining code from suite_test.go

/*
Now that you have your controller running on a test cluster and a client ready to perform operations on your CronJob, we can start writing integration tests!
*/
Expand Down
4 changes: 2 additions & 2 deletions docs/book/src/multiversion-tutorial/testdata/project/internal/webhook/v1/cronjob_webhook.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ import (
batchv1 "tutorial.kubebuilder.io/project/api/v1"
)

// +kubebuilder:docs-gen:collapse=Go imports
// +kubebuilder:docs-gen:collapse=Imports

/*
Next, we'll setup a logger for the webhooks.
Expand Down Expand Up @@ -284,4 +284,4 @@ func validateCronJobName(cronjob *batchv1.CronJob) *field.Error {
return nil
}

// +kubebuilder:docs-gen:collapse=Validate object name
// +kubebuilder:docs-gen:collapse=validateCronJobName() Code Implementation
1 change: 1 addition & 0 deletions docs/book/src/multiversion-tutorial/testdata/project/internal/webhook/v2/cronjob_webhook.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
// +kubebuilder:docs-gen:collapse=Apache License

package v2

Expand Down
9 changes: 9 additions & 0 deletions docs/book/theme/css/markers.css
View file
Open in desktop
Copy link
Contributor

@vitorfloriano vitorfloriano Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@camilamacedo86 I checked the preview and it seems that some copy buttons are still missing. See: https://deploy-preview-5175--kubebuilder.netlify.app/cronjob-tutorial/empty-main#every-journey-needs-a-start-every-program-needs-a-main

In code blocks that they are not missing, they are misplaced. See: https://deploy-preview-5175--kubebuilder.netlify.app/cronjob-tutorial/cronjob-tutorial#scaffolding-out-our-project

The custom CSS seems to be affecting how the copy buttons are displayed.

For testing, I checked out your PR and served the book using mdBook v0.4.40, then I deleted the custom CSS to see what happens and all the code blocks displayed the copy button properly (other parts broke, though 😅):

Image

Copy link
Member Author

@camilamacedo86 camilamacedo86 Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/hold

I will be looking on that
Good catcher.

Copy link
Contributor

@vitorfloriano vitorfloriano Nov 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @camilamacedo86

I fixed the issue with the copy button and the license blocks. See #5184 and #5183.

Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,11 @@ input.markers-summarize:checked ~ label.markers-summarize::before {
margin-top: 0.125em;
}

/* Completely hide low-value collapsed sections (license text, imports) */
details.collapse-hide {
display: none;
}

/* details elements (not markers) */
details.collapse-code > summary {
width: 100%;
Expand Down Expand Up @@ -248,6 +253,10 @@ details.collapse-code[open] > summary pre span::after {
content: "";
}

details.collapse-code > summary pre span.collapse-summary::before {
content: "// ";
}

details.collapse-code > summary pre span::before {
content: "// ";
}
Expand Down
10 changes: 6 additions & 4 deletions docs/book/utils/litgo/literate.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,10 +242,12 @@ func (l Literate) extractContents(contents []byte, pathInfo filePathInfo) (strin

for _, pair := range pairs {
if pair.collapse != "" {
// NB(directxman12): we add the hljs class to "cheat" and get the
// right background with theming, since hljs doesn't use CSS
// variables.
out.WriteString("<details class=\"collapse-code\"><summary class=\"hljs\"><pre class=\"hljs\"><span class=\"hljs-comment\">")
collapseClass := "collapse-code"
// Hide low-value sections entirely (licenses, imports, etc)
if strings.EqualFold(pair.collapse, "Apache License") || strings.EqualFold(pair.collapse, "Imports") {
collapseClass = "collapse-code collapse-hide"
}
out.WriteString("<details class=\"" + collapseClass + "\"><summary class=\"hljs\"><pre class=\"hljs\"><span class=\"collapse-summary\">")
out.WriteString(pair.collapse)
out.WriteString("</span></pre></summary>")
}
Expand Down
2 changes: 1 addition & 1 deletion hack/docs/internal/cronjob-tutorial/controller_implementation.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ type Clock interface {
Now() time.Time
}
// +kubebuilder:docs-gen:collapse=Clock
// +kubebuilder:docs-gen:collapse=Clock Code Implementation
// Definitions to manage status conditions
const (
Expand Down
7 changes: 4 additions & 3 deletions hack/docs/internal/cronjob-tutorial/generate_cronjob.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -358,7 +358,7 @@ CronJob controller's`+" `"+`SetupWithManager`+"`"+` method.
os.Exit(1)
}`, `

// +kubebuilder:docs-gen:collapse=old stuff`)
// +kubebuilder:docs-gen:collapse=Remaining code from main.go`)
hackutils.CheckError("fixing main.go", err)

err = pluginutil.InsertCode(
Expand All @@ -372,8 +372,9 @@ CronJob controller's`+" `"+`SetupWithManager`+"`"+` method.
filepath.Join(sp.ctx.Dir, "cmd/main.go"),
`setupLog.Error(err, "problem running manager")
os.Exit(1)
}`, `
// +kubebuilder:docs-gen:collapse=old stuff`)
}
}`, `
// +kubebuilder:docs-gen:collapse=Remaining code from main.go`)
hackutils.CheckError("fixing main.go", err)
}

Expand Down
4 changes: 2 additions & 2 deletions hack/docs/internal/cronjob-tutorial/webhook_implementation.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ package cronjob
const webhookIntro = `batchv1 "tutorial.kubebuilder.io/project/api/v1"
)

// +kubebuilder:docs-gen:collapse=Go imports
// +kubebuilder:docs-gen:collapse=Imports

/*
Next, we'll setup a logger for the webhooks.
Expand Down Expand Up @@ -178,7 +178,7 @@ func validateCronJobName(cronjob *batchv1.CronJob) *field.Error {
return nil
}

// +kubebuilder:docs-gen:collapse=Validate object name`
// +kubebuilder:docs-gen:collapse=validateCronJobName() Code Implementation`

const fragmentForDefaultFields = `
// Default values for various CronJob fields
Expand Down
1 change: 1 addition & 0 deletions hack/docs/internal/cronjob-tutorial/writing_tests_controller.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,7 @@ var _ = Describe("CronJob controller", func() {
})
})
// +kubebuilder:docs-gen:collapse=Remaining code from cronjob_controller_test.go
/*
After writing all this code, you can run` + " `" + `go test ./...` + "`" + ` in your` + " `" + `controllers/` + "`" + ` directory again to run your new test!
Expand Down
1 change: 1 addition & 0 deletions hack/docs/internal/cronjob-tutorial/writing_tests_env.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@ var _ = AfterSuite(func() {
err := testEnv.Stop()
Expect(err).NotTo(HaveOccurred())
})
// +kubebuilder:docs-gen:collapse=Remaining code from suite_test.go

/*
Now that you have your controller running on a test cluster and a client ready to perform operations on your CronJob, we can start writing integration tests!
Expand Down
2 changes: 1 addition & 1 deletion hack/docs/internal/multiversion-tutorial/cronjob_v1.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ const statusDesignComment = `/*
serialization, as mentioned above.
*/`

const boilerplateReplacement = `// +kubebuilder:docs-gen:collapse=old stuff
const boilerplateReplacement = `// +kubebuilder:docs-gen:collapse=Remaining code from cronjob_types.go

/*
Since we'll have more than one version, we'll need to mark a storage version.
Expand Down
5 changes: 2 additions & 3 deletions hack/docs/internal/multiversion-tutorial/cronjob_v2.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,11 +64,10 @@ const cronjobSpecMore = `// startingDeadlineSeconds defines in seconds for start
// +optional
// +kubebuilder:validation:Minimum=0
FailedJobsHistoryLimit *int32 ` + "`json:\"failedJobsHistoryLimit,omitempty\"`" + `

// +kubebuilder:docs-gen:collapse=The rest of Spec

}

// +kubebuilder:docs-gen:collapse=CronJobSpec Full Code

/*
Next, we'll need to define a type to hold our schedule.
Based on our proposed YAML above, it'll have a field for
Expand Down
Loading