fix: improve documentation links and consistency in Quick Start guide#288
fix: improve documentation links and consistency in Quick Start guide#288shubhtrek wants to merge 2 commits intokmesh-net:mainfrom
Conversation
Signed-off-by: Shubh Pingale <135618936+shubhtrek@users.noreply.github.com>
✅ Deploy Preview for kmesh-net ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
[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 |
Signed-off-by: Shubh Pingale <135618936+shubhtrek@users.noreply.github.com> Esc :wq Enter
![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 updates the community meeting frequency to weekly and improves the documentation by fixing internal links, correcting grammar, and standardizing the capitalization of 'Istio'. It also simplifies the installation commands for Gateway API CRDs by removing specific commit references. Feedback includes a recommendation to use relative .md file paths for Docusaurus links, ensuring consistent capitalization of 'Istio' throughout the quick-start guide, and reverting platform-specific changes in yarn.lock that could break non-Windows builds.
| ## Preparation | ||
|
|
||
| Kmesh needs to run on a Kubernetes cluster. Kubernetes 1.26+ are currently supported. We recommend using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) to quickly provide a Kubernetes cluster (We provide a [document](develop-with-kind/) for developing and deploying Kmesh using kind). Of course, you can also use [minikube](https://minikube.sigs.k8s.io/docs/) and other ways to create Kubernetes clusters. | ||
| Kmesh needs to run on a Kubernetes cluster. Kubernetes 1.26+ are currently supported. We recommend using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) to quickly provide a Kubernetes cluster (We provide a [document](/docs/setup/develop-with-kind/) for developing and deploying Kmesh using kind). Of course, you can also use [minikube](https://minikube.sigs.k8s.io/docs/) and other ways to create Kubernetes clusters. |
There was a problem hiding this comment.
In Docusaurus, it is recommended to use relative paths to .md files for internal links (e.g., [document](./develop-with-kind.md)). This ensures that links are validated at build time and remain portable if the documentation structure changes or if the site is hosted at a subpath.
| Kmesh needs to run on a Kubernetes cluster. Kubernetes 1.26+ are currently supported. We recommend using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) to quickly provide a Kubernetes cluster (We provide a [document](/docs/setup/develop-with-kind/) for developing and deploying Kmesh using kind). Of course, you can also use [minikube](https://minikube.sigs.k8s.io/docs/) and other ways to create Kubernetes clusters. | |
| Kmesh needs to run on a Kubernetes cluster. Kubernetes 1.26+ are currently supported. We recommend using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) to quickly provide a Kubernetes cluster (We provide a [document](./develop-with-kind.md) for developing and deploying Kmesh using kind). Of course, you can also use [minikube](https://minikube.sigs.k8s.io/docs/) and other ways to create Kubernetes clusters. |
References
- Use relative file paths for internal documentation links to ensure build-time validation and portability.
| Kmesh needs to run on a Kubernetes cluster. Kubernetes 1.26+ are currently supported. We recommend using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) to quickly provide a Kubernetes cluster (We provide a [document](/docs/setup/develop-with-kind/) for developing and deploying Kmesh using kind). Of course, you can also use [minikube](https://minikube.sigs.k8s.io/docs/) and other ways to create Kubernetes clusters. | ||
|
|
||
| Currently, Kmesh makes use of [istio](https://istio.io/) as its control plane. Before installing Kmesh, please install the Istio control plane. We recommend installing istio ambient mode because Kmesh `dual-engine` mode need it. For details, see [ambient mode istio](https://istio.io/latest/docs/ops/ambient/getting-started/). | ||
| Currently, Kmesh makes use of [istio](https://istio.io/) as its control plane. Before installing Kmesh, please install the Istio control plane. We recommend installing Istio ambient mode because Kmesh `dual-engine` mode needs it. For details, see [ambient mode Istio](https://istio.io/latest/docs/ops/ambient/getting-started/). |
There was a problem hiding this comment.
The first occurrence of 'istio' in this line should be capitalized as 'Istio' for consistency with the rest of the sentence and the PR's stated goal of fixing naming consistency.
| Currently, Kmesh makes use of [istio](https://istio.io/) as its control plane. Before installing Kmesh, please install the Istio control plane. We recommend installing Istio ambient mode because Kmesh `dual-engine` mode needs it. For details, see [ambient mode Istio](https://istio.io/latest/docs/ops/ambient/getting-started/). | |
| Currently, Kmesh makes use of [Istio](https://istio.io/) as its control plane. Before installing Kmesh, please install the Istio control plane. We recommend installing Istio ambient mode because Kmesh `dual-engine` mode needs it. For details, see [ambient mode Istio](https://istio.io/latest/docs/ops/ambient/getting-started/). |
References
- Maintain consistent capitalization for product names like Istio throughout the documentation.
| ### Only install Istiod | ||
|
|
||
| Installing ambient mode istio by above steps will install additional istio components. | ||
| Installing ambient mode istio by above steps will install additional Istio components. |
There was a problem hiding this comment.
The word 'istio' should be capitalized as 'Istio' here to maintain consistency throughout the document.
| Installing ambient mode istio by above steps will install additional Istio components. | |
| Installing ambient mode Istio by above steps will install additional Istio components. |
References
- Maintain consistent capitalization for product names like Istio throughout the documentation.
| "@node-rs/jieba-win32-x64-msvc@2.0.1": | ||
| version "2.0.1" | ||
| resolved "https://registry.npmjs.org/@node-rs/jieba-darwin-arm64/-/jieba-darwin-arm64-2.0.1.tgz" | ||
| integrity sha512-10+nwGQ6KzXXJlIL/sELA6Fi6m7eJ7xJksBiKuw1kxKUgaJwtVfAG0iqRF+NRQv0Sdq7r3k5ew9K9y0+IYaEcA== | ||
| resolved "https://registry.npmjs.org/@node-rs/jieba-win32-x64-msvc/-/jieba-win32-x64-msvc-2.0.1.tgz" | ||
| integrity sha512-LDOyo2/2CO8UnpSGLJdgqtH8mOnsABPhNxkfIky7UT9cyLEzOaU44nbA5YzPGpBI3qzMbWcwJYQsjBcgK2VqAg== |
There was a problem hiding this comment.
The yarn.lock file has been modified to replace Darwin (macOS) dependencies with Windows-specific ones. This typically occurs when the lockfile is updated on a Windows machine without cross-platform support configured. This change will break the build for macOS users and should be reverted. Unrelated lockfile changes should generally be avoided in documentation PRs.
References
- Avoid committing platform-specific lockfile changes that prune dependencies for other supported operating systems.
There was a problem hiding this comment.
Pull request overview
This PR updates website documentation to make the Quick Start and contributor docs more consistent and easier to maintain, mainly by adjusting links, wording, and referenced setup commands.
Changes:
- Updated Quick Start links and wording around kind/Istio setup.
- Replaced pinned Gateway API CRD references in Quick Start commands.
- Changed community meeting frequency text and included unrelated lockfile updates.
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
yarn.lock |
Modifies platform-specific lockfile entries for optional native packages. |
docs/setup/quick-start.md |
Updates setup links, Istio wording, and Gateway API CRD install/cleanup commands. |
docs/community/contribute.md |
Changes the documented community meeting cadence. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Kmesh needs to run on a Kubernetes cluster. Kubernetes 1.26+ are currently supported. We recommend using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) to quickly provide a Kubernetes cluster (We provide a [document](/docs/setup/develop-with-kind/) for developing and deploying Kmesh using kind). Of course, you can also use [minikube](https://minikube.sigs.k8s.io/docs/) and other ways to create Kubernetes clusters. | ||
|
|
||
| Currently, Kmesh makes use of [istio](https://istio.io/) as its control plane. Before installing Kmesh, please install the Istio control plane. We recommend installing istio ambient mode because Kmesh `dual-engine` mode need it. For details, see [ambient mode istio](https://istio.io/latest/docs/ops/ambient/getting-started/). | ||
| Currently, Kmesh makes use of [istio](https://istio.io/) as its control plane. Before installing Kmesh, please install the Istio control plane. We recommend installing Istio ambient mode because Kmesh `dual-engine` mode needs it. For details, see [ambient mode Istio](https://istio.io/latest/docs/ops/ambient/getting-started/). |
| ### Only install Istiod | ||
|
|
||
| Installing ambient mode istio by above steps will install additional istio components. | ||
| Installing ambient mode istio by above steps will install additional Istio components. |
| ```shell | ||
| kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ | ||
| { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } | ||
| { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental" | kubectl apply -f -; } |
| ```shell | ||
| kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ | ||
| { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } | ||
| { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental" | kubectl apply -f -; } |
|
|
||
| ```shell | ||
| kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl delete -f - | ||
| kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental" | kubectl delete -f - |
Summary
This PR improves the reliability and consistency of the Quick Start documentation.
Changes
Impact
These changes reduce the risk of outdated references and improve readability.
Note
I’d like to work on similar documentation improvements if needed.
Fixes #280