docs: add heading anchors (#814)

* docs: add heading anchors * refactor: remove hastscript from docs deps --------- Co-authored-by: Odil Abdulloyev <abdulloyevodil@mail.ru>
artalar · Apr 17, 2024 · 1f8e18c · 1f8e18c
1 parent 60527d9
commit 1f8e18c
Show file tree

Hide file tree

Showing 5 changed files with 151 additions and 22 deletions.
diff --git a/docs/.astro/types.d.ts b/docs/.astro/types.d.ts
@@ -440,5 +440,5 @@ declare module 'astro:content' {
 
 	type AnyEntryMap = ContentEntryMap & DataEntryMap;
 
-	export type ContentConfig = typeof import("../src/content/config.js");
+	export type ContentConfig = typeof import("./../src/content/config.js");
 }
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -2,6 +2,9 @@ import { $ } from 'zx'
 import { defineConfig } from 'astro/config'
 import starlight from '@astrojs/starlight'
 import rehypeExternalLinks from 'rehype-external-links'
+import rehypeAutolinkHeadings from 'rehype-autolink-headings'
+import rehypeSlug from 'rehype-slug'
+
 if (!process.env.VERCEL) await $`tsx sync-readme-to-pages.ts`
 
 // https://astro.build/config
@@ -100,6 +103,22 @@ export default defineConfig({
           target: '_blank',
         },
       ],
+      rehypeSlug,
+      [
+        rehypeAutolinkHeadings,
+        {
+          properties: { class: 'anchor-link' },
+          behavior: 'after',
+          content: () => [{ type: 'text', value: '#' }],
+          group: ({ tagName }) => ({
+            type: 'element',
+            tagName: 'div',
+            properties: {
+              class: `heading-wrapper level-${tagName}`,
+            },
+          }),
+        },
+      ],
     ],
   },
 })
diff --git a/docs/package-lock.json b/docs/package-lock.json
diff --git a/docs/package.json b/docs/package.json
@@ -22,10 +22,12 @@
   },
   "devDependencies": {
     "@astrojs/starlight": "^0.21.2",
-    "zx": "^7.2.3",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-external-links": "^3.0.0",
+    "rehype-slug": "^6.0.0",
+    "sharp": "^0.33.3",
     "tsx": "^4.7.1",
     "typescript": "^5.4.3",
-    "rehype-external-links": "^3.0.0",
-    "sharp": "^0.33.3"
+    "zx": "^7.2.3"
   }
 }
diff --git a/docs/src/styles/custom.css b/docs/src/styles/custom.css
@@ -11,6 +11,9 @@
   --sl-color-gray-5: #35354c;
   --sl-color-gray-6: #24243a;
   --sl-color-black: #171721;
+
+  /* heading anchor icon size */
+  --icon-size: 0.75em;
 }
 /* Light mode colors. */
 :root[data-theme='light'] {
@@ -51,4 +54,42 @@ main::before {
 .external-link-icon {
   text-decoration: none;
   display: inline-block;
-}
+}
+
+.heading-wrapper > :is(h2, h3, h4, h5, h6) {
+  display: inline;
+}
+
+.heading-wrapper .anchor-link {
+  opacity: 0;
+  margin-inline-start: calc(var(--icon-size) / 2);
+  text-decoration: none;
+  &:hover {
+    text-decoration: underline;
+  }
+}
+
+.heading-wrapper:hover .anchor-link,
+.heading-wrapper .anchor-link:focus {
+  opacity: 1;
+}
+
+.level-h2 {
+  font-size: var(--sl-text-h2);
+}
+
+.level-h3 {
+  font-size: var(--sl-text-h3);
+}
+
+.level-h4 {
+  font-size: var(--sl-text-h4);
+}
+
+.level-h5 {
+  font-size: var(--sl-text-h5);
+}
+
+.level-h6 {
+  font-size: var(--sl-text-h6);
+}