You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/style-guide/how-we-docs/links.mdx
+13-4Lines changed: 13 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ meta:
5
5
title: Links | How we docs
6
6
---
7
7
8
-
import { Render } from"~/components";
8
+
import { GitHubCode, Render } from"~/components";
9
9
10
10
Though [links](/style-guide/documentation-content-strategy/component-attributes/links/) are an important part of documentation, they also have their own maintenance cost.
11
11
@@ -40,9 +40,18 @@ Of these three [link types](#link-types), only **Internal** links:
40
40
- Universally lead to a bad customer experience (a `404` page).
41
41
- Are easily auditable within the current context.
42
42
43
-
For these reasons, we choose to **fail** a build based on broken internal links. For our implementation, we rely on the Starlight link validator plugin.
43
+
For these reasons, we choose to **fail** a build based on broken internal links. For our implementation, we rely on the [Starlight link validator plugin](https://github.com/HiDeoo/starlight-links-validator).
44
44
45
-
{/* Insert reference to astro.config.ts + links to starlight link plugin + CI build step */}
45
+
<GitHubCode
46
+
repo="cloudflare/cloudflare-docs"
47
+
file="astro.config.ts"
48
+
commit="aaacc3c3c2a7517ee307ddfc56962cbea9847202"
49
+
lang="ts"
50
+
lines="129-153"
51
+
code={{ title: "astro.config.ts" }}
52
+
/>
53
+
54
+
Whether or not we run the link validation depends an environmental variable that we set in our [CI build process](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/ci.yml#L52).
46
55
47
56
We also make two intentional decisions about this link auditing:
48
57
@@ -59,4 +68,4 @@ We use an external SEO tool to help flag these broken external links for us, add
59
68
60
69
Anchor links do not have as dramatic as consequences of being wrong as internal links. If you have a broken anchor link, a customer will either need to manually scroll to the header or - in some cases - go to another page.
61
70
62
-
Because of these characteristics, we run periodic, background checks to flag broken anchor links, using the `htmltest` library.
71
+
Because of these characteristics, we run [periodic, background checks](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/anchor-link-audit.yml) to flag broken anchor links, using the `htmltest` library.
0 commit comments