@astrojs/starlight 0.41.10 → 0.42.0

package/integrations/expressive-code/theming.ts

@@ -1,105 +0,0 @@
-import { ExpressiveCodeTheme, type ThemeObjectOrShikiThemeName } from 'astro-expressive-code';
-import nightOwlDark from './themes/night-owl-dark.jsonc?raw';
-import nightOwlLight from './themes/night-owl-light.jsonc?raw';
-
-export type BundledThemeName = 'starlight-dark' | 'starlight-light';
-
-export type ThemeObjectOrBundledThemeName = ThemeObjectOrShikiThemeName | BundledThemeName;
-
-/**
- * Converts the Starlight `themes` config option into a format understood by Expressive Code,
- * loading any bundled themes and using the Starlight defaults if no themes were provided.
- */
-export function preprocessThemes(
-	themes: ThemeObjectOrBundledThemeName[] | undefined
-): ThemeObjectOrShikiThemeName[] {
-	// Try to gracefully handle cases where the user forgot to use an array in the config
-	themes = themes && !Array.isArray(themes) ? [themes] : themes;
-	// If no themes were provided, use our bundled default themes
-	if (!themes || !themes.length) themes = ['starlight-dark', 'starlight-light'];
-
-	return themes.map((theme) => {
-		// If the current entry is the name of a bundled theme, load it
-		if (theme === 'starlight-dark' || theme === 'starlight-light') {
-			const bundledTheme = theme === 'starlight-dark' ? nightOwlDark : nightOwlLight;
-			return customizeBundledTheme(ExpressiveCodeTheme.fromJSONString(bundledTheme));
-		}
-		// Otherwise, just pass it through
-		return theme;
-	});
-}
-
-/**
- * Customizes some settings of the bundled theme to make it fit better with Starlight.
- */
-function customizeBundledTheme(theme: ExpressiveCodeTheme) {
-	theme.colors['titleBar.border'] = theme.colors['tab.activeBackground'];
-	theme.colors['editorGroupHeader.tabsBorder'] = theme.colors['tab.activeBackground'];
-
-	// Add underline font style to link syntax highlighting tokens
-	// to match the new GitHub theme link style
-	theme.settings.forEach((s) => {
-		if (s.name?.includes('Link')) s.settings.fontStyle = 'underline';
-	});
-
-	return theme;
-}
-
-/**
- * Modifies the given theme by applying Starlight's CSS variables to the colors of UI elements
- * (backgrounds, buttons, shadows etc.). This ensures that code blocks match the site's theme.
- */
-export function applyStarlightUiThemeColors(theme: ExpressiveCodeTheme) {
-	const isDark = theme.type === 'dark';
-	const neutralMinimal = isDark ? '#ffffff17' : '#0000001a';
-	const neutralDimmed = isDark ? '#ffffff40' : '#00000055';
-
-	// Make borders slightly transparent
-	const borderColor = 'color-mix(in srgb, var(--sl-color-gray-5), transparent 25%)';
-	theme.colors['titleBar.border'] = borderColor;
-	theme.colors['editorGroupHeader.tabsBorder'] = borderColor;
-
-	// Use the same color for terminal title bar background and editor tab bar background
-	const backgroundColor = isDark ? 'var(--sl-color-black)' : 'var(--sl-color-gray-6)';
-	theme.colors['titleBar.activeBackground'] = backgroundColor;
-	theme.colors['editorGroupHeader.tabsBackground'] = backgroundColor;
-
-	// Use the same color for terminal titles and tab titles
-	theme.colors['titleBar.activeForeground'] = 'var(--sl-color-text)';
-	theme.colors['tab.activeForeground'] = 'var(--sl-color-text)';
-
-	// Set tab border colors
-	const activeBorderColor = isDark ? 'var(--sl-color-accent-high)' : 'var(--sl-color-accent)';
-	theme.colors['tab.activeBorder'] = 'transparent';
-	theme.colors['tab.activeBorderTop'] = activeBorderColor;
-
-	// Use neutral colors for scrollbars
-	theme.colors['scrollbarSlider.background'] = neutralMinimal;
-	theme.colors['scrollbarSlider.hoverBackground'] = neutralDimmed;
-
-	// Set theme `bg` color property for contrast calculations
-	theme.bg = isDark ? '#23262f' : '#f6f7f9';
-	theme.colors['editor.background'] = theme.bg;
-	// Set actual background color to the appropriate Starlight CSS variable
-	const editorBackgroundColor = isDark ? 'var(--sl-color-gray-6)' : 'var(--sl-color-gray-7)';
-
-	theme.styleOverrides.frames = {
-		// Use the same color for editor background, terminal background and active tab background
-		editorBackground: editorBackgroundColor,
-		terminalBackground: editorBackgroundColor,
-		editorActiveTabBackground: editorBackgroundColor,
-		terminalTitlebarDotsForeground: borderColor,
-		terminalTitlebarDotsOpacity: '0.75',
-		inlineButtonForeground: 'var(--sl-color-text)',
-		frameBoxShadowCssValue: 'none',
-	};
-
-	// Use neutral, semi-transparent colors for default text markers
-	// to avoid conflicts with the user's chosen background color
-	theme.styleOverrides.textMarkers = {
-		markBackground: neutralMinimal,
-		markBorderColor: neutralDimmed,
-	};
-
-	return theme;
-}

package/integrations/expressive-code/translations.ts

@@ -1,36 +0,0 @@
-import { pluginFramesTexts } from 'astro-expressive-code';
-import type { StarlightConfig } from '../../types';
-import type { createTranslationSystemFromFs } from '../../utils/translations-fs';
-import { localeToLang } from '../shared/localeToLang';
-
-export function addTranslations(config: StarlightConfig, useTranslations: UseTranslations) {
-	addTranslationsForLocale(config.defaultLocale.locale, config, useTranslations);
-	if (config.isMultilingual) {
-		for (const locale in config.locales) {
-			if (locale === config.defaultLocale.locale || locale === 'root') continue;
-			addTranslationsForLocale(locale, config, useTranslations);
-		}
-	}
-}
-
-function addTranslationsForLocale(
-	locale: string | undefined,
-	config: StarlightConfig,
-	useTranslations: UseTranslations
-) {
-	const lang = localeToLang(config, locale);
-	const t = useTranslations(lang);
-	const translationKeys = [
-		'expressiveCode.copyButtonCopied',
-		'expressiveCode.copyButtonTooltip',
-		'expressiveCode.terminalWindowFallbackTitle',
-	] as const;
-	translationKeys.forEach((key) => {
-		const translation = t.exists(key) ? t(key) : undefined;
-		if (!translation) return;
-		const ecId = key.replace(/^expressiveCode\./, '');
-		pluginFramesTexts.overrideTexts(lang, { [ecId]: translation });
-	});
-}
-
-type UseTranslations = Awaited<ReturnType<typeof createTranslationSystemFromFs>>;

package/integrations/markdown-icon.ts

@@ -1,13 +0,0 @@
-import type { Element, ElementContent } from 'hast';
-import { fromHtml } from 'hast-util-from-html';
-import { Icons } from '../components-internals/Icons';
-
-export const headingLinkIconSvgChildrenHtml = Icons['link-alt'];
-export const headingLinkIconChildren = parseIconChildren(headingLinkIconSvgChildrenHtml);
-
-/** Parse a Starlight icon SVG fragment as children of an `<svg>` element. */
-export function parseIconChildren(icon: string): ElementContent[] {
-	const svg = fromHtml(`<svg>${icon}</svg>`, { fragment: true, space: 'svg' })
-		.children[0] as Element;
-	return svg.children;
-}

package/integrations/markdown-plugins.ts

@@ -1,71 +0,0 @@
-import { isSatteriProcessor } from '@astrojs/markdown-satteri';
-import type { AstroConfig, AstroIntegration, AstroIntegrationLogger } from 'astro';
-import type { MarkdownProcessorPluginOptions } from './markdown-processor';
-import { satteriDirectivesRestoration, starlightSatteriPlugins } from './satteri';
-
-// This file is imported by the Starlight integration that is used in Astro configuration files.
-// When using Starlight, Astro loads its configuration using a temporary Vite module runner and
-// closes it before running integration hooks. If this dynamic import is started later from an
-// integration hook, Vite tries to resolve it through that closed runner and throw "Vite module
-// runner has been closed".
-// We start loading `./remark-rehype` at the top level so Vite waits for it to resolve or fail
-// while the config runner is still running. This keeps the Unified integration optional as when
-// `@astrojs/markdown-remark` is not installed, importing `./remark-rehype` rejects and we resolve
-// it to `null`, which is later used to detect if Unified support is available or not.
-export const unifiedIntegration = import('./remark-rehype').catch(() => null);
-
-type UnifiedIntegration = Awaited<typeof unifiedIntegration>;
-type MarkdownProcessor = NonNullable<AstroConfig['markdown']['processor']>;
-
-/** Registers Starlight's Markdown transforms, picking the plugin set for the configured engine. */
-export function applyStarlightMarkdownPlugins(
-	processor: MarkdownProcessor,
-	options: MarkdownProcessorPluginOptions,
-	unified: UnifiedIntegration,
-	logger: Pick<AstroIntegrationLogger, 'warn'>
-) {
-	if (isSatteriProcessor(processor)) {
-		// Starlight's asides are built on container directives, which Sätteri disables by default.
-		processor.options.features.directive = true;
-		const { mdastPlugins, hastPlugins } = starlightSatteriPlugins(options);
-		processor.options.mdastPlugins.push(...mdastPlugins);
-		processor.options.hastPlugins.push(...hastPlugins);
-	} else if (unified?.isUnifiedProcessor(processor)) {
-		processor.options.remarkPlugins.push(...unified.starlightRemarkPlugins(options));
-		processor.options.rehypePlugins.push(...unified.starlightRehypePlugins(options));
-	} else {
-		logger.warn(
-			`The configured \`markdown.processor\` ("${processor.name}") is not supported by Starlight. ` +
-				"Starlight's Markdown transforms (asides, heading anchor links, RTL code support) won't run on your content. " +
-				'Switch to `satteri()` from `@astrojs/markdown-satteri` or `unified()` from `@astrojs/markdown-remark`.'
-		);
-	}
-}
-
-/** Registers the directive-restoration plugin. */
-export function registerDirectivesRestoration(
-	processor: MarkdownProcessor,
-	unified: UnifiedIntegration
-) {
-	if (isSatteriProcessor(processor)) {
-		processor.options.mdastPlugins.push(satteriDirectivesRestoration());
-	} else if (unified?.isUnifiedProcessor(processor)) {
-		processor.options.remarkPlugins.push(unified.remarkDirectivesRestoration);
-	}
-}
-
-/**
- * Run directive-restoration last so plugins added by Starlight plugins (via their own Astro
- * integrations) get to handle text/leaf directives first.
- */
-export function starlightDirectivesRestorationIntegration(): AstroIntegration {
-	return {
-		name: 'starlight-directives-restoration',
-		hooks: {
-			'astro:config:setup': async ({ config }) => {
-				const unified = await unifiedIntegration;
-				registerDirectivesRestoration(config.markdown?.processor, unified);
-			},
-		},
-	};
-}

package/integrations/markdown-processor.ts

@@ -1,64 +0,0 @@
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import type { AstroConfig } from 'astro';
-import { resolveCollectionPath } from '../utils/collection-fs';
-import { ensureTrailingSlash } from '../utils/path';
-import type { HookParameters, StarlightConfig } from '../types';
-
-/**
- * Options shared by the plugin factories of both Markdown processors Starlight supports (the unified
- * `remark`/`rehype` pipeline and Sätteri).
- */
-export interface MarkdownProcessorPluginOptions {
-	starlightConfig: Pick<StarlightConfig, 'defaultLocale' | 'locales' | 'markdown'>;
-	astroConfig: Pick<AstroConfig, 'root' | 'srcDir'>;
-	useTranslations: HookParameters<'config:setup'>['useTranslations'];
-	absolutePathToLang: HookParameters<'config:setup'>['absolutePathToLang'];
-}
-
-/**
- * Returns the paths to the Starlight docs collection and any additional paths defined in the
- * `starlightConfig.markdown.processedDirs` option that can be used with the {@link shouldTransformPath}
- * utility to determine if a file should be transformed by a plugin or not.
- */
-export function getMarkdownProcessorPaths(options: MarkdownProcessorPluginOptions): string[] {
-	const paths = [normalizeDirectoryPath(resolveCollectionPath('docs', options.astroConfig.srcDir))];
-
-	for (const processedDir of options.starlightConfig.markdown.processedDirs) {
-		paths.push(
-			normalizeDirectoryPath(resolve(fileURLToPath(options.astroConfig.root), processedDir))
-		);
-	}
-
-	return paths;
-}
-
-/**
- * Determines if a file should be transformed by a Markdown plugin, e.g. files without a known path
- * or files that are not part of the allowed paths are skipped. Accepts a path string (as the unified
- * pipeline exposes via `VFile`) or a `URL` (as Sätteri exposes via `ctx.fileURL`).
- */
-export function shouldTransformPath(path: string | URL | undefined, allowedPaths: string[]) {
-	if (!path) return false;
-	const normalizedPath = normalizePath(path instanceof URL ? fileURLToPath(path) : path);
-	return allowedPaths.some((p) => normalizedPath.startsWith(p));
-}
-
-/**
- * File path separators seems to be inconsistent on Windows between remark/rehype plugins used on
- * Markdown vs MDX files.
- * For the time being, we normalize all paths to unix style paths.
- */
-const backSlashRegex = /\\/g;
-function normalizePath(path: string) {
-	return path.replace(backSlashRegex, '/');
-}
-
-/**
- * Allowed paths are directory prefixes compared with `startsWith()` in {@link shouldTransformPath},
- * so we ensure they have a trailing slash to avoid matching sibling directories with the same
- * prefix.
- */
-function normalizeDirectoryPath(path: string) {
-	return ensureTrailingSlash(normalizePath(path));
-}

package/integrations/pagefind.ts

@@ -1,60 +0,0 @@
-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/integrations/rehype-code-rtl-support.ts

@@ -1,37 +0,0 @@
-import type { Root } from 'hast';
-import { CONTINUE, SKIP, visit } from 'unist-util-visit';
-import type { Transformer } from 'unified';
-import type { MarkdownProcessorPluginOptions } from './markdown-processor';
-
-/**
- * rehype plugin that adds `dir` attributes to `<code>` and `<pre>`
- * elements that don’t already have them.
- *
- * `<code>` will become `<code dir="auto">`
- * `<pre>` will become `<pre dir="ltr">`
- *
- * `<code>` _inside_ `<pre>` is skipped, so respects the `ltr` on its parent.
- *
- * Reasoning:
- * - `<pre>` is usually a code block and code should be LTR even in an RTL document
- * - `<code>` is often LTR, but could also be RTL. `dir="auto"` ensures the bidirectional
- *   algorithm treats the contents of `<code>` in isolation and gives its best guess.
- */
-export function rehypeRtlCodeSupport(_options: MarkdownProcessorPluginOptions) {
-	const transformer: Transformer<Root> = (tree) => {
-		visit(tree, 'element', (el) => {
-			if (el.tagName === 'pre' || el.tagName === 'code') {
-				el.properties ||= {};
-				if (!('dir' in el.properties)) {
-					el.properties.dir = { pre: 'ltr', code: 'auto' }[el.tagName];
-				}
-				return SKIP;
-			}
-			return CONTINUE;
-		});
-	};
-
-	return function attacher() {
-		return transformer;
-	};
-}

package/integrations/rehype-heading-links.ts

@@ -1,79 +0,0 @@
-import type { Nodes, Root } from 'hast';
-import { toString } from 'hast-util-to-string';
-import { h, s } from 'hastscript';
-import type { Transformer } from 'unified';
-import { SKIP, visit } from 'unist-util-visit';
-import { headingLinkIconChildren } from './markdown-icon';
-import type { MarkdownProcessorPluginOptions } from './markdown-processor';
-
-const AnchorLinkIcon = h(
-	'span',
-	{ ariaHidden: 'true', class: 'sl-anchor-icon' },
-	s(
-		'svg',
-		{ width: 16, height: 16, viewBox: '0 0 24 24', fill: 'currentColor' },
-		headingLinkIconChildren
-	)
-);
-
-/**
- * Add anchor links to headings.
- */
-export default function rehypeAutolinkHeadings({
-	absolutePathToLang,
-	useTranslations,
-}: MarkdownProcessorPluginOptions) {
-	const transformer: Transformer<Root> = (tree, file) => {
-		const pageLang = absolutePathToLang(file.path);
-		const t = useTranslations(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: '#' + String(node.properties.id) },
-					children: [
-						AnchorLinkIcon,
-						h('span', { class: 'sr-only', 'data-pagefind-ignore': true }, accessibleLabel),
-					],
-				}
-			);
-
-			return SKIP;
-		});
-	};
-
-	return function attacher() {
-		return transformer;
-	};
-}
-
-// 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;
-}