docs: restructure documentation hierarchy#791
Conversation
kubeedge-bot
added
do-not-merge/work-in-progress
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
Welcome @Gurkaran18! It looks like this is your first PR to kubeedge/website 🎉 |
kubeedge-bot
added
the
size/L
Gurkaran18
force-pushed
the
docs/restructure-issue-1498
branch
from
31f5f04 to
a0f66c6
Compare
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request restructures the KubeEdge documentation by migrating files into a more organized directory hierarchy and updating internal links and the sidebar configuration. Feedback focuses on fixing a potentially broken link in the sidebar caused by a custom document ID, removing the migration script to prevent repository clutter, and improving the safety of the script's git operations.
| items: [ | ||
| 'developer-guide/dmi', | ||
| 'developer-guide/mapper-framework', | ||
| 'developer-guide/mappers/index', |
There was a problem hiding this comment.
The document docs/developer-guide/mappers/index.md defines a custom id: mappers-index in its frontmatter. In Docusaurus, when a custom ID is provided, the resulting Doc ID is the directory path joined with that custom ID (e.g., developer-guide/mappers/mappers-index). The current sidebar entry 'developer-guide/mappers/index' will fail to resolve, likely breaking this link in the sidebar.
| 'developer-guide/mappers/index', | |
| 'developer-guide/mappers/mappers-index', |
| @@ -0,0 +1,108 @@ | |||
| #!/bin/bash | |||
There was a problem hiding this comment.
This script appears to be a one-off migration tool used to perform the documentation restructuring. Since the changes (moved files and updated links) are already included in this pull request, committing the script to the repository's root directory is unnecessary and adds clutter to the codebase. It is recommended to remove this file before merging.
| rm -f docs/advanced/_category_.json | ||
| rm -f docs/developer/_category_.json | ||
| rm -f docs/faq/_category_.json | ||
| git add -A # stage the removals |
There was a problem hiding this comment.
Using git add -A in a script can be risky as it stages all changes in the working directory, including untracked files that may not be intended for the commit. It is safer to use a more specific command like git add docs/ to ensure only documentation changes are staged.
| git add -A # stage the removals | |
| git add docs/ |
Gurkaran18
changed the title
kubeedge-bot
removed
the
do-not-merge/invalid-commit-message
Reorganize the KubeEdge documentation to establish a clean separation between user-facing and developer-facing content, as proposed in Issue 1498. Changes: - docs/setup/ -> docs/user-guide/getting-started/ and configuration/ - docs/advanced/ -> docs/user-guide/features/ and troubleshooting/ - docs/developer/ -> docs/developer-guide/ - docs/faq/ -> docs/reference/faq/ - sidebars.js: replace autogenerated sidebar with explicit manual hierarchy - Fix all internal relative links broken by the above renames (9 files) - Remove stale _category_.json files from vacated directories Signed-off-by: Gurkaran Singh <gurkaranbirsingh@example.com>
- Switch sidebars.js from explicit doc IDs to autogenerated per-directory approach which is the correct Docusaurus v2/v3 pattern - Add _category_.json files to all new directories to control sidebar labels and ordering: - user-guide/ (position 2) - user-guide/getting-started/ (position 1) - user-guide/configuration/ (position 2) - user-guide/features/ (position 3) - user-guide/troubleshooting/ (position 4) - developer-guide/ (position 3) - developer-guide/mappers/ (position 6) - developer-guide/test/ (position 7) - reference/ and reference/faq/ (position 1) Signed-off-by: Gurkaran Singh <gurkaranbirsingh@example.com>
Gurkaran18
force-pushed
the
docs/restructure-issue-1498
branch
from
e8824e9 to
87fedde
Compare
- Fixed remaining broken relative links in English docs (install-with-binary, metrics, upgrade, mapper) - Migrated Chinese translation directory structure (i18n/zh/.../current/) to match the new English hierarchy - Fixed 12 broken relative links within the Chinese translation files Signed-off-by: Gurkaran Singh <gurkaranbirsingh@example.com>
kubeedge-bot
added
size/XXL
kubeedge-bot
removed
the
do-not-merge/work-in-progress
2 participants
What kind of change does this PR introduce?
docs update
What is the current behavior?
The existing documentation structure mixes user-facing content with
developer-facing content under vague directories like
docs/advanced/and
docs/setup/. The sidebar is fully auto-generated from thefilesystem, meaning there is no intentional information architecture.
This makes the docs hard to navigate for both new users and contributors.
Fixes: kubeedge/kubeedge#1498
What is the new behavior?
Reorganizes the
kubeedge/websitedocs into a clean, intentionalhierarchy with a clear separation between user and developer content:
docs/setup/→docs/user-guide/getting-started/(install guides)→
docs/user-guide/configuration/(config & upgrade)docs/advanced/→docs/user-guide/features/(feature guides)→
docs/user-guide/troubleshooting/(debug guide)docs/developer/→docs/developer-guide/(all dev content)docs/faq/→docs/reference/faq/(reference section)sidebars.js: Replaces auto-generated sidebar with an explicit manualhierarchy enforcing this order:
Welcome → User Guide → Developer Guide → Concepts → Reference → Community
_category_.jsonfiles from vacated directories.Does this PR introduce a breaking change?
No. This is a pure documentation restructuring. No Go source code,
APIs, or configuration schemas are modified.
Please check if the PR fulfills these requirements
Other information
This work implements the document architecture proposed by maintainer
daixiang0in the issue thread (Nov 26, 2020 comment). The issue hasbeen open since 2020 and was marked
lifecycle/frozento prevent thestale bot from closing it, indicating maintainers consider this high
priority.