@astrojs/starlight 0.37.3 → 0.37.5

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @astrojs/starlight
 
+## 0.37.5
+
+### Patch Changes
+
+- [#3675](https://github.com/withastro/starlight/pull/3675) [`0ba556d`](https://github.com/withastro/starlight/commit/0ba556d7d49dd4904f8aa8524c105bf1ceeec85c) Thanks [@controversial](https://github.com/controversial)! - Excludes the accessible labels for heading anchor links from Pagefind results
+
+## 0.37.4
+
+### Patch Changes
+
+- [#3534](https://github.com/withastro/starlight/pull/3534) [`703fab0`](https://github.com/withastro/starlight/commit/703fab085b99303c0c01325c9bb869ea7e1418c4) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes support for running builds when `npx` is unavailable.
+
+  Previously, Starlight would spawn a process to run the Pagefind search indexing binary using `npx`. On platforms where `npx` isn’t available, this could cause issues. Starlight now runs Pagefind using its Node.js API to avoid a separate process. As a side effect, you may notice that logging during builds is now less verbose.
+
+- [#3656](https://github.com/withastro/starlight/pull/3656) [`a0e6368`](https://github.com/withastro/starlight/commit/a0e636838092d30cb6b8f80e5535ad842e52d759) Thanks [@delucis](https://github.com/delucis)! - Fixes several edge cases in highlighting the current page heading in Starlight’s table of contents
+
+- [#3663](https://github.com/withastro/starlight/pull/3663) [`00cbf00`](https://github.com/withastro/starlight/commit/00cbf001fee4fd59f351c7a6c0f8c353c7c41f13) Thanks [@lines-of-codes](https://github.com/lines-of-codes)! - Adds Thai language support
+
+- [#3658](https://github.com/withastro/starlight/pull/3658) [`ac79329`](https://github.com/withastro/starlight/commit/ac793290f0dbd21f9b9a5d6f60aa315043815227) Thanks [@delucis](https://github.com/delucis)! - Avoids adding redundant `aria-current="false"` attributes to sidebar entries
+
+- [#3382](https://github.com/withastro/starlight/pull/3382) [`db295c2`](https://github.com/withastro/starlight/commit/db295c2a3d75aad71a41702f33001195d89de5d2) Thanks [@trueberryless](https://github.com/trueberryless)! - Fixes an issue where the mobile table of contents is unable to find the first heading when a page has a tall banner.
+
 ## 0.37.3
 
 ### Patch Changes

package/components/AnchorHeading.astro

@@ -48,6 +48,6 @@ const accessibleLabel = Astro.locals.t('heading.anchorLabel', {
 					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"
 				></path></svg
 			></span
-		><span class="sr-only" set:text={accessibleLabel} /></a
+		><span class="sr-only" data-pagefind-ignore="" set:text={accessibleLabel} /></a
 	></div
 >

package/components/SidebarSublist.astro

@@ -20,7 +20,7 @@ const { sublist, nested } = Astro.props;
 				{entry.type === 'link' ? (
 					<a
 						href={entry.href}
-						aria-current={entry.isCurrent && 'page'}
+						aria-current={entry.isCurrent ? 'page' : undefined}
 						class:list={[{ large: !nested }, entry.attrs.class]}
 						{...entry.attrs}
 					>

package/components/TableOfContents/starlight-toc.ts

@@ -5,6 +5,14 @@ export class StarlightTOC extends HTMLElement {
 	private minH = parseInt(this.dataset.minH || '2', 10);
 	private maxH = parseInt(this.dataset.maxH || '3', 10);
 
+	/**
+	 * CSS selector string that matches only headings that can appear in the table of contents.
+	 * Generates a selector like `h1#_top,:where(h2,h3)[id]`.
+	 */
+	private tocHeadingSelector =
+		`h1#${PAGE_TITLE_ID},` +
+		`:where(${[...Array.from({ length: 1 + this.maxH - this.minH }).map((_, index) => `h${this.minH + index}`)].join()})[id]`;
+
 	protected set current(link: HTMLAnchorElement) {
 		if (link === this._current) return;
 		if (this._current) this._current.removeAttribute('aria-current');
@@ -25,26 +33,22 @@ export class StarlightTOC extends HTMLElement {
 		const links = [...this.querySelectorAll('a')];
 
 		/** Test if an element is a table-of-contents heading. */
-		const isHeading = (el: Element): el is HTMLHeadingElement => {
-			if (el instanceof HTMLHeadingElement) {
-				// Special case for page title h1
-				if (el.id === PAGE_TITLE_ID) return true;
-				// Check the heading level is within the user-configured limits for the ToC
-				const level = el.tagName[1];
-				if (level) {
-					const int = parseInt(level, 10);
-					if (int >= this.minH && int <= this.maxH) return true;
-				}
-			}
-			return false;
-		};
+		const isHeading = (el: Element): el is HTMLHeadingElement =>
+			el.matches(this.tocHeadingSelector);
 
 		/** Walk up the DOM to find the nearest heading. */
 		const getElementHeading = (el: Element | null): HTMLHeadingElement | null => {
 			if (!el) return null;
 			const origin = el;
 			while (el) {
+				// Short circuit if we reach the top-level content container or one of the other containers in main.
+				if (el.matches('.sl-markdown-content, main > *')) {
+					return document.getElementById(PAGE_TITLE_ID) as HTMLHeadingElement;
+				}
 				if (isHeading(el)) return el;
+				// Find the first heading that is a child of this element, and return it if there is one.
+				const childHeading = el.querySelector<HTMLHeadingElement>(this.tocHeadingSelector);
+				if (childHeading) return childHeading;
 				// Assign the previous sibling’s last, most deeply nested child to el.
 				el = el.previousElementSibling;
 				while (el?.lastElementChild) {
@@ -72,10 +76,20 @@ export class StarlightTOC extends HTMLElement {
 			}
 		};
 
-		// Observe elements with an `id` (most likely headings) and their siblings.
-		// Also observe direct children of `.content` to include elements before
-		// the first heading.
-		const toObserve = document.querySelectorAll('main [id], main [id] ~ *, main .content > *');
+		// Observe the following elements:
+		// - headings that appear in the table of contents
+		// - siblings of those headings or of the `.sl-heading-wrapper` added by Starlight’s anchor links feature
+		// - direct children of `.sl-markdown-content` to include elements before the first subheading
+		// - direct children of `main` that don’t include headings (mainly to target Starlight’s banner)
+		// Ignore any elements that themselves contain a table-of-contents heading, as we are already observing those children.
+		const toObserve = document.querySelectorAll(
+			[
+				`main :where(${this.tocHeadingSelector})`,
+				`main :where(${this.tocHeadingSelector}, .sl-heading-wrapper) ~ *:not(:has(${this.tocHeadingSelector}))`,
+				`main .sl-markdown-content > *:not(:has(${this.tocHeadingSelector}))`,
+				`main > *:not(:has(${this.tocHeadingSelector}))`,
+			].join()
+		);
 
 		let observer: IntersectionObserver | undefined;
 		const observe = () => {

package/index.ts

@@ -8,11 +8,8 @@
 /// <reference path="./virtual.d.ts" />
 
 import mdx from '@astrojs/mdx';
-import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
+import type { AstroIntegration } from 'astro';
 import { AstroError } from 'astro/errors';
-import { spawn } from 'node:child_process';
-import { dirname, relative } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import {
 	starlightRehypePlugins,
 	starlightRemarkPlugins,
@@ -20,6 +17,7 @@ import {
 } from './integrations/remark-rehype';
 import { starlightDirectivesRestorationIntegration } from './integrations/asides';
 import { starlightExpressiveCode } from './integrations/expressive-code/index';
+import { starlightPagefind } from './integrations/pagefind';
 import { starlightSitemap } from './integrations/sitemap';
 import { vitePluginStarlightCssLayerOrder } from './integrations/vite-layer-order';
 import { vitePluginStarlightUserConfig } from './integrations/virtual-user-config';
@@ -148,36 +146,10 @@ export default function StarlightIntegration(
 				injectPluginTranslationsTypes(pluginTranslations, injectTypes);
 			},
 
-			'astro:build:done': ({ dir, logger }) => {
+			'astro:build:done': async (options) => {
 				if (!userConfig.pagefind) return;
-				const loglevelFlag = getPagefindLoggingFlags(logger.options.level);
-				const targetDir = fileURLToPath(dir);
-				const cwd = dirname(fileURLToPath(import.meta.url));
-				const relativeDir = relative(cwd, targetDir);
-				return new Promise<void>((resolve) => {
-					spawn('npx', ['-y', 'pagefind', ...loglevelFlag, '--site', relativeDir], {
-						stdio: 'inherit',
-						shell: true,
-						cwd,
-					}).on('close', () => resolve());
-				});
+				return starlightPagefind(options);
 			},
 		},
 	};
 }
-
-/** Map the logging level of Astro’s logger to one of Pagefind’s logging level flags. */
-function getPagefindLoggingFlags(level: AstroIntegrationLogger['options']['level']) {
-	switch (level) {
-		case 'silent':
-		case 'error':
-			return ['--silent'];
-		case 'warn':
-			return ['--quiet'];
-		case 'debug':
-			return ['--verbose'];
-		case 'info':
-		default:
-			return [];
-	}
-}

package/integrations/heading-links.ts

@@ -50,7 +50,10 @@ export default function rehypeAutolinkHeadings({
 					type: 'element',
 					tagName: 'a',
 					properties: { class: 'sl-anchor-link', href: '#' + String(node.properties.id) },
-					children: [AnchorLinkIcon, h('span', { class: 'sr-only' }, accessibleLabel)],
+					children: [
+						AnchorLinkIcon,
+						h('span', { class: 'sr-only', 'data-pagefind-ignore': true }, accessibleLabel),
+					],
 				}
 			);
 

package/integrations/pagefind.ts

@@ -0,0 +1,60 @@
+import type { HookParameters } from 'astro';
+import { fileURLToPath } from 'node:url';
+import * as pagefind from 'pagefind';
+
+/** Run Pagefind to generate search index files based on the build output directory. */
+export async function starlightPagefind({
+	dir,
+	logger: starlightLogger,
+}: PagefindIntegrationOptions) {
+	const logger = starlightLogger.fork('starlight:pagefind');
+	const options = { dir, logger };
+
+	try {
+		const now = performance.now();
+		logger.info('Building search index with Pagefind...');
+
+		const newIndexResponse = await pagefind.createIndex();
+
+		const { index } = assertPagefindResponse<pagefind.NewIndexResponse>(newIndexResponse, options);
+
+		const indexingResponse = await index.addDirectory({ path: fileURLToPath(dir) });
+		const { page_count } = assertPagefindResponse<pagefind.IndexingResponse>(
+			indexingResponse,
+			options
+		);
+
+		logger.info(`Found ${page_count} HTML files.`);
+
+		const writeFilesResponse = await index.writeFiles({
+			outputPath: fileURLToPath(new URL('./pagefind/', dir)),
+		});
+		assertPagefindResponse<pagefind.WriteFilesResponse>(writeFilesResponse, options);
+
+		const pagefindTime = performance.now() - now;
+		logger.info(
+			`Finished building search index in ${pagefindTime < 750 ? `${Math.round(pagefindTime)}ms` : `${(pagefindTime / 1000).toFixed(2)}s`}.`
+		);
+	} catch (cause) {
+		throw new Error('Failed to run Pagefind.', { cause });
+	} finally {
+		await pagefind.close();
+	}
+}
+
+function assertPagefindResponse<T extends PagefindBaseResponse>(
+	response: T,
+	{ logger }: PagefindIntegrationOptions
+) {
+	if (response.errors.length > 0) {
+		for (const error of response.errors) logger.error(`Pagefind error: ${error}`);
+		throw new Error('Pagefind response contained errors.');
+	}
+	return response as Required<T>;
+}
+
+interface PagefindBaseResponse {
+	errors: string[];
+}
+
+type PagefindIntegrationOptions = Pick<HookParameters<'astro:build:done'>, 'dir' | 'logger'>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.37.3",
+  "version": "0.37.5",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",

package/translations/index.ts

@@ -15,6 +15,7 @@ import id from './id.json';
 import it from './it.json';
 import nl from './nl.json';
 import da from './da.json';
+import th from './th.json';
 import tr from './tr.json';
 import ar from './ar.json';
 import nb from './nb.json';
@@ -53,6 +54,7 @@ export default Object.fromEntries(
 		it,
 		nl,
 		da,
+		th,
 		tr,
 		ar,
 		nb,

package/translations/th.json

@@ -0,0 +1,30 @@
+{
+  "skipLink.label": "ข้ามไปยังเนื้อหา",
+  "search.label": "ค้นหา",
+  "search.ctrlKey": "Ctrl",
+  "search.cancelLabel": "ยกเลิก",
+  "search.devWarning": "การค้นหาสามารถใช้งานได้ในเฉพาะเวอร์ชันใช้งานจริงเท่านั้น\nโปรดลองบิลด์และดูตัวอย่างเว็บไซต์เพื่อทดสอบฟังก์ชันบนอุปกรณ์ของคุณ",
+  "themeSelect.accessibleLabel": "เลือกธีม",
+  "themeSelect.dark": "มืด",
+  "themeSelect.light": "สว่าง",
+  "themeSelect.auto": "อัตโนมัติ",
+  "languageSelect.accessibleLabel": "เลือกภาษา",
+  "menuButton.accessibleLabel": "เมนู",
+  "sidebarNav.accessibleLabel": "หลัก",
+  "tableOfContents.onThisPage": "ในหน้านี้",
+  "tableOfContents.overview": "ภาพรวม",
+  "i18n.untranslatedContent": "เนื้อหานี้ยังไม่มีในภาษาของคุณ",
+  "page.editLink": "แก้ไขหน้า",
+  "page.lastUpdated": "อัพเดทล่าสุด:",
+  "page.previousLink": "ก่อนหน้า",
+  "page.nextLink": "ถัดไป",
+  "page.draft": "เนื้อหานี้เป็นแบบร่างและจะไม่ถูกใส่ในเวอร์ชันใช้งานจริง",
+  "404.text": "ไม่พบหน้า โปรดตรวจสอบ URL หรือลองใช้ฟังก์ชันการค้นหา",
+  "aside.note": "หมายเหตุ",
+  "aside.tip": "เคล็ดลับ",
+  "aside.caution": "คำเตือน",
+  "aside.danger": "อันตราย",
+  "fileTree.directory": "โฟลเดอร์",
+  "builtWithStarlight.label": "ถูกสร้างขึ้นด้วย Starlight",
+  "heading.anchorLabel": "หัวข้อที่มีชื่อว่า “{{title}}”"
+}