@astrojs/starlight 0.41.11 → 0.42.0

package/integrations/remark-asides.ts

@@ -1,219 +0,0 @@
-/// <reference types="mdast-util-directive" />
-
-import { h as _h, s as _s, type Properties } from 'hastscript';
-import type { Node, Paragraph as P, Parent, PhrasingContent, Root } from 'mdast';
-import {
-	type Directives,
-	directiveToMarkdown,
-	type TextDirective,
-	type LeafDirective,
-} from 'mdast-util-directive';
-import { toMarkdown } from 'mdast-util-to-markdown';
-import { toString } from 'mdast-util-to-string';
-import type { Plugin, Transformer } from 'unified';
-import { visit } from 'unist-util-visit';
-import type { MarkdownProcessorPluginOptions } from './markdown-processor';
-import { parseIconChildren } from './markdown-icon';
-import type { ElementContent } from 'hast';
-import { getAsideIcon, isAsideVariant, type AsideVariant } from './aside-utils';
-
-/** Hacky function that generates an mdast HTML tree ready for conversion to HTML by rehype. */
-function h(el: string, attrs: Properties = {}, children: unknown[] = []): P {
-	const { tagName, properties } = _h(el, attrs);
-	return {
-		type: 'paragraph',
-		data: { hName: tagName, hProperties: properties },
-		children: children as P['children'],
-	};
-}
-
-/** Hacky function that generates an mdast SVG tree ready for conversion to HTML by rehype. */
-function s(el: string, attrs: Properties = {}, children: unknown[] = []): P {
-	const { tagName, properties } = _s(el, attrs);
-	return {
-		type: 'paragraph',
-		data: { hName: tagName, hProperties: properties },
-		children: children as P['children'],
-	};
-}
-
-/** Checks if a node is a directive. */
-function isNodeDirective(node: Node): node is Directives {
-	return (
-		node.type === 'textDirective' ||
-		node.type === 'leafDirective' ||
-		node.type === 'containerDirective'
-	);
-}
-
-/**
- * Transforms back directives not handled by Starlight to avoid breaking user content.
- * For example, a user might write `x:y` in the middle of a sentence, where `:y` would be
- * identified as a text directive, which are not used by Starlight, and we definitely want that
- * text to be rendered verbatim in the output.
- */
-function transformUnhandledDirective(
-	node: TextDirective | LeafDirective,
-	index: number,
-	parent: Parent
-) {
-	let markdown = toMarkdown(node, { extensions: [directiveToMarkdown()] });
-	/**
-	 * `mdast-util-to-markdown` assumes that the tree represents a complete document (as it's an AST
-	 * and not a CST) and to follow the POSIX definition of a line (a sequence of zero or more
-	 * non- <newline> characters plus a terminating <newline> character), a newline is automatically
-	 * added at the end of the output so that the output is a valid file.
-	 * In this specific case, we can safely remove the newline character at the end of the output
-	 * before replacing the directive with its value.
-	 *
-	 * @see https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_206
-	 * @see https://github.com/syntax-tree/mdast-util-to-markdown/blob/fd6a508cc619b862f75b762dcf876c6b8315d330/lib/index.js#L79-L85
-	 */
-	if (markdown.at(-1) === '\n') markdown = markdown.slice(0, -1);
-	const textNode = { type: 'text', value: markdown } as const;
-	if (node.type === 'textDirective') {
-		parent.children[index] = textNode;
-	} else {
-		parent.children[index] = {
-			type: 'paragraph',
-			children: [textNode],
-		};
-	}
-}
-
-/** Hacky function that generates the children of an mdast SVG tree. */
-function makeSvgChildNodes(children: ElementContent[]): P[] {
-	const nodes: P[] = [];
-	for (const child of children) {
-		if (child.type !== 'element') continue;
-		nodes.push({
-			type: 'paragraph',
-			data: { hName: child.tagName, hProperties: child.properties },
-			// We are explicitly casting to the expected type here due to the hacky nature of this
-			// function which only works with SVG elements.
-			children: makeSvgChildNodes(child.children) as unknown as P['children'],
-		});
-	}
-	return nodes;
-}
-
-/**
- * remark plugin that converts blocks delimited with `:::` into styled
- * asides (a.k.a. “callouts”, “admonitions”, etc.). Depends on the
- * `remark-directive` module for the core parsing logic.
- *
- * For example, this Markdown
- *
- * ```md
- * :::tip[Did you know?]
- * Astro helps you build faster websites with “Islands Architecture”.
- * :::
- * ```
- *
- * will produce this output
- *
- * ```astro
- * <aside class="starlight-aside starlight-aside--tip" aria-label="Did you know?">
- *   <p class="starlight-aside__title" aria-hidden="true">Did you know?</p>
- *   <div class="starlight-aside__content">
- *     <p>Astro helps you build faster websites with “Islands Architecture”.</p>
- *   </div>
- * </aside>
- * ```
- */
-export function remarkAsides(options: MarkdownProcessorPluginOptions): Plugin<[], Root> {
-	const iconPaths: Record<AsideVariant, ReturnType<typeof parseIconChildren>> = {
-		note: parseIconChildren(getAsideIcon('note')),
-		tip: parseIconChildren(getAsideIcon('tip')),
-		caution: parseIconChildren(getAsideIcon('caution')),
-		danger: parseIconChildren(getAsideIcon('danger')),
-	};
-
-	const transformer: Transformer<Root> = (tree, file) => {
-		const lang = options.absolutePathToLang(file.path);
-		const t = options.useTranslations(lang);
-		visit(tree, (node, index, parent) => {
-			if (!parent || index === undefined || !isNodeDirective(node)) {
-				return;
-			}
-			if (node.type === 'textDirective' || node.type === 'leafDirective') {
-				return;
-			}
-			const variant = node.name;
-			const attributes = node.attributes;
-			if (!isAsideVariant(variant)) return;
-
-			// remark-directive converts a container’s “label” to a paragraph added as the head of its
-			// children with the `directiveLabel` property set to true. We want to pass it as the title
-			// prop to <Aside>, so when we find a directive label, we store it for the title prop and
-			// remove the paragraph from the container’s children.
-			let title: string = t(`aside.${variant}`);
-			let titleNode: PhrasingContent[] = [{ type: 'text', value: title }];
-			const firstChild = node.children[0];
-			if (
-				firstChild?.type === 'paragraph' &&
-				firstChild.data &&
-				'directiveLabel' in firstChild.data &&
-				firstChild.children.length > 0
-			) {
-				titleNode = firstChild.children;
-				title = toString(firstChild.children);
-				// The first paragraph contains a directive label, we can safely remove it.
-				node.children.splice(0, 1);
-			}
-
-			const iconPath = makeSvgChildNodes(
-				attributes?.['icon']
-					? parseIconChildren(getAsideIcon(variant, attributes?.['icon']))
-					: iconPaths[variant]
-			);
-
-			const aside = h(
-				'aside',
-				{
-					'aria-label': title,
-					class: `starlight-aside starlight-aside--${variant}`,
-				},
-				[
-					h('p', { class: 'starlight-aside__title', 'aria-hidden': 'true' }, [
-						s(
-							'svg',
-							{
-								viewBox: '0 0 24 24',
-								width: 16,
-								height: 16,
-								fill: 'currentColor',
-								class: 'starlight-aside__icon',
-							},
-							iconPath
-						),
-						...titleNode,
-					]),
-					h('div', { class: 'starlight-aside__content' }, node.children),
-				]
-			);
-
-			parent.children[index] = aside;
-		});
-	};
-
-	return function attacher() {
-		return transformer;
-	};
-}
-
-export function remarkDirectivesRestoration() {
-	return function transformer(tree: Root) {
-		visit(tree, (node, index, parent) => {
-			if (
-				index !== undefined &&
-				parent &&
-				(node.type === 'textDirective' || node.type === 'leafDirective') &&
-				node.data === undefined
-			) {
-				transformUnhandledDirective(node, index, parent);
-				return;
-			}
-		});
-	};
-}

package/integrations/remark-rehype.ts

@@ -1,87 +0,0 @@
-import { isUnifiedProcessor, rehypeHeadingIds } from '@astrojs/markdown-remark';
-import type { Root as RehypeRoot } from 'hast';
-import type { Root as RemarkRoot } from 'mdast';
-import remarkDirective from 'remark-directive';
-import type { Plugin } from 'unified';
-import type { VFile } from 'vfile';
-import { remarkAsides, remarkDirectivesRestoration } from './remark-asides';
-import { rehypeRtlCodeSupport } from './rehype-code-rtl-support';
-import rehypeAutolinkHeadings from './rehype-heading-links';
-import {
-	getMarkdownProcessorPaths,
-	shouldTransformPath,
-	type MarkdownProcessorPluginOptions,
-} from './markdown-processor';
-
-// Re-exported so callers can narrow `markdown.processor` to the Unified processor and use the
-// remark directive-restoration plugin through the same lazy import that loads the optional
-// `@astrojs/markdown-remark` peer dependency.
-export { isUnifiedProcessor, remarkDirectivesRestoration };
-
-/** List of remark plugins to apply. */
-export function starlightRemarkPlugins(options: MarkdownProcessorPluginOptions): RemarkPlugin[] {
-	return [remarkDirective, remarkPlugins(options)];
-}
-
-/** List of rehype plugins to apply. */
-export function starlightRehypePlugins(options: MarkdownProcessorPluginOptions): RehypePlugin[] {
-	return [
-		...(options.starlightConfig.markdown.headingLinks ? [[rehypeHeadingIds]] : []),
-		rehypePlugins(options),
-	] as RehypePlugin[];
-}
-
-/** Remark plugin applying other Starlight remark plugins if necessary. */
-function remarkPlugins(options: MarkdownProcessorPluginOptions): RemarkPlugin {
-	const allowedPaths = getMarkdownProcessorPaths(options);
-
-	return function attacher(this) {
-		const remarkAsidesTransformer = remarkAsides(options).call(this)!;
-
-		return async function transformer(...args) {
-			const [, file] = args;
-
-			if (!shouldTransformFile(file, allowedPaths)) return;
-
-			await remarkAsidesTransformer(...args);
-		};
-	};
-}
-
-/** Rehype plugin applying other Starlight rehype plugins if necessary. */
-function rehypePlugins(options: MarkdownProcessorPluginOptions): RehypePlugin {
-	const allowedPaths = getMarkdownProcessorPaths(options);
-
-	return function attacher(this) {
-		const rehypeRtlCodeSupportTransformer = rehypeRtlCodeSupport(options).call(this);
-		const rehypeAutolinkHeadingsTransformer = rehypeAutolinkHeadings(options).call(this);
-
-		return async function transformer(...args) {
-			const [, file] = args;
-
-			if (!shouldTransformFile(file, allowedPaths)) return;
-
-			await rehypeRtlCodeSupportTransformer(...args);
-
-			if (options.starlightConfig.markdown.headingLinks) {
-				await rehypeAutolinkHeadingsTransformer(...args);
-			}
-		};
-	};
-}
-
-/**
- * Determines if a file should be transformed by a remark/rehype plugin, e.g. files without a known
- * path or files that are not part of the allowed paths are skipped.
- */
-function shouldTransformFile(file: VFile, allowedPaths: string[]) {
-	// If the content is rendered using the content loader `renderMarkdown()` API, a file path
-	// is not provided.
-	// In that case, we skip the file.
-	if (!file?.path) return false;
-
-	return shouldTransformPath(file.path, allowedPaths);
-}
-
-type RemarkPlugin = Plugin<[], RemarkRoot>;
-type RehypePlugin = Plugin<[], RehypeRoot>;

package/integrations/satteri.ts

@@ -1,265 +0,0 @@
-import { fileURLToPath } from 'node:url';
-import { satteriHeadingIdsPlugin } from '@astrojs/markdown-satteri';
-import type { Parents, Properties } from 'hast';
-import type { Paragraph } from 'mdast';
-import { directiveToMarkdown } from 'mdast-util-directive';
-import { toMarkdown } from 'mdast-util-to-markdown';
-import type {
-	HastPluginDefinition,
-	HastPluginInput,
-	HastVisitorContext,
-	MdastPluginInput,
-	MdastPluginDefinition,
-} from 'satteri';
-import { headingLinkIconChildren } from './markdown-icon';
-import { getAsideIcon, isAsideVariant } from './aside-utils';
-import {
-	getMarkdownProcessorPaths,
-	shouldTransformPath,
-	type MarkdownProcessorPluginOptions,
-} from './markdown-processor';
-
-export function starlightSatteriPlugins(options: MarkdownProcessorPluginOptions): {
-	mdastPlugins: MdastPluginInput[];
-	hastPlugins: HastPluginInput[];
-} {
-	const allowedPaths = getMarkdownProcessorPaths(options);
-	return {
-		mdastPlugins: [satteriAsidesPlugin(options, allowedPaths)],
-		hastPlugins: [
-			satteriRtlCodeSupportPlugin(allowedPaths),
-			...(options.starlightConfig.markdown.headingLinks
-				? [() => satteriHeadingIdsPlugin(), satteriAutolinkHeadingsPlugin(options, allowedPaths)]
-				: []),
-		],
-	};
-}
-
-/**
- * Recover directives Starlight didn't claim so user content isn't dropped
- */
-export function satteriDirectivesRestoration(): MdastPluginDefinition {
-	return {
-		name: 'starlight-directives-restoration',
-		textDirective(node) {
-			// Leave directives another plugin already handled (i.e. set `data` on) untouched.
-			if (node.data !== undefined) return;
-			return { type: 'text', value: serializeDirective(node) };
-		},
-		leafDirective(node) {
-			if (node.data !== undefined) return;
-			return {
-				type: 'paragraph',
-				children: [{ type: 'text', value: serializeDirective(node) }],
-			};
-		},
-		containerDirective(node) {
-			if (node.data !== undefined) return;
-			return paragraphElement('div', {}, [...node.children]);
-		},
-	};
-}
-
-function paragraphElement(
-	tagName: string,
-	properties: Properties,
-	children: unknown[] = []
-): Paragraph {
-	return {
-		type: 'paragraph',
-		data: { hName: tagName, hProperties: properties },
-		children: children as Paragraph['children'],
-	};
-}
-
-/** Convert `:::variant` directive blocks into styled asides. */
-function satteriAsidesPlugin(
-	options: MarkdownProcessorPluginOptions,
-	allowedPaths: string[]
-): MdastPluginDefinition {
-	return {
-		name: 'starlight-asides',
-		containerDirective(node, ctx) {
-			if (!shouldTransformPath(ctx.fileURL, allowedPaths)) return;
-			if (!isAsideVariant(node.name)) return;
-
-			const variant = node.name;
-			// `shouldTransformPath` above already returned for a missing `fileURL`.
-			const filename = fileURLToPath(ctx.fileURL!);
-			const t = options.useTranslations(options.absolutePathToLang(filename));
-
-			let title = t(`aside.${variant}`);
-			let titleNode: unknown[] = [{ type: 'text', value: title }];
-			const children = [...node.children];
-			const firstChild = children[0];
-			if (
-				firstChild?.type === 'paragraph' &&
-				firstChild.data?.directiveLabel &&
-				firstChild.children.length > 0
-			) {
-				titleNode = firstChild.children;
-				title = ctx.textContent(firstChild);
-				children.shift();
-			}
-
-			const icon = getAsideIcon(variant, node.attributes?.['icon']);
-			const iconSvg = `<svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon">${icon}</svg>`;
-			// Markdown and MDX require different AST shapes for raw HTML content.
-			// TODO: replace endsWith check with an official Sätteri API once available.
-			const iconNode = ctx.fileURL?.pathname.endsWith('.mdx')
-				? {
-						type: 'mdxJsxTextElement',
-						name: 'Fragment',
-						attributes: [{ type: 'mdxJsxAttribute', name: 'set:html', value: iconSvg }],
-					}
-				: { type: 'html', value: iconSvg };
-
-			return paragraphElement(
-				'aside',
-				{
-					'aria-label': title,
-					class: `starlight-aside starlight-aside--${variant}`,
-				},
-				[
-					paragraphElement('p', { class: 'starlight-aside__title', 'aria-hidden': 'true' }, [
-						iconNode,
-						...titleNode,
-					]),
-					paragraphElement('div', { class: 'starlight-aside__content' }, children),
-				]
-			);
-		},
-	};
-}
-
-function serializeDirective(node: Parameters<typeof toMarkdown>[0]): string {
-	const md = toMarkdown(node, { extensions: [directiveToMarkdown()] });
-	return md.at(-1) === '\n' ? md.slice(0, -1) : md;
-}
-
-function satteriRtlCodeSupportPlugin(allowedPaths: string[]): HastPluginDefinition {
-	return {
-		name: 'starlight-rtl-code-support',
-		element: [
-			{
-				filter: ['pre'],
-				visit(node, ctx) {
-					if (!shouldTransformPath(ctx.fileURL, allowedPaths)) return;
-					if (node.properties && 'dir' in node.properties) return;
-					ctx.setProperty(node, 'dir', 'ltr');
-				},
-			},
-			{
-				filter: ['code'],
-				visit(node, ctx) {
-					if (
-						shouldTransformPath(ctx.fileURL, allowedPaths) &&
-						!(node.properties && 'dir' in node.properties) &&
-						!hasPreParent(node, ctx)
-					) {
-						ctx.setProperty(node, 'dir', 'auto');
-					}
-				},
-			},
-		],
-		// Shiki runs ahead of us and replaces the highlighted `<pre>` element with a raw HTML
-		// node, so the `pre` element visitor above never sees it. Patch the raw markup instead.
-		raw(node, ctx) {
-			if (!shouldTransformPath(ctx.fileURL, allowedPaths)) return undefined;
-			const value = ltrRawPre(node.value);
-			if (value === null) return undefined;
-			return { type: 'raw', value };
-		},
-	};
-}
-
-/**
- * Check if any parent of `child` is a `<pre>` element by walking up the tree.
- */
-function hasPreParent(child: Readonly<Parents> | undefined, ctx: HastVisitorContext): boolean {
-	while (child) {
-		const parent: Readonly<Parents> | undefined = ctx.parent(child);
-		if (parent?.type === 'element' && parent.tagName === 'pre') return true;
-		child = parent;
-	}
-	return false;
-}
-
-const rawPreOpenTag = /<pre(?=[\s>])[^>]*>/;
-
-/**
- * Add `dir="ltr"` to the opening tag of a raw `<pre>` HTML string, unless it already declares a
- * `dir`. Returns `null` when the value isn’t a `<pre>`, leaving unrelated raw HTML untouched.
- */
-function ltrRawPre(value: string): string | null {
-	const openTag = value.match(rawPreOpenTag)?.[0];
-	if (!openTag || /\sdir\s*=/.test(openTag)) return null;
-	return value.replace(openTag, () => `<pre dir="ltr"${openTag.slice(4)}`);
-}
-
-function satteriAutolinkHeadingsPlugin(
-	options: MarkdownProcessorPluginOptions,
-	allowedPaths: string[]
-): HastPluginDefinition {
-	return {
-		name: 'starlight-autolink-headings',
-		element: {
-			filter: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
-			visit(node, ctx) {
-				if (!shouldTransformPath(ctx.fileURL, allowedPaths)) return;
-
-				const id = node.properties?.['id'];
-				if (typeof id !== 'string' || !id) return;
-
-				const title = ctx.textContent(node);
-				// `shouldTransformPath` above already returned for a missing `fileURL`.
-				const filename = fileURLToPath(ctx.fileURL!);
-				const t = options.useTranslations(options.absolutePathToLang(filename));
-				const accessibleLabel = t('heading.anchorLabel', {
-					title,
-					interpolation: { escapeValue: false },
-				});
-
-				return {
-					type: 'element',
-					tagName: 'div',
-					properties: { class: `sl-heading-wrapper level-${node.tagName}` },
-					children: [
-						node,
-						{
-							type: 'element',
-							tagName: 'a',
-							properties: { class: 'sl-anchor-link', href: '#' + id },
-							children: [
-								{
-									type: 'element',
-									tagName: 'span',
-									properties: { 'aria-hidden': 'true', class: 'sl-anchor-icon' },
-									children: [
-										{
-											type: 'element',
-											tagName: 'svg',
-											properties: {
-												width: '16',
-												height: '16',
-												viewBox: '0 0 24 24',
-												fill: 'currentColor',
-											},
-											children: headingLinkIconChildren,
-										},
-									],
-								},
-								{
-									type: 'element',
-									tagName: 'span',
-									properties: { class: 'sr-only', 'data-pagefind-ignore': true },
-									children: [{ type: 'text', value: accessibleLabel }],
-								},
-							],
-						},
-					],
-				};
-			},
-		},
-	};
-}

package/integrations/shared/absolutePathToLang.ts

@@ -1,26 +0,0 @@
-import type { StarlightConfig } from '../../types';
-import { localeToLang } from './localeToLang';
-import { slugToLocale } from './slugToLocale';
-
-/** Get current language from an absolute file path. */
-export function absolutePathToLang(
-	path: string,
-	{
-		docsPath,
-		starlightConfig,
-	}: {
-		docsPath: string;
-		starlightConfig: Pick<StarlightConfig, 'defaultLocale' | 'locales'>;
-	}
-): string {
-	// Format path to unix style path.
-	path = path?.replace(/\\/g, '/');
-	// Ensure that the page path starts with a slash if the docs directory also does,
-	// which makes stripping the docs path in the next step work on Windows, too.
-	if (path && !path.startsWith('/') && docsPath.startsWith('/')) path = '/' + path;
-	// Strip docs path leaving only content collection file ID.
-	// Example: /Users/houston/repo/src/content/docs/en/guide.md => en/guide.md
-	const slug = path?.replace(docsPath, '');
-	const locale = slugToLocale(slug, starlightConfig);
-	return localeToLang(starlightConfig, locale);
-}

package/integrations/shared/localeToLang.ts

@@ -1,15 +0,0 @@
-import type { StarlightConfig } from '../../types';
-import { BuiltInDefaultLocale } from '../../utils/i18n';
-
-/**
- * Get the BCP-47 language tag for the given locale.
- * @param locale Locale string or `undefined` for the root locale.
- */
-export function localeToLang(
-	config: Pick<StarlightConfig, 'defaultLocale' | 'locales'>,
-	locale: string | undefined
-): string {
-	const lang = locale ? config.locales?.[locale]?.lang : config.locales?.root?.lang;
-	const defaultLang = config.defaultLocale?.lang || config.defaultLocale?.locale;
-	return lang || defaultLang || BuiltInDefaultLocale.lang;
-}

package/integrations/shared/slugToLocale.ts

@@ -1,18 +0,0 @@
-import type { StarlightConfig } from '../../types';
-
-/**
- * Get the “locale” of a slug. This is the base path at which a language is served.
- * For example, if French docs are in `src/content/docs/french/`, the locale is `french`.
- * Root locale slugs will return `undefined`.
- * @param slug A collection entry slug
- */
-export function slugToLocale(
-	slug: string | undefined,
-	config: Pick<StarlightConfig, 'defaultLocale' | 'locales'>
-): string | undefined {
-	const localesConfig = config.locales ?? {};
-	const baseSegment = slug?.split('/')[0];
-	if (baseSegment && localesConfig[baseSegment]) return baseSegment;
-	if (!localesConfig.root) return config.defaultLocale.locale;
-	return undefined;
-}

package/integrations/sitemap.ts

@@ -1,23 +0,0 @@
-import sitemap, { type SitemapOptions } from '@astrojs/sitemap';
-import type { StarlightConfig } from '../types';
-
-export function getSitemapConfig(opts: StarlightConfig): SitemapOptions {
-	const sitemapConfig: SitemapOptions = {};
-	if (opts.isMultilingual) {
-		sitemapConfig.i18n = {
-			defaultLocale: opts.defaultLocale.locale || 'root',
-			locales: Object.fromEntries(
-				Object.entries(opts.locales).map(([locale, config]) => [locale, config!.lang!])
-			),
-		};
-	}
-	return sitemapConfig;
-}
-
-/**
- * A wrapped version of the `@astrojs/sitemap` integration configured based
- * on Starlight i18n config.
- */
-export function starlightSitemap(opts: StarlightConfig) {
-	return sitemap(getSitemapConfig(opts));
-}