docs: fix 14 broken links and stale talm anchor across v1 docs#486
Merged
docs: fix 14 broken links and stale talm anchor across v1 docs#486
Conversation
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (11)
✅ Files skipped from review due to trivial changes (11)
📝 WalkthroughWalkthroughUpdated internal documentation link references across 11 files to use consistent absolute/versioned Hugo Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request standardizes internal documentation links by updating {{% ref %}} shortcode paths and correcting relative links across various guides. The feedback suggests further improving link reliability by replacing remaining raw markdown links with the {{% ref %}} shortcode, which provides build-time validation and ensures link consistency.
| ``` | ||
|
|
||
| Now follow **Get Started** guide starting from the [**Install Cozystack**](/docs/getting-started/install-cozystack) section, to continue the installation. | ||
| Now follow **Get Started** guide starting from the [**Install Cozystack**](/docs/v1/getting-started/install-cozystack) section, to continue the installation. |
Contributor
There was a problem hiding this comment.
Using the {{% ref %}} shortcode is preferred for internal links. It provides build-time validation and ensures the link remains correct even if the site's base URL or structure changes. This aligns with the PR's goal of preventing broken links.
Suggested change
| Now follow **Get Started** guide starting from the [**Install Cozystack**](/docs/v1/getting-started/install-cozystack) section, to continue the installation. | |
| Now follow **Get Started** guide starting from the [**Install Cozystack**]({{% ref "/docs/v1/getting-started/install-cozystack" %}}) section, to continue the installation. |
|
|
||
| {{% alert title="Troubleshooting" %}} | ||
| Troubleshooting advice can be found on our [Troubleshooting Cheatsheet](/docs/operations/troubleshooting/). | ||
| Troubleshooting advice can be found on our [Troubleshooting Cheatsheet](/docs/v1/operations/troubleshooting/). |
Contributor
There was a problem hiding this comment.
Using the {{% ref %}} shortcode is preferred for internal links to enable build-time validation and maintain consistency across the documentation.
Suggested change
| Troubleshooting advice can be found on our [Troubleshooting Cheatsheet](/docs/v1/operations/troubleshooting/). | |
| Troubleshooting advice can be found on our [Troubleshooting Cheatsheet]({{% ref "/docs/v1/operations/troubleshooting" %}}). |
|
|
||
| {{% alert color="info" %}} | ||
| **Optional**: If you want the dashboard to reach Keycloak via the internal cluster network instead of the external ingress, set `keycloakInternalUrl`. This is useful in environments with self-signed certificates or restricted external access. See [Self-Signed Certificates](../self-signed-certificates/) for details. | ||
| **Optional**: If you want the dashboard to reach Keycloak via the internal cluster network instead of the external ingress, set `keycloakInternalUrl`. This is useful in environments with self-signed certificates or restricted external access. See [Self-Signed Certificates](./self-signed-certificates/) for details. |
Contributor
There was a problem hiding this comment.
Using the {{% ref %}} shortcode for internal links is more robust than raw markdown links, as it allows Hugo to validate the target at build time.
Suggested change
| **Optional**: If you want the dashboard to reach Keycloak via the internal cluster network instead of the external ingress, set `keycloakInternalUrl`. This is useful in environments with self-signed certificates or restricted external access. See [Self-Signed Certificates](./self-signed-certificates/) for details. | |
| **Optional**: If you want the dashboard to reach Keycloak via the internal cluster network instead of the external ingress, set `keycloakInternalUrl`. This is useful in environments with self-signed certificates or restricted external access. See [Self-Signed Certificates]({{% ref "/docs/v1/operations/oidc/self-signed-certificates" %}}) for details. |
| ## Prerequisites | ||
|
|
||
| - Cozystack cluster with OIDC enabled (see [Enable OIDC Server](../enable_oidc/)) | ||
| - Cozystack cluster with OIDC enabled (see [Enable OIDC Server](./enable_oidc/)) |
Contributor
There was a problem hiding this comment.
Using the {{% ref %}} shortcode for internal links is more robust than raw markdown links, as it allows Hugo to validate the target at build time.
Suggested change
| - Cozystack cluster with OIDC enabled (see [Enable OIDC Server](./enable_oidc/)) | |
| - Cozystack cluster with OIDC enabled (see [Enable OIDC Server]({{% ref "/docs/v1/operations/oidc/enable_oidc" %}})) |
| - **Certificate not found**: Ensure the certificate file path in `extraVolumes` matches the path specified in `oidc-ca-file`. | ||
| - **Domain resolution fails**: Verify that `extraHostEntries` is correctly configured on all control plane nodes. | ||
| - **Authentication fails**: Check that the user exists in Keycloak and has the required group memberships (see [Users and Roles](../users_and_roles/)). | ||
| - **Authentication fails**: Check that the user exists in Keycloak and has the required group memberships (see [Users and Roles](./users_and_roles/)). |
Contributor
There was a problem hiding this comment.
Using the {{% ref %}} shortcode for internal links is more robust than raw markdown links, as it allows Hugo to validate the target at build time.
Suggested change
| - **Authentication fails**: Check that the user exists in Keycloak and has the required group memberships (see [Users and Roles](./users_and_roles/)). | |
| - **Authentication fails**: Check that the user exists in Keycloak and has the required group memberships (see [Users and Roles]({{% ref "/docs/v1/operations/oidc/users_and_roles" %}})). |
|
|
||
| To get started with customizing or creating your own instancetypes and preferences | ||
| see [DEVELOPMENT.md](./DEVELOPMENT.md). | ||
| see [Developer Guide](/docs/v1/development/). |
Contributor
There was a problem hiding this comment.
Using the {{% ref %}} shortcode for internal links is more robust than raw markdown links, as it allows Hugo to validate the target at build time.
Suggested change
| see [Developer Guide](/docs/v1/development/). | |
| see [Developer Guide]({{% ref "/docs/v1/development" %}}). |
lexfrei
force-pushed
the
docs/fix-broken-refs
branch
from
10d62db to
29110e8
Compare
Leading-slash ref issues in the v1.2 tree were already fixed by the v1.0/v1.1/v1.2 refactor. Six remaining broken links survived the refactor because they were plain markdown links, not ref shortcodes: - hetzner.md — stale anchor #1-initialize-cluster-configuration → #2 (talm.md grew a new "## 1. Install Dependencies" section ahead of "Initialize Cluster Configuration", which is now ## 2). - servers-com/_index.md — unversioned /docs/getting-started/... link wrapped in a ref shortcode and pointed at /docs/v1.2/. - operations/faq/_index.md — same fix for /docs/operations/... link → ref /docs/v1.2/operations/troubleshooting. - oidc/enable_oidc.md, oidc/self-signed-certificates.md — replaced Hugo-unfriendly relative paths (../sibling/) with absolute ref shortcodes so the build fails if the target is renamed. - virtualization/vm-instance.md — ./DEVELOPMENT.md pointed at a file that does not exist; replaced with ref to /docs/v1.2/development. Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Aleksei Sviridkin <f@lex.la>
lexfrei
force-pushed
the
docs/fix-broken-refs
branch
from
15663cb to
87c158f
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Fixes 14 broken links in the v1 docs tree found by an automated pass: static validation of every
{{% ref %}}/{{% relref %}}shortcode target plus a lychee offline check of raw markdown links. 11 files touched, two logical groups of fixes.Group 1 —
{{% ref %}}shortcodes written without a leading slash (8 fixes, 6 files):A ref written as
ref "docs/v1/foo"(no leading/) is treated by Hugo as relative to the calling page, so Hugo resolves it todocs/v1/docs/v1/foo, which never exists. The rest of the v1 docs use the absolute formref "/docs/v1/foo". Normalize the outliers:install/providers/hetzner.md— 2 refs (one also had a stale anchor, see below)operations/services/_index.md— 2 refsguides/concepts.md— 2 refsoperations/services/monitoring/dashboards.md— 3 refsoperations/services/monitoring/alerting.md— 1 refoperations/services/monitoring/logs.md— 3 refsStale anchor inside
hetzner.md: the Hetzner install guide linked readers attalm#1-initialize-cluster-configuration, but Talm's guide has since grown a new## 1. Install Dependenciessection ahead of "Initialize Cluster Configuration", which is now## 2.. Update the anchor to#2-initialize-cluster-configuration.Group 2 — plain markdown links (6 fixes, 5 files):
operations/oidc/enable_oidc.md→[Self-Signed Certificates](../self-signed-certificates/): resolves tooperations/self-signed-certificates(one directory above where the file lives). Target file isoperations/oidc/self-signed-certificates.md, so use./self-signed-certificates/.operations/oidc/self-signed-certificates.md→ two mirror-image breakages:../enable_oidc/and../users_and_roles/both point one level too high. Use./enable_oidc/and./users_and_roles/.virtualization/vm-instance.md→./DEVELOPMENT.mdis a dangling relative link to a file that does not exist incontent/. Replace with the real Developer Guide at/docs/v1/development/.operations/faq/_index.md→/docs/operations/troubleshooting/is missing the/v1/segment and points at a non-existent legacy path. Add/v1/.install/providers/servers-com/_index.md→/docs/getting-started/install-cozystackhas the same missing/v1/segment. Add/v1/.Why
All 14 are real broken links on the live site right now. None of them produce a Hugo build error (Hugo's default
refLinksErrorLeveliswarning, and plain markdown link resolution happens at browser time, not build time), which is why they accumulated unnoticed. Every broken link costs readers trust and routes them to 404s or to wrong pages.Verification
{{% ref %}}/{{% relref %}}target incontent/en/docs/v1/and tries to resolve it against the filesystem — after this PR it reports 0 missing targets (down from 8).lychee --offlineoncontent/en/docs/v1/**/*.mdbefore and after. False positives for/img/...absolute paths and for Hugo-routed absolute paths like/docs/v1/development/(where a page exists but lychee does not know Hugo's routing) were filtered manually by cross-checking each finding against the actual filesystem. After the fixes, the remaining lychee "errors" are all confirmed false positives (static asset paths and Hugo-routed pages that do exist).hugobuilds cleanly (440 pages, no ref warnings) both before and after.Out of scope
lycheealso flagged a large number of/img/...absolute image paths as broken, but those are all false positives —/img/is a static asset root, Hugo serves it viastatic/img/, and the rendered pages on the live site show the images correctly.markdownlintacross the v1 tree surfaced many style-only issues (MD030, MD012, MD033, MD034 bare URLs, MD040 missing code-block language) that are pre-existing and mostly in auto-generatedcontent/en/docs/v1/applications/*.mdfiles (which are regenerated from upstreamcozystack/cozystackREADMEs). Those should be fixed in the upstream READMEs, not here.Summary by CodeRabbit