Skip to content

[WIP]: Documentation restructuring - #4874

Draft
CsatariGergely wants to merge 3 commits into
kptdev:mainfrom
nokia:bookless-docs
Draft

CsatariGergely wants to merge 3 commits into
kptdev:mainfrom
nokia:bookless-docs

Conversation

@CsatariGergely

Copy link
Copy Markdown
Contributor

Adding the structure agreed in #4451

Closes: #4451

Adding the structure agreed in kptdev#4451

Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>
@CsatariGergely
CsatariGergely requested review from a team and a balanced review from Copilot November 13, 2026 12:19
@netlify

netlify Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for kptdocs ready!

Name Link
🔨 Latest commit d09f2cb
🔍 Latest deploy log https://app.netlify.com/projects/kptdocs/deploys/6afdbe650bc173095d117820
😎 Deploy Preview https://deploy-preview-4874--kptdocs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@CsatariGergely
CsatariGergely marked this pull request as draft November 13, 2026 12:19
@CsatariGergely CsatariGergely changed the title Documentation restructuring [WIP]: Documentation restructuring Nov 13, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Unresolved issues break reference navigation and existing schema URLs, while the published Plan schema does not match the CLI output.

3 open issues
What changed in this PR

This PR begins restructuring kpt documentation into topic- and task-based sections, following #4451’s move away from a book-centered layout.

Changes:

  • Adds section scaffolding for concepts, installation, getting started, guides, FAQ, and contributing.
  • Relocates reference documentation, adds legacy page aliases, and updates links and generation paths.
  • Restores sidebar navigation and uses the documentation tree on the homepage.
File Description
scripts/​generate-schema.sh Updates schema output paths.
documentation/​README.md Updates documentation-link examples.
documentation/​layouts/​partials/​sidebar.html Adds sidebar rendering and homepage root selection.
documentation/​layouts/​partials/​sidebar-tree.html Removes the sidebar-disabling override.
documentation/​content/​en/​reference/​_index.md Removes the former reference landing page.
documentation/​content/​en/​guides/​3-way-merge.md Updates reference links.
documentation/​content/​en/​faq.md Updates the function reference link.
documentation/​content/​en/​documentation/​8-contributing/​documentation-contribution/​error-messages-style-guide.md Adds an error-style-guide entry.
documentation/​content/​en/​documentation/​8-contributing/​documentation-contribution/​_index.md Adds a documentation-contribution entry.
documentation/​content/​en/​documentation/​8-contributing/​code-contribution.md Adds a code-contribution entry.
documentation/​content/​en/​documentation/​8-contributing/​_index.md Adds the contributing section scaffold.
documentation/​content/​en/​documentation/​7-FAQ/​_index.md Adds the FAQ section scaffold.
documentation/​content/​en/​documentation/​6-references/​schema/​resource-list/​_index.md Relocates the reference and adds a legacy alias.
documentation/​content/​en/​documentation/​6-references/​schema/​plan/​plan.yaml Publishes the Plan schema at the new path.
documentation/​content/​en/​documentation/​6-references/​schema/​plan/​_index.md Relocates the reference and adds a legacy alias.
documentation/​content/​en/​documentation/​6-references/​schema/​kptfile/​kptfile.yaml Publishes the YAML schema at the new path.
documentation/​content/​en/​documentation/​6-references/​schema/​kptfile/​kptfile.json Publishes the JSON schema at the new path.
documentation/​content/​en/​documentation/​6-references/​schema/​kptfile/​_index.md Relocates the reference and adds a legacy alias.
documentation/​content/​en/​documentation/​6-references/​schema/​function-result-list/​_index.md Relocates the reference and adds a legacy alias.
documentation/​content/​en/​documentation/​6-references/​schema/​crd-status-convention/​_index.md Relocates the reference and adds a legacy alias.
documentation/​content/​en/​documentation/​6-references/​schema/​_index.md Relocates the schema section and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​pkg/​update/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​pkg/​tree/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​pkg/​init/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​pkg/​get/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​pkg/​diff/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​pkg/​cat/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​pkg/​_index.md Moves package commands into the new reference tree.
documentation/​content/​en/​documentation/​6-references/​cli/​live/​status/​_index.md Relocates documentation and updates the apply link.
documentation/​content/​en/​documentation/​6-references/​cli/​live/​migrate/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​live/​install-resource-group/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​live/​init/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​live/​destroy/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​live/​apply/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​live/​_index.md Moves deployment commands into the new reference tree.
documentation/​content/​en/​documentation/​6-references/​cli/​fn/​source/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​fn/​sink/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​fn/​render/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​fn/​eval/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​fn/​doc/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​fn/​_index.md Moves function commands into the new reference tree.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​wasm/​push/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​wasm/​pull/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​wasm/​_index.md Moves WASM commands into the new reference tree.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​sync/​get/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​sync/​delete/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​sync/​create/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​sync/​_index.md Moves sync commands into the new reference tree.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​live/​plan/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​live/​_index.md Moves alpha deployment commands into the new tree.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​license/​info/​_index.md Relocates command documentation and adds an alias.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​license/​_index.md Moves license commands into the new reference tree.
documentation/​content/​en/​documentation/​6-references/​cli/​alpha/​_index.md Moves alpha commands into the new reference tree.
documentation/​content/​en/​documentation/​6-references/​cli/​_index.md Relocates the CLI overview and updates command links.
documentation/​content/​en/​documentation/​6-references/​annotations/​local-config/​_index.md Relocates the annotation reference and adds an alias.
documentation/​content/​en/​documentation/​6-references/​annotations/​depends-on/​_index.md Relocates the annotation reference and adds an alias.
documentation/​content/​en/​documentation/​6-references/​annotations/​apply-time-mutation/​_index.md Relocates the reference and updates fragment links.
documentation/​content/​en/​documentation/​6-references/​annotations/​_index.md Relocates the annotation overview and updates links.
documentation/​content/​en/​documentation/​6-references/​_index.md Adds the replacement reference landing page.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​updating-a-package/​effective-customizations.md Adds an effective-customizations placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​updating-a-package/​_index.md Adds a package-update section scaffold.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​rendering-a-package.md Adds a package-rendering placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​publishing-a-package.md Adds a package-publishing placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​getting-a-package.md Adds a package-fetching placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​exploring-a-package.md Adds a package-exploration placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​excluding-files-with-krmignore.md Adds a file-exclusion placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​editing-a-package.md Adds a package-editing placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​deploying-packages.md Adds a package-deployment placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​creating-a-package.md Adds a package-creation placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​composing-a-package.md Adds a package-composition placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-kpt-packages/​_index.md Adds the package-guides section.
documentation/​content/​en/​documentation/​5-guides/​working-with-functions/​imperative-function-execution.md Adds an imperative-execution placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-functions/​function-results.md Adds a function-results placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-functions/​developing-functions.md Adds a function-development placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-functions/​declarative-function-execution.md Adds a declarative-execution placeholder.
documentation/​content/​en/​documentation/​5-guides/​working-with-functions/​_index.md Adds the function-guides section.
documentation/​content/​en/​documentation/​5-guides/​krm-function-developer-guide.md Adds a KRM developer-guide placeholder.
documentation/​content/​en/​documentation/​5-guides/​ci-user-guide.md Adds a CI user-guide placeholder.
documentation/​content/​en/​documentation/​5-guides/​advanced-topics/​variant-constructor-pattern.md Adds a variant-constructor placeholder.
documentation/​content/​en/​documentation/​5-guides/​advanced-topics/​value-propagation-pattern.md Adds a value-propagation placeholder.
documentation/​content/​en/​documentation/​5-guides/​advanced-topics/​understanding-3-way-merge.md Adds a three-way-merge placeholder.
documentation/​content/​en/​documentation/​5-guides/​advanced-topics/​tenant-onboarding.md Adds a tenant-onboarding placeholder.
documentation/​content/​en/​documentation/​5-guides/​advanced-topics/​_index.md Adds the advanced-topics section.
documentation/​content/​en/​documentation/​5-guides/​_index.md Adds the guides section scaffold.
documentation/​content/​en/​documentation/​4-getting-started/​system-requirements.md Adds a system-requirements placeholder.
documentation/​content/​en/​documentation/​4-getting-started/​quickstart.md Adds a quickstart placeholder.
documentation/​content/​en/​documentation/​4-getting-started/​_index.md Adds the getting-started section scaffold.
documentation/​content/​en/​documentation/​3-intallation/​source.md Adds a source-installation placeholder.
documentation/​content/​en/​documentation/​3-intallation/​homebrew.md Adds a Homebrew-installation placeholder.
documentation/​content/​en/​documentation/​3-intallation/​docker.md Adds a Docker-installation placeholder.
documentation/​content/​en/​documentation/​3-intallation/​_index.md Adds the installation section scaffold.
documentation/​content/​en/​documentation/​2-concepts/​workflows.md Adds a workflows placeholder.
documentation/​content/​en/​documentation/​2-concepts/​packages.md Adds a package-concepts placeholder.
documentation/​content/​en/​documentation/​2-concepts/​functions.md Adds a function-concepts placeholder.
documentation/​content/​en/​documentation/​2-concepts/​_index.md Adds the concepts section scaffold.
documentation/​content/​en/​documentation/​1-overview/​_index.md Adds an overview section placeholder.
documentation/​content/​en/​documentation/​_index.md Adds the new documentation root.
documentation/​content/​en/​book/​08-ci-user-guide/​_index.md Updates the deployment reference link.
documentation/​content/​en/​book/​06-deploying-packages/​_index.md Updates deployment and annotation reference links.
documentation/​content/​en/​book/​05-developing-functions/​_index.md Updates the annotation reference link.
documentation/​content/​en/​book/​04-using-functions/​_index.md Updates function and annotation reference links.
documentation/​content/​en/​book/​03-packages/​_index.md Updates package command reference links.
documentation/​content/​en/​book/​02-concepts/​_index.md Updates CLI and annotation reference links.
documentation/​content/​en/​book/​01-getting-started/​_index.md Updates function command reference links.
documentation/​content/​en/​_index.md Changes homepage reference-link selection.
documentation/​assets/​scss/​_sidebar-left.scss Updates the sidebar icon font and weight.
cli/​main.go Points documentation generation at relocated sources.
AGENTS.md Updates documentation paths in contributor guidance.

Review effort: Balanced


To get familiar with kpt, the best way to start is with the first 4 chapters of the kpt [Book]({{% relref "book" %}}).
Furthermore it is useful to check the [references]({{% relref "reference" %}}) and the catalog of [selected krm functions](https://catalog.kpt.dev).
Furthermore it is useful to check the [references]({{ with or (site.GetPage "/documentation/6-references") (site.GetPage "/reference") }}{{ .RelPermalink }}{{ end }}) and the catalog of [selected krm functions](https://catalog.kpt.dev).
Comment on lines +4 to +5
weight: 1
list_pages: true
Comment on lines +42 to +43
$SWAGGER_CMD generate spec -m -w api/kptfile/v1 -o documentation/content/en/documentation/6-references/schema/kptfile/kptfile.yaml
$SWAGGER_CMD generate spec -m -w api/kptfile/v1 -o documentation/content/en/documentation/6-references/schema/kptfile/kptfile.json
@sonarqubecloud

Copy link
Copy Markdown

Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>
Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Restructure documentation to follow best practices

2 participants