feat(www): Heading ids are hierarchical (#814)

Allows for better, nicer visual presentation of the headings while still maintaining very meaningful and stable anchors.

packages/www/build/md/rehype-hierarchical-slugs.js

@@ -0,0 +1,37 @@
+import ghSlugger from "github-slugger";
+import { hasProperty } from "hast-util-has-property";
+import { heading } from "hast-util-heading";
+import { headingRank } from "hast-util-heading-rank";
+import { toString } from "hast-util-to-string";
+import { visit } from "unist-util-visit";
+
+const { slug : slugger } = ghSlugger;
+
+export default function rehypeHierarchicalSlug() {
+ return (tree) => {
+ const slugs = [];
+
+ visit(tree, "element", (node) => {
+ if(!heading(node) || !node.properties || hasProperty(node, "id")) {
+ return;
+ }
+
+ const rank = headingRank(node);
+ const slug = slugger(toString(node));
+
+ let last = slugs[slugs.length - 1];
+
+ while(last && last.rank >= rank) {
+ slugs.pop();
+
+ last = slugs[slugs.length - 1];
+ }
+
+ if(rank > 1) {
+ slugs.push({ rank, slug });
+ }
+
+ node.properties.id = slugs.map(({ slug : s }) => s).join("-");
+ });
+ };
+}

packages/www/build/md/remark-import.js

@@ -48,6 +48,8 @@ const remarkImport = (options = false) => {
  parent[i] = root[i];
  }
 
+ parent.type = "parent";
+
  return CONTINUE;
  });
 

packages/www/build/vite-md.js

@@ -3,12 +3,12 @@ import remarkParse from "remark-parse";
 import { default as remarkRehype, defaultHandlers } from "remark-rehype";
 import rehypeAutolinkHeadings from "rehype-autolink-headings";
 import rehypeFormat from "rehype-format";
-import rehypeSlug from "rehype-slug";
 import rehypeStringify from "rehype-stringify";
 import rehypeTableOfContents from "rehype-toc";
 
 import remarkImport from "./md/remark-import.js";
 import rehypeCode from "./md/rehype-code.js";
+import rehypeHierarchicalSlugs from "./md/rehype-hierarchical-slugs.js";
 
 const ESCAPES = new Map([
  [ "`", "\\`" ],
@@ -33,7 +33,7 @@ export default () => {
  code : rehypeCode,
  },
  })
- .use(rehypeSlug)
+ .use(rehypeHierarchicalSlugs)
  .freeze();
 
  const later = [

packages/www/package.json

@@ -39,12 +39,16 @@
  "@sveltejs/kit": "^1.0.0-next.256",
  "codemirror": "^5.65.1",
  "debounce": "^1.2.1",
+ "github-slugger": "^1.4.0",
+ "hast-util-has-property": "^2.0.0",
+ "hast-util-heading": "^2.0.0",
+ "hast-util-heading-rank": "^2.1.0",
+ "hast-util-to-string": "^2.0.0",
  "hastscript": "^7.0.2",
  "lznext": "^0.1.0",
  "postcss-nested": "^5.0.6",
  "rehype-autolink-headings": "^6.1.1",
  "rehype-format": "^4.0.1",
- "rehype-slug": "^5.0.1",
  "rehype-stringify": "^9.0.2",
  "rehype-toc": "^3.0.2",
  "remark-parse": "^10.0.1",

packages/www/src/routes/api/_content/extending-after.md

@@ -1,4 +1,4 @@
-### `after` hook
+### `after`
 
 The `after` hook is run once the output location for the CSS is known, but before all the files are combined. By default it will run [`postcss-url`](https://github.com/postcss/postcss-url) to rebase file references based on the final output location, but this can be disabled using the [`rewrite`](#rewrite) option.
 
@@ -13,7 +13,7 @@ Since all manipulations on the file are complete at this point it is a good plac
 }
 ```
 
-#### Using the `after` hook
+#### Usage
 
 Specify an array of PostCSS plugins to be run after files are processed, but before they are combined. Plugin will be passed a `to` and `from` option.
 

packages/www/src/routes/api/_content/extending-before.md

@@ -1,9 +1,9 @@
-### `before` hook
+### `before`
 
 The `before` hook is run before a CSS file is ever processed by `modular-css`, so it provides access to rewrite files if they aren't actually CSS or contain non-standard syntax. Plugins like [`postcss-nested`](https://github.com/postcss/postcss-nested) go well here.
 
 
-#### Using the `before` hook
+#### Usage
 
 Specify an array of PostCSS plugins to be run against each file before it is processed. Plugin will be passed a `from` option.
 

packages/www/src/routes/api/_content/extending-done.md

@@ -1,8 +1,8 @@
-### `done` hook
+### `done`
 
 The `done` hook is run after all of the constituent files are combined into a single stylesheet. This makes it a good place to add tools like [`cssnano`](http://cssnano.co/) that need access to the entire stylesheet to be able to accurately optimize the CSS.
 
-#### Using the `done` hook
+#### Usage
 
 Specify an array of PostCSS plugins to be run against the complete combined CSS. Plugin will be passed a `to` option.