Skip to content

Commit a16cad7

Browse files
committed
Finish adding in links
1 parent 3b48e0e commit a16cad7

File tree

1 file changed

+13
-4
lines changed
  • src/content/docs/style-guide/how-we-docs

1 file changed

+13
-4
lines changed

src/content/docs/style-guide/how-we-docs/links.mdx

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ meta:
55
title: Links | How we docs
66
---
77

8-
import { Render } from "~/components";
8+
import { GitHubCode, Render } from "~/components";
99

1010
Though [links](/style-guide/documentation-content-strategy/component-attributes/links/) are an important part of documentation, they also have their own maintenance cost.
1111

@@ -40,9 +40,18 @@ Of these three [link types](#link-types), only **Internal** links:
4040
- Universally lead to a bad customer experience (a `404` page).
4141
- Are easily auditable within the current context.
4242

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).
4444

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).
4655

4756
We also make two intentional decisions about this link auditing:
4857

@@ -59,4 +68,4 @@ We use an external SEO tool to help flag these broken external links for us, add
5968

6069
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.
6170

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

Comments
 (0)