@astrojs/starlight 0.33.1 → 0.34.0

package/integrations/heading-links.ts

@@ -0,0 +1,104 @@
+import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+import type { AstroConfig, AstroUserConfig } from 'astro';
+import type { Nodes, Root } from 'hast';
+import { toString } from 'hast-util-to-string';
+import { h } from 'hastscript';
+import type { Transformer } from 'unified';
+import { SKIP, visit } from 'unist-util-visit';
+import type { HookParameters, StarlightConfig } from '../types';
+
+const AnchorLinkIcon = h(
+	'span',
+	{ ariaHidden: 'true', class: 'sl-anchor-icon' },
+	h(
+		'svg',
+		{ width: 16, height: 16, viewBox: '0 0 24 24' },
+		h('path', {
+			fill: 'currentcolor',
+			d: 'm12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z',
+		})
+	)
+);
+
+/**
+ * Add anchor links to headings.
+ */
+export default function rehypeAutolinkHeadings(
+	useTranslationsForLang: HookParameters<'config:setup'>['useTranslations'],
+	absolutePathToLang: HookParameters<'config:setup'>['absolutePathToLang']
+) {
+	const transformer: Transformer<Root> = (tree, file) => {
+		const pageLang = absolutePathToLang(file.path);
+		const t = useTranslationsForLang(pageLang);
+
+		visit(tree, 'element', function (node, index, parent) {
+			if (!headingRank(node) || !node.properties.id || typeof index !== 'number' || !parent) {
+				return;
+			}
+
+			const accessibleLabel = t('heading.anchorLabel', {
+				title: toString(node),
+				interpolation: { escapeValue: false },
+			});
+
+			// Wrap the heading in a div and append the anchor link.
+			parent.children[index] = h(
+				'div',
+				{ class: `sl-heading-wrapper level-${node.tagName}` },
+				// Heading
+				node,
+				// Anchor link
+				{
+					type: 'element',
+					tagName: 'a',
+					properties: { class: 'sl-anchor-link', href: '#' + node.properties.id },
+					children: [AnchorLinkIcon, h('span', { class: 'sr-only' }, accessibleLabel)],
+				}
+			);
+
+			return SKIP;
+		});
+	};
+
+	return function attacher() {
+		return transformer;
+	};
+}
+
+interface AutolinkHeadingsOptions {
+	starlightConfig: Pick<StarlightConfig, 'markdown'>;
+	astroConfig: { experimental: Pick<AstroConfig['experimental'], 'headingIdCompat'> };
+	useTranslations: HookParameters<'config:setup'>['useTranslations'];
+	absolutePathToLang: HookParameters<'config:setup'>['absolutePathToLang'];
+}
+type RehypePlugins = NonNullable<NonNullable<AstroUserConfig['markdown']>['rehypePlugins']>;
+
+export const starlightAutolinkHeadings = ({
+	starlightConfig,
+	astroConfig,
+	useTranslations,
+	absolutePathToLang,
+}: AutolinkHeadingsOptions): RehypePlugins =>
+	starlightConfig.markdown.headingLinks
+		? [
+				[
+					rehypeHeadingIds,
+					{ experimentalHeadingIdCompat: astroConfig.experimental?.headingIdCompat },
+				],
+				rehypeAutolinkHeadings(useTranslations, absolutePathToLang),
+			]
+		: [];
+
+// This utility is inlined from https://github.com/syntax-tree/hast-util-heading-rank
+// Copyright (c) 2020 Titus Wormer <tituswormer@gmail.com>
+// MIT License: https://github.com/syntax-tree/hast-util-heading-rank/blob/main/license
+/**
+ * Get the rank (`1` to `6`) of headings (`h1` to `h6`).
+ * @param node Node to check.
+ * @returns Rank of the heading or `undefined` if not a heading.
+ */
+function headingRank(node: Nodes): number | undefined {
+	const name = node.type === 'element' ? node.tagName.toLowerCase() : '';
+	const code = name.length === 2 && name.charCodeAt(0) === 104 /* `h` */ ? name.charCodeAt(1) : 0;
+	return code > 48 /* `0` */ && code < 55 /* `7` */ ? code - 48 /* `0` */ : undefined;
+}

package/integrations/virtual-user-config.ts

@@ -84,6 +84,15 @@ export function vitePluginStarlightUserConfig(
 				: `import { makeAPI } from ${resolveLocalPath('../utils/gitInlined.ts')};` +
 					`const api = makeAPI(${JSON.stringify(getAllNewestCommitDate(rootPath, docsPath))});`) +
 			'export const getNewestCommitDate = api.getNewestCommitDate;',
+		/**
+		 * Module containing styles for features that can be toggled on or off such as heading anchor links.
+		 */
+		'virtual:starlight/optional-css': opts.markdown.headingLinks
+			? `import ${resolveLocalPath('../style/anchor-links.css')};`
+			: '',
+		/**
+		 * Module containing imports of user-specified custom CSS files.
+		 */
 		'virtual:starlight/user-css': opts.customCss.map((id) => `import ${resolveId(id)};`).join(''),
 		'virtual:starlight/user-images': opts.logo
 			? 'src' in opts.logo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -103,6 +103,10 @@
       "types": "./components/StarlightPage.astro.tsx",
       "import": "./components/StarlightPage.astro"
     },
+    "./components/AnchorHeading.astro": {
+      "types": "./components/AnchorHeading.astro.tsx",
+      "import": "./components/AnchorHeading.astro"
+    },
     "./components/Footer.astro": {
       "types": "./components/Footer.astro.tsx",
       "import": "./components/Footer.astro"
@@ -173,25 +177,25 @@
     "./style/markdown.css": "./style/markdown.css"
   },
   "peerDependencies": {
-    "astro": "^5.1.5"
+    "astro": "^5.5.0"
   },
   "devDependencies": {
-    "@astrojs/markdown-remark": "^6.0.1",
     "@playwright/test": "^1.45.0",
     "@types/node": "^18.16.19",
     "@vitest/coverage-v8": "^3.0.5",
-    "astro": "^5.5.3",
+    "astro": "^5.6.1",
     "linkedom": "^0.18.4",
     "vitest": "^3.0.5"
   },
   "dependencies": {
-    "@astrojs/mdx": "^4.0.5",
-    "@astrojs/sitemap": "^3.2.1",
+    "@astrojs/markdown-remark": "^6.3.1",
+    "@astrojs/mdx": "^4.2.3",
+    "@astrojs/sitemap": "^3.3.0",
     "@pagefind/default-ui": "^1.3.0",
     "@types/hast": "^3.0.4",
     "@types/js-yaml": "^4.0.9",
     "@types/mdast": "^4.0.4",
-    "astro-expressive-code": "^0.40.0",
+    "astro-expressive-code": "^0.41.1",
     "bcp-47": "^2.1.0",
     "hast-util-from-html": "^2.0.1",
     "hast-util-select": "^6.0.2",
@@ -207,6 +211,7 @@
     "rehype": "^13.0.1",
     "rehype-format": "^5.0.0",
     "remark-directive": "^3.0.0",
+    "ultrahtml": "^1.6.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
     "vfile": "^6.0.2"

package/schemas/head.ts

@@ -7,9 +7,9 @@ export const HeadConfigSchema = () =>
 				/** Name of the HTML tag to add to `<head>`, e.g. `'meta'`, `'link'`, or `'script'`. */
 				tag: z.enum(['title', 'base', 'link', 'style', 'meta', 'script', 'noscript', 'template']),
 				/** Attributes to set on the tag, e.g. `{ rel: 'stylesheet', href: '/custom.css' }`. */
-				attrs: z.record(z.union([z.string(), z.boolean(), z.undefined()])).default({}),
+				attrs: z.record(z.union([z.string(), z.boolean(), z.undefined()])).optional(),
 				/** Content to place inside the tag (optional). */
-				content: z.string().default(''),
+				content: z.string().optional(),
 			})
 		)
 		.default([]);

package/schemas/i18n.ts

@@ -158,6 +158,8 @@ function starlightI18nSchema() {
 				.describe(
 					'Label for the “Built with Starlight” badge optionally displayed in the site footer.'
 				),
+
+			'heading.anchorLabel': z.string().describe('Label for anchor links in Markdown content.'),
 		})
 		.partial();
 }

package/style/anchor-links.css

@@ -0,0 +1,125 @@
+/* 
+How does anchor link placement work?
+
+Because anchor links need to placed inline at the end of a heading, but are not children of the
+heading element itself, positioning them to behave in a desirable way is a tiny bit tricky. Here’s
+how we do it.
+
+1. We wrap the heading and anchor link in a div and make the heading element inline:
+   <div class="sl-heading-wrapper">
+     <h2>...</h2><a class="sl-anchor-link">...</a>
+   </a>
+
+2. We need to avoid the anchor link wrapping onto a new line by itself like this because it looks
+   broken:
+
+   Some heading text
+   ⛓
+
+3. To achieve this we add an area of padding to the end of the heading and move the link over this
+   padding using negative margin:
+
+                        padding-inline-end creates space at the end of the line
+                         ↓
+      Some heading text[   ]⛓
+
+                        margin-inline-start then pulls the anchor link into that space
+                         ↓
+      Some heading text[ ⛓ ]
+
+   This ensures that when the anchor link wraps, the final word in the heading will wrap with it.
+
+*/
+@layer starlight.content {
+	/* ======================================================
+   WRAPPER
+   ====================================================== */
+	.sl-markdown-content .sl-heading-wrapper {
+		/* The size of the SVG icon. */
+		--sl-anchor-icon-size: 0.8275em;
+		/* The horizontal space between the SVG icon and the end of the heading text. */
+		--sl-anchor-icon-gap: 0.25em;
+		/* The end of line space required to accommodate the anchor link. */
+		--sl-anchor-icon-space: calc(var(--sl-anchor-icon-size) + var(--sl-anchor-icon-gap));
+
+		line-height: var(--sl-line-height-headings);
+	}
+
+	/* We need to apply the same rule we use for heading spacing to the parent wrapper. */
+	.sl-markdown-content
+		:not(h1, h2, h3, h4, h5, h6, .sl-heading-wrapper)
+		+ :is(.sl-heading-wrapper) {
+		margin-top: 1.5em;
+	}
+
+	/* These font sizes are set in `markdown.css` for heading elements, but we need them one level higher on the wrapper. */
+	.sl-markdown-content .sl-heading-wrapper.level-h1 {
+		font-size: var(--sl-text-h1);
+	}
+	.sl-markdown-content .sl-heading-wrapper.level-h2 {
+		font-size: var(--sl-text-h2);
+	}
+	.sl-markdown-content .sl-heading-wrapper.level-h3 {
+		font-size: var(--sl-text-h3);
+	}
+	.sl-markdown-content .sl-heading-wrapper.level-h4 {
+		font-size: var(--sl-text-h4);
+	}
+	.sl-markdown-content .sl-heading-wrapper.level-h5 {
+		font-size: var(--sl-text-h5);
+	}
+	.sl-markdown-content .sl-heading-wrapper.level-h6 {
+		font-size: var(--sl-text-h6);
+	}
+
+	/* ======================================================
+   HEADING
+   ====================================================== */
+	.sl-markdown-content .sl-heading-wrapper > :first-child {
+		display: inline;
+		/* Apply end-of-line padding to the heading element. */
+		padding-inline-end: var(--sl-anchor-icon-space);
+	}
+
+	/* ======================================================
+   LINK
+   ====================================================== */
+	.sl-markdown-content .sl-anchor-link {
+		position: relative;
+		/* Move the anchor link over the heading element’s end-of-line padding. */
+		margin-inline-start: calc(-1 * var(--sl-anchor-icon-size));
+	}
+
+	/* Increase clickable area for anchor links with a pseudo element that doesn’t impact layout. */
+	.sl-markdown-content .sl-anchor-link::after {
+		content: '';
+		position: absolute;
+		/* While most icon spacing is done with `em` to be relative to the heading font-size, increasing
+     the touch area is most important for smaller headings like h5/h6, so we use absolute units,
+     which have a diminishing impact at larger font-sizes. */
+		inset: -0.25rem -0.5rem;
+	}
+
+	/* Size and position the SVG icon inside the link. */
+	.sl-markdown-content .sl-anchor-icon > svg {
+		display: inline;
+		width: var(--sl-anchor-icon-size);
+		/* Center the link icon SVG vertically in the line. */
+		vertical-align: top;
+		transform: translateY(
+			calc((var(--sl-line-height-headings) * 1em - var(--sl-anchor-icon-size)) / 2)
+		);
+	}
+
+	/* On devices with hover capability, hide the anchor link icons and show only show them when focused
+   or when the heading is hovered. */
+	@media (hover: hover) {
+		.sl-markdown-content .sl-anchor-link {
+			opacity: 0;
+		}
+		.sl-markdown-content .sl-anchor-link:focus,
+		.sl-markdown-content .sl-heading-wrapper:hover .sl-anchor-link {
+			opacity: 1;
+		}
+	}
+}

package/style/asides.css

@@ -1,49 +1,51 @@
-.starlight-aside {
-	padding: 1rem;
-	border-inline-start: 0.25rem solid var(--sl-color-asides-border);
-	color: var(--sl-color-white);
-}
-.starlight-aside--note {
-	--sl-color-asides-text-accent: var(--sl-color-blue-high);
-	--sl-color-asides-border: var(--sl-color-blue);
-	background-color: var(--sl-color-blue-low);
-}
-.starlight-aside--tip {
-	--sl-color-asides-text-accent: var(--sl-color-purple-high);
-	--sl-color-asides-border: var(--sl-color-purple);
-	background-color: var(--sl-color-purple-low);
-}
-.starlight-aside--caution {
-	--sl-color-asides-text-accent: var(--sl-color-orange-high);
-	--sl-color-asides-border: var(--sl-color-orange);
-	background-color: var(--sl-color-orange-low);
-}
-.starlight-aside--danger {
-	--sl-color-asides-text-accent: var(--sl-color-red-high);
-	--sl-color-asides-border: var(--sl-color-red);
-	background-color: var(--sl-color-red-low);
-}
+@layer starlight.components {
+	.starlight-aside {
+		padding: 1rem;
+		border-inline-start: 0.25rem solid var(--sl-color-asides-border);
+		color: var(--sl-color-white);
+	}
+	.starlight-aside--note {
+		--sl-color-asides-text-accent: var(--sl-color-blue-high);
+		--sl-color-asides-border: var(--sl-color-blue);
+		background-color: var(--sl-color-blue-low);
+	}
+	.starlight-aside--tip {
+		--sl-color-asides-text-accent: var(--sl-color-purple-high);
+		--sl-color-asides-border: var(--sl-color-purple);
+		background-color: var(--sl-color-purple-low);
+	}
+	.starlight-aside--caution {
+		--sl-color-asides-text-accent: var(--sl-color-orange-high);
+		--sl-color-asides-border: var(--sl-color-orange);
+		background-color: var(--sl-color-orange-low);
+	}
+	.starlight-aside--danger {
+		--sl-color-asides-text-accent: var(--sl-color-red-high);
+		--sl-color-asides-border: var(--sl-color-red);
+		background-color: var(--sl-color-red-low);
+	}
 
-.starlight-aside__title {
-	display: flex;
-	gap: 0.5rem;
-	align-items: center;
-	font-size: var(--sl-text-h5);
-	font-weight: 600;
-	line-height: var(--sl-line-height-headings);
-	color: var(--sl-color-asides-text-accent);
-}
+	.starlight-aside__title {
+		display: flex;
+		gap: 0.5rem;
+		align-items: center;
+		font-size: var(--sl-text-h5);
+		font-weight: 600;
+		line-height: var(--sl-line-height-headings);
+		color: var(--sl-color-asides-text-accent);
+	}
 
-.starlight-aside__icon {
-	font-size: 1.333em;
-	width: 1em;
-	height: 1em;
-}
+	.starlight-aside__icon {
+		font-size: 1.333em;
+		width: 1em;
+		height: 1em;
+	}
 
-.starlight-aside__title + .starlight-aside__content {
-	margin-top: 0.5rem;
-}
+	.starlight-aside__title + .starlight-aside__content {
+		margin-top: 0.5rem;
+	}
 
-.starlight-aside__content a {
-	color: var(--sl-color-asides-text-accent);
+	.starlight-aside__content a {
+		color: var(--sl-color-asides-text-accent);
+	}
 }

package/style/layers.css

@@ -0,0 +1 @@
+@layer starlight.base, starlight.reset, starlight.core, starlight.content, starlight.components, starlight.utils;