fix: fixes various issues with IDs and links with HTML embedded in Markdown

Author: HiDeoo

example/package.json

@@ -13,8 +13,8 @@
     "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0"
   },
   "dependencies": {
-    "@astrojs/starlight": "0.2.0",
-    "astro": "2.6.6",
+    "@astrojs/starlight": "0.7.2",
+    "astro": "2.10.9",
     "starlight-links-validator": "workspace:*"
   },
   "engines": {

example/src/content/docs/guides/example.md

@@ -16,3 +16,17 @@ Writing a good guide requires thinking about what your users are trying to do.
 - Check the [links](#links) section of this guide
 - Check the [reference](/reference/example/#further-reading) page
 - Check the [links](/guides/links/) page
+
+<div id="aBlock">
+some content
+
+some content
+
+some content
+
+some content
+
+  <a href="#anotherBlock">
+    test
+  </a>
+</div>

packages/starlight-links-validator/libs/remark.ts

@@ -3,7 +3,11 @@ import 'mdast-util-mdx-jsx'
 import nodePath from 'node:path'
 
 import { slug } from 'github-slugger'
+import type { Nodes } from 'hast'
+import { fromHtml } from 'hast-util-from-html'
+import { hasProperty } from 'hast-util-has-property'
 import type { Root } from 'mdast'
+import type { MdxJsxAttribute, MdxJsxExpressionAttribute } from 'mdast-util-mdx-jsx'
 import { toString } from 'mdast-util-to-string'
 import type { Plugin } from 'unified'
 import { visit } from 'unist-util-visit'
@@ -20,7 +24,7 @@ export const remarkStarlightLinksValidator: Plugin<[], Root> = function () {
     const fileHeadings: string[] = []
     const fileLinks: string[] = []
 
-    visit(tree, ['heading', 'link', 'mdxJsxFlowElement'], (node) => {
+    visit(tree, ['heading', 'html', 'link', 'mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
       // https://github.com/syntax-tree/mdast#nodes
       // https://github.com/syntax-tree/mdast-util-mdx-jsx#nodes
       switch (node.type) {
@@ -43,6 +47,12 @@ export const remarkStarlightLinksValidator: Plugin<[], Root> = function () {
           break
         }
         case 'mdxJsxFlowElement': {
+          for (const attribute of node.attributes) {
+            if (isMdxIdAttribute(attribute)) {
+              fileHeadings.push(attribute.value)
+            }
+          }
+
           if (node.name !== 'a') {
             break
           }
@@ -61,6 +71,37 @@ export const remarkStarlightLinksValidator: Plugin<[], Root> = function () {
             }
           }
 
+          break
+        }
+        case 'mdxJsxTextElement': {
+          for (const attribute of node.attributes) {
+            if (isMdxIdAttribute(attribute)) {
+              fileHeadings.push(attribute.value)
+            }
+          }
+
+          break
+        }
+        case 'html': {
+          const htmlTree = fromHtml(node.value, { fragment: true })
+
+          // @ts-expect-error - https://github.com/microsoft/TypeScript/issues/51188
+          visit(htmlTree, (htmlNode: Nodes) => {
+            if (hasProperty(htmlNode, 'id') && typeof htmlNode.properties.id === 'string') {
+              fileHeadings.push(htmlNode.properties.id)
+            }
+
+            if (
+              htmlNode.type === 'element' &&
+              htmlNode.tagName === 'a' &&
+              hasProperty(htmlNode, 'href') &&
+              typeof htmlNode.properties.href === 'string' &&
+              isInternalLink(htmlNode.properties.href)
+            ) {
+              fileLinks.push(htmlNode.properties.href)
+            }
+          })
+
           break
         }
       }
@@ -91,5 +132,15 @@ function normalizeFilePath(filePath?: string) {
     .replace(/\/?$/, '/')
 }
 
+function isMdxIdAttribute(attribute: MdxJsxAttribute | MdxJsxExpressionAttribute): attribute is MdxIdAttribute {
+  return attribute.type === 'mdxJsxAttribute' && attribute.name === 'id' && typeof attribute.value === 'string'
+}
+
 export type Headings = Map<string, string[]>
 export type Links = Map<string, string[]>
+
+interface MdxIdAttribute {
+  name: 'id'
+  type: 'mdxJsxAttribute'
+  value: string
+}

packages/starlight-links-validator/package.json

@@ -15,13 +15,17 @@
   },
   "dependencies": {
     "github-slugger": "2.0.0",
+    "hast-util-from-html": "2.0.1",
+    "hast-util-has-property": "3.0.0",
     "kleur": "4.1.5",
     "mdast-util-to-string": "3.2.0",
     "unist-util-visit": "4.1.2"
   },
   "devDependencies": {
+    "@types/hast": "3.0.0",
     "@types/mdast": "3.0.11",
     "@types/node": "18.16.18",
+    "astro": "2.10.9",
     "mdast-util-mdx-jsx": "2.1.4",
     "typescript": "5.1.3",
     "unified": "10.1.2",

packages/starlight-links-validator/tests/fixtures/base/astro.config.ts

@@ -1,7 +1,7 @@
 import starlight from '@astrojs/starlight'
 import { defineConfig } from 'astro/config'
 
-import starlightLinksValidator from '../../src'
+import starlightLinksValidator from '../..'
 
 export default defineConfig({
   integrations: [

packages/starlight-links-validator/tests/fixtures/with-invalid-links/src/content/docs/guides/example.mdx

@@ -17,3 +17,17 @@ import { Card, CardGrid } from '@astrojs/starlight/components'
 - [Link to invalid anchor in another page](/unknown/#links)
 
 <a href="/unknown">HTML link to unknown page</a>
+
+<div id="aBlock">
+some content
+
+some content
+
+some content
+
+some content
+
+  <a href="#anotherBlock">
+    test
+  </a>
+</div>

packages/starlight-links-validator/tests/fixtures/with-invalid-links/src/content/docs/test.md

@@ -20,3 +20,17 @@ title: Test
 - [Link to invalid anchor in this page](#links)
 - [Link to valid anchor in another MDX page](/guides/example/#some-links)
 - [Link to invalid anchor in another MDX page](/guides/example/#links)
+
+<div id="aDiv">
+some content
+
+some content
+
+some content
+
+some content
+
+  <a href="#anotherDiv">
+    test
+  </a>
+</div>

packages/starlight-links-validator/tests/fixtures/with-valid-links/src/content/docs/guides/example.mdx

@@ -16,3 +16,21 @@ import { Card, CardGrid } from '@astrojs/starlight/components'
 - [Link to anchor in the same page](#some-links)
 
 <a href="/test">HTML link to another page</a>
+
+<div id="aBlock">
+some content
+
+some content
+
+some <span id="aText">other</span> content
+
+some content
+
+<a href="#aBlock">test block</a>
+
+some content
+
+  <a href="#aText">
+    test text
+  </a>
+</div>

packages/starlight-links-validator/tests/fixtures/with-valid-links/src/content/docs/test.md

@@ -7,3 +7,17 @@ title: Test
 Some content.
 
 - [Link to same page](/test)
+
+<div id="aDiv">
+some content
+
+some content
+
+some content
+
+some content
+
+  <a href="#aDiv">
+    test
+  </a>
+</div>

packages/starlight-links-validator/tests/validation.test.ts

@@ -16,7 +16,7 @@ test('should not build with invalid links', async () => {
   try {
     await loadFixture('with-invalid-links')
   } catch (error) {
-    expect(error).toMatch(/Found 10 invalid links in 2 files./)
+    expect(error).toMatch(/Found 12 invalid links in 2 files./)
 
     expect(error).toMatch(
       new RegExp(`▶ test/
@@ -26,14 +26,16 @@ test('should not build with invalid links', async () => {
   ├─ /unknown#title
   ├─ /unknown/#title
   ├─ #links
-  └─ /guides/example/#links`)
+  ├─ /guides/example/#links
+  └─ #anotherDiv`)
     )
 
     expect(error).toMatch(
       new RegExp(`▶ guides/example/
   ├─ #links
   ├─ /unknown/#links
-  └─ /unknown`)
+  ├─ /unknown
+  └─ #anotherBlock`)
     )
   }
 })