Update docs layout (#97)

Author: stormwarning

.eslintrc.cjs

@@ -1,3 +1,6 @@
+// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+const path = require('node:path')
+
 /** @type {import('eslint').Linter.Config} */
 const config = {
 	extends: [
@@ -9,6 +12,9 @@ const config = {
 		node: true,
 	},
 	ignorePatterns: ['dist', '*.njk'],
+	parserOptions: {
+		project: [path.resolve(__dirname, 'tsconfig.json')],
+	},
 	rules: {
 		'@typescript-eslint/ban-types': 'off',
 		'@typescript-eslint/lines-between-class-members': 'off',

docs/eleventy.config.js

@@ -1,19 +1,16 @@
-/* eslint-disable @typescript-eslint/no-unsafe-call */
-
 import eleventyNavigationPlugin from '@11ty/eleventy-navigation'
 import eleventyRemark from '@fec/eleventy-plugin-remark'
-import dedent from 'dedent'
 import { rehype } from 'rehype'
 import rehypeAutolinkHeadings from 'rehype-autolink-headings'
 import rehypeSlug from 'rehype-slug'
-import { remark } from 'remark'
 import remarkDirective from 'remark-directive'
 
 import { remarkDirectives } from './remark/directives.js'
 import { remarkHeadings } from './remark/headings.js'
 import { remarkSample } from './remark/sample.js'
+import { rehypeTableOfContents } from './remark/table-of-contents.js'
 
-/** @param {import('@11ty/eleventy').UserConfig} eleventyConfig */
+/** @param {import('@11ty/eleventy/UserConfig').default} eleventyConfig */
 export default async function config(eleventyConfig) {
 	eleventyConfig.addPassthroughCopy({
 		'src/assets/fonts': './assets/fonts',
@@ -23,32 +20,6 @@ export default async function config(eleventyConfig) {
 	})
 	eleventyConfig.addPassthroughCopy({ 'src/public': '.' })
 
-	eleventyConfig.addPairedShortcode(
-		'navitem',
-		(content, url, isSelected, isInactive) => {
-			let tag = ''
-
-			if (isInactive) {
-				tag = `<span class="px-3 py-2 relative block text-grey-400">${content}</span>`
-			} else {
-				let linkClass = [
-					'px-3 py-2 transition-colors duration-200 relative block',
-					isSelected && 'text-sky-700',
-					!isSelected && 'hover:text-grey-900 text-grey-500',
-				].join(' ')
-
-				tag = dedent`<a class="${linkClass}" href="${url}">
-						<span class="rounded-md absolute inset-0 bg-sky-50 ${
-							!isSelected && 'opacity-0'
-						}"></span>
-						<span class="relative">${content}</span>
-					</a>`
-			}
-
-			return `<li>${tag}</li>`
-		},
-	)
-
 	eleventyConfig.addPlugin(eleventyNavigationPlugin)
 	eleventyConfig.addPlugin(eleventyRemark, {
 		plugins: [
@@ -62,14 +33,25 @@ export default async function config(eleventyConfig) {
 
 	eleventyConfig.addTransform(
 		'rehype',
-		/** @param {string} content */ async (content, outputPath) => {
+		/**
+		 * @param {string} content
+		 * @param {string} outputPath
+		 */
+		async (content, outputPath) => {
 			let newContent = content
 
 			if (outputPath?.endsWith('.html')) {
 				let result = await rehype()
 					.use(rehypeSlug)
 					.use(rehypeAutolinkHeadings, {
-						test: (element, index, parent) => parent.tagName !== 'nav',
+						test(element, index, parent) {
+							return (
+								parent?.type === 'element' &&
+								parent?.tagName !== 'nav' &&
+								element.tagName !== 'h1' &&
+								element.tagName !== 'h5'
+							)
+						},
 						properties: {
 							class:
 								'absolute ml-[-0.75em] md:ml-[-1em] pr-[0.5em] !no-underline !text-grey-400 opacity-0 group-hover:opacity-100',
@@ -88,6 +70,18 @@ export default async function config(eleventyConfig) {
 		},
 	)
 
+	eleventyConfig.addAsyncFilter(
+		'toc',
+		/** @param {string} content */ async (content) => {
+			let output = await rehype()
+				.data('settings', { fragment: true })
+				.use(rehypeSlug)
+				.use(rehypeTableOfContents)
+				.process(content)
+			return output.toString()
+		},
+	)
+
 	return {
 		dir: {
 			input: 'src',

docs/package.json

@@ -4,33 +4,44 @@
 	"private": true,
 	"type": "module",
 	"scripts": {
-		"build": "eleventy --config=eleventy.config.js",
-		"dev": "TAILWIND_MODE=watch eleventy --config=eleventy.config.js --serve"
+		"build": "run-s build:*",
+		"build:11ty": "npx @11ty/eleventy",
+		"build:css": "npx @tailwindcss/cli -i ./src/assets/main.css -o ./dist/assets/styles.css",
+		"build:old": "eleventy --config=eleventy.config.js",
+		"dev": "run-p start:*",
+		"dev:old": "TAILWIND_MODE=watch npx @11ty/eleventy --config=eleventy.config.js --serve",
+		"start:11ty": "npx @11ty/eleventy --serve --quiet",
+		"start:css": "npx @tailwindcss/cli -i ./src/assets/main.css -o ./dist/assets/styles.css --watch"
 	},
 	"devDependencies": {
-		"@11ty/eleventy": "3.0.0",
-		"@11ty/eleventy-navigation": "0.3.5",
-		"@11ty/eleventy-plugin-syntaxhighlight": "5.0.0",
+		"@11ty/eleventy": "3.1.2",
+		"@11ty/eleventy-navigation": "1.0.4",
 		"@fec/eleventy-plugin-remark": "4.0.0",
-		"@tailwindcss/typography": "0.5.2",
+		"@shikijs/transformers": "3.7.0",
+		"@tailwindcss/cli": "4.0.17",
+		"@tailwindcss/postcss": "4.0.17",
+		"@tailwindcss/typography": "0.5.16",
 		"@types/hast": "3.0.4",
 		"@types/mdast": "4.0.4",
 		"autoprefixer": "10.3.4",
 		"dedent": "1.5.3",
+		"hast-util-heading-rank": "3.0.0",
 		"hastscript": "9.0.1",
 		"mdast-util-to-hast": "13.2.0",
 		"postcss": "8.4.23",
 		"postcss-cli": "8.3.1",
-		"prismjs": "1.30.0",
 		"rehype": "13.0.2",
 		"rehype-autolink-headings": "7.1.0",
 		"rehype-parse": "9.0.1",
 		"rehype-slug": "6.0.0",
 		"remark": "15.0.1",
 		"remark-directive": "4.0.0",
-		"tailwindcss": "3.3.2",
+		"shiki": "3.7.0",
+		"tailwindcss": "4.0.17",
+		"tailwindcss-capsize": "4.0.1",
 		"tailwindcss-opentype": "workspace:*",
 		"unified": "11.0.5",
+		"unist-util-remove": "4.0.0",
 		"unist-util-visit": "5.0.0"
 	}
 }

docs/postcss.config.js

@@ -0,0 +1,8 @@
+const config = {
+	plugins: {
+		'@tailwindcss/postcss': {},
+		autoprefixer: {},
+	},
+}
+
+export default config

docs/remark/directives.js

@@ -1,7 +1,7 @@
 import dedent from 'dedent'
 import { h } from 'hastscript'
 import { toHast } from 'mdast-util-to-hast'
-import parse from 'rehype-parse'
+import rehypeParse from 'rehype-parse'
 import { unified } from 'unified'
 import { visit } from 'unist-util-visit'
 
@@ -18,9 +18,10 @@ export function remarkDirectives() {
 					node.type === 'textDirective'
 				) {
 					let data = (node.data ??= {})
+					/** @type {import('hast').Properties} */
+					let properties = node.attributes ?? {}
 					/** @type {import('hast').Element} */
-					let hast = h(node.name, node.attributes)
-					let children = []
+					let hast = h(node.name, properties)
 
 					switch (node.name) {
 						case 'feat': {
@@ -29,20 +30,21 @@ export function remarkDirectives() {
 									? node.children[0].value.split(',')
 									: undefined
 							let features = dedent`
-								<span aria-hidden="true" class="inline-flex self-center mx-4 h-6 w-px align-middle bg-grey-700 bg-opacity-20"></span>
-								${tags.map((tag) => markupTagText(tag))}
+								<span aria-hidden="true" class="inline-flex self-center mx-4 h-6 w-px align-middle bg-grey-900/10 dark:bg-white/15"></span>
+								${tags?.map((tag) => markupTagText(tag))}
 							`
 								.replaceAll('\n', '')
 								.replaceAll('\t', '')
 								.replace(',', ' ')
 
-							let parsed = unified().use(parse).parse(features)
-							let html = parsed.children[0]
-							/** @todo Fix type information here. */
-							// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-							children = html.children[1].children
+							let parsed = unified()
+								.use(rehypeParse, { fragment: true })
+								.parse(features).children
 
-							hast = h(node.name, node.attributes, [children])
+							hast = h(node.name, properties, parsed)
+							data.hProperties = {
+								class: 'not-prose inline',
+							}
 							data.hChildren = hast.children
 							break
 						}
@@ -52,17 +54,15 @@ export function remarkDirectives() {
 								<svg class="flex-none h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
 									<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
 								</svg>`
+
 							let existing = toHast(node.children[0])
-							/** @todo Fix type information here. */
-							// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-							let child = unified().use(parse).parse(icon).children[0]
-								.children[1].children
+							let child = unified()
+								.use(rehypeParse, { fragment: true })
+								.parse(icon).children
 
-							existing.properties.class = '!m-0'
-							console.log(existing)
 							hast = h(
 								'div',
-								{ class: 'flex gap-4 p-4 bg-grey-100 rounded-lg' },
+								{ class: 'not-prose flex gap-4 p-4 bg-grey-100 rounded-lg' },
 								[child, existing],
 							)
 							data.hName = hast.tagName
@@ -81,8 +81,11 @@ export function remarkDirectives() {
 	}
 }
 
+/**
+ * @param {string} tag
+ */
 function markupTagText(tag) {
-	return dedent`<span class="align-middle inline-flex items-center px-3 py-1 rounded-full text-sm font-medium leading-4 bg-grey-50 text-grey-600 tracking-tight">
+	return dedent`<span class="align-middle inline-flex items-center px-3 py-1 rounded-full text-xs font-medium leading-4 bg-grey-50 text-grey-600 tracking-tight dark:bg-grey-900 dark:text-gray-400">
 		<kbd>${tag}</kbd>
 	</span>`
 }

docs/remark/headings.js

@@ -1,20 +1,18 @@
 import { visit } from 'unist-util-visit'
 
 export function remarkHeadings() {
-	/** @param {import('@types/mdast').Root} tree */
+	/** @param {import('mdast').Root} tree */
 	return (tree) => {
 		visit(
 			tree,
 			'heading',
-			/** @param {import('@types/mdast').Heading} node */ (node) => {
+			/** @param {import('mdast').Heading} node */ (node) => {
 				if (node.depth === 1) return
 
-				let data = (node.data ??= {})
-				let properties = (data.hProperties ??= {})
-				/** @type {string[]} */
-				let classes = (properties.class ??= [])
-
-				classes.push('group flex whitespace-pre-wrap')
+				node.data ??= {}
+				node.data.hProperties = {
+					className: ['group flex whitespace-pre-wrap'],
+				}
 			},
 		)
 	}