@astrojs/starlight 0.5.6 → 0.6.1

package/utils/user-config.ts

@@ -3,320 +3,324 @@ import { parse as bcpParse, stringify as bcpStringify } from 'bcp-47';
 import { HeadConfigSchema } from '../schemas/head';
 import { LogoConfigSchema } from '../schemas/logo';
 import { TableOfContentsSchema } from '../schemas/tableOfContents';
+import { FaviconSchema } from '../schemas/favicon';
 
 const LocaleSchema = z.object({
-  /** The label for this language to show in UI, e.g. `"English"`, `"العربية"`, or `"简体中文"`. */
-  label: z
-    .string()
-    .describe(
-      'The label for this language to show in UI, e.g. `"English"`, `"العربية"`, or `"简体中文"`.'
-    ),
-  /** The BCP-47 tag for this language, e.g. `"en"`, `"ar"`, or `"zh-CN"`. */
-  lang: z
-    .string()
-    .optional()
-    .describe(
-      'The BCP-47 tag for this language, e.g. `"en"`, `"ar"`, or `"zh-CN"`.'
-    ),
-  /** The writing direction of this language; `"ltr"` for left-to-right (the default) or `"rtl"` for right-to-left. */
-  dir: z
-    .enum(['rtl', 'ltr'])
-    .optional()
-    .default('ltr')
-    .describe(
-      'The writing direction of this language; `"ltr"` for left-to-right (the default) or `"rtl"` for right-to-left.'
-    ),
+	/** The label for this language to show in UI, e.g. `"English"`, `"العربية"`, or `"简体中文"`. */
+	label: z
+		.string()
+		.describe(
+			'The label for this language to show in UI, e.g. `"English"`, `"العربية"`, or `"简体中文"`.'
+		),
+	/** The BCP-47 tag for this language, e.g. `"en"`, `"ar"`, or `"zh-CN"`. */
+	lang: z
+		.string()
+		.optional()
+		.describe('The BCP-47 tag for this language, e.g. `"en"`, `"ar"`, or `"zh-CN"`.'),
+	/** The writing direction of this language; `"ltr"` for left-to-right (the default) or `"rtl"` for right-to-left. */
+	dir: z
+		.enum(['rtl', 'ltr'])
+		.optional()
+		.default('ltr')
+		.describe(
+			'The writing direction of this language; `"ltr"` for left-to-right (the default) or `"rtl"` for right-to-left.'
+		),
 });
 
 const SidebarBaseSchema = z.object({
-  /** The visible label for this item in the sidebar. */
-  label: z.string(),
-  /** Translations of the `label` for each supported language. */
-  translations: z.record(z.string()).default({}),
+	/** The visible label for this item in the sidebar. */
+	label: z.string(),
+	/** Translations of the `label` for each supported language. */
+	translations: z.record(z.string()).default({}),
 });
 
 const SidebarGroupSchema = SidebarBaseSchema.extend({
-  /** Whether this item should be collapsed by default. */
-  collapsed: z.boolean().default(false),
+	/** Whether this item should be collapsed by default. */
+	collapsed: z.boolean().default(false),
 });
 
 const SidebarLinkItemSchema = SidebarBaseSchema.extend({
-  /** The link to this item’s content. Can be a relative link to local files or the full URL of an external page. */
-  link: z.string(),
+	/** The link to this item’s content. Can be a relative link to local files or the full URL of an external page. */
+	link: z.string(),
 });
 export type SidebarLinkItem = z.infer<typeof SidebarLinkItemSchema>;
 
 const AutoSidebarGroupSchema = SidebarGroupSchema.extend({
-  /** Enable autogenerating a sidebar category from a specific docs directory. */
-  autogenerate: z.object({
-    /** The directory to generate sidebar items for. */
-    directory: z.string(),
-    /**
-     * Whether the autogenerated subgroups should be collapsed by default.
-     * Defaults to the `AutoSidebarGroup` `collapsed` value.
-     */
-    collapsed: z.boolean().optional(),
-    // TODO: not supported by Docusaurus but would be good to have
-    /** How many directories deep to include from this directory in the sidebar. Default: `Infinity`. */
-    // depth: z.number().optional(),
-  }),
+	/** Enable autogenerating a sidebar category from a specific docs directory. */
+	autogenerate: z.object({
+		/** The directory to generate sidebar items for. */
+		directory: z.string(),
+		/**
+		 * Whether the autogenerated subgroups should be collapsed by default.
+		 * Defaults to the `AutoSidebarGroup` `collapsed` value.
+		 */
+		collapsed: z.boolean().optional(),
+		// TODO: not supported by Docusaurus but would be good to have
+		/** How many directories deep to include from this directory in the sidebar. Default: `Infinity`. */
+		// depth: z.number().optional(),
+	}),
 });
 export type AutoSidebarGroup = z.infer<typeof AutoSidebarGroupSchema>;
 
 type ManualSidebarGroupInput = z.input<typeof SidebarGroupSchema> & {
-  /** Array of links and subcategories to display in this category. */
-  items: Array<
-    | z.input<typeof SidebarLinkItemSchema>
-    | z.input<typeof AutoSidebarGroupSchema>
-    | ManualSidebarGroupInput
-  >;
+	/** Array of links and subcategories to display in this category. */
+	items: Array<
+		| z.input<typeof SidebarLinkItemSchema>
+		| z.input<typeof AutoSidebarGroupSchema>
+		| ManualSidebarGroupInput
+	>;
 };
 
 type ManualSidebarGroupOutput = z.output<typeof SidebarGroupSchema> & {
-  /** Array of links and subcategories to display in this category. */
-  items: Array<
-    | z.output<typeof SidebarLinkItemSchema>
-    | z.output<typeof AutoSidebarGroupSchema>
-    | ManualSidebarGroupOutput
-  >;
+	/** Array of links and subcategories to display in this category. */
+	items: Array<
+		| z.output<typeof SidebarLinkItemSchema>
+		| z.output<typeof AutoSidebarGroupSchema>
+		| ManualSidebarGroupOutput
+	>;
 };
 
 const ManualSidebarGroupSchema: z.ZodType<
-  ManualSidebarGroupOutput,
-  z.ZodTypeDef,
-  ManualSidebarGroupInput
+	ManualSidebarGroupOutput,
+	z.ZodTypeDef,
+	ManualSidebarGroupInput
 > = SidebarGroupSchema.extend({
-  /** Array of links and subcategories to display in this category. */
-  items: z.lazy(() =>
-    z
-      .union([
-        SidebarLinkItemSchema,
-        ManualSidebarGroupSchema,
-        AutoSidebarGroupSchema,
-      ])
-      .array()
-  ),
+	/** Array of links and subcategories to display in this category. */
+	items: z.lazy(() =>
+		z.union([SidebarLinkItemSchema, ManualSidebarGroupSchema, AutoSidebarGroupSchema]).array()
+	),
 });
 
 const SidebarItemSchema = z.union([
-  SidebarLinkItemSchema,
-  ManualSidebarGroupSchema,
-  AutoSidebarGroupSchema,
+	SidebarLinkItemSchema,
+	ManualSidebarGroupSchema,
+	AutoSidebarGroupSchema,
 ]);
 export type SidebarItem = z.infer<typeof SidebarItemSchema>;
 
 const UserConfigSchema = z.object({
-  /** Title for your website. Will be used in metadata and as browser tab title. */
-  title: z
-    .string()
-    .describe(
-      'Title for your website. Will be used in metadata and as browser tab title.'
-    ),
-
-  /** Description metadata for your website. Can be used in page metadata. */
-  description: z
-    .string()
-    .optional()
-    .describe(
-      'Description metadata for your website. Can be used in page metadata.'
-    ),
-
-  /** Set a logo image to show in the navigation bar alongside or instead of the site title. */
-  logo: LogoConfigSchema(),
-
-  /** Optional details about the social media accounts for this site. */
-  social: z
-    .object({
-      /** Link to the main Twitter profile for this site, e.g. `'https://twitter.com/astrodotbuild'`. */
-      twitter: z.string().url().optional(),
-      /** Link to the main Mastodon profile for this site, e.g. `'https://m.webtoo.ls/@astro'`. */
-      mastodon: z.string().url().optional(),
-      /** Link to the main GitHub org or repo for this site, e.g. `'https://github.com/withastro/starlight'`. */
-      github: z.string().url().optional(),
-      /** Link to the Discord server for this site, e.g. `'https://astro.build/chat'`. */
-      discord: z.string().url().optional(),
-      /** Link to the Codeberg profile or repository for this site, e.g. `'https://codeberg.org/knut/examples'`. */
-      codeberg: z.string().url().optional(),
-      /** Link to the Youtube channel for this site, e.g. `'https://www.youtube.com/@astrodotbuild'`. */
-      youtube: z.string().url().optional(),
-      /** Link to the Threads profile for this site, e.g. `'https://www.threads.net/@nmoodev'`. */
-      threads: z.string().url().optional(),
-      /** Link to the LinkedIn page for this site, e.g. `'https://www.linkedin.com/company/astroinc'`. */
-      linkedin: z.string().url().optional(),
-      /** Link to the Twitch profile or repository for this site, e.g. `'https://www.twitch.tv/bholmesdev'`. */
-      twitch: z.string().url().optional(),
-    })
-    .optional(),
-
-  /** The tagline for your website. */
-  tagline: z.string().optional().describe('The tagline for your website.'),
-
-  /** Configure the defaults for the table of contents on each page. */
-  tableOfContents: TableOfContentsSchema(),
-
-  /** Enable and configure “Edit this page” links. */
-  editLink: z
-    .object({
-      /** Set the base URL for edit links. The final link will be `baseUrl` + the current page path. */
-      baseUrl: z.string().url().optional(),
-    })
-    .optional()
-    .default({}),
-
-  /** Configure locales for internationalization (i18n). */
-  locales: z
-    .object({
-      /** Configure a “root” locale to serve a default language from `/`. */
-      root: LocaleSchema.required({ lang: true }).optional(),
-    })
-    .catchall(LocaleSchema)
-    .transform((locales, ctx) => {
-      for (const key in locales) {
-        const locale = locales[key]!;
-        // Fall back to the key in the locales object as the lang.
-        let lang = locale.lang || key;
-
-        // Parse the lang tag so we can check it is valid according to BCP-47.
-        const schema = bcpParse(lang, { forgiving: true });
-        schema.region = schema.region?.toUpperCase();
-        const normalizedLang = bcpStringify(schema);
-
-        // Error if parsing the language tag failed.
-        if (!normalizedLang) {
-          ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `Could not validate language tag "${lang}" at locales.${key}.lang.`,
-          });
-          return z.NEVER;
-        }
-
-        // Let users know we’re modifying their configured `lang`.
-        if (normalizedLang !== lang) {
-          console.warn(
-            `Warning: using "${normalizedLang}" language tag for locales.${key}.lang instead of "${lang}".`
-          );
-          lang = normalizedLang;
-        }
-
-        // Set the final value as the normalized lang, based on the key if needed.
-        locale.lang = lang;
-      }
-      return locales;
-    })
-    .optional()
-    .describe('Configure locales for internationalization (i18n).'),
-
-  /**
-   * Specify the default language for this site.
-   *
-   * The default locale will be used to provide fallback content where translations are missing.
-   */
-  defaultLocale: z.string().optional(),
-
-  /** Configure your site’s sidebar navigation items. */
-  sidebar: SidebarItemSchema.array().optional(),
-
-  /**
-   * Add extra tags to your site’s `<head>`.
-   *
-   * Can also be set for a single page in a page’s frontmatter.
-   *
-   * @example
-   * // Add Fathom analytics to your site
-   * starlight({
-   *  head: [
-   *    {
-   *      tag: 'script',
-   *      attrs: {
-   *        src: 'https://cdn.usefathom.com/script.js',
-   *        'data-site': 'MY-FATHOM-ID',
-   *        defer: true,
-   *      },
-   *    },
-   *  ],
-   * })
-   */
-  head: HeadConfigSchema(),
-
-  /**
-   * Provide CSS files to customize the look and feel of your Starlight site.
-   *
-   * Supports local CSS files relative to the root of your project,
-   * e.g. `'/src/custom.css'`, and CSS you installed as an npm
-   * module, e.g. `'@fontsource/roboto'`.
-   *
-   * @example
-   * starlight({
-   *  customCss: ['/src/custom-styles.css', '@fontsource/roboto'],
-   * })
-   */
-  customCss: z.string().array().optional().default([]),
-
-  /** Define if the last update date should be visible in the page footer. */
-  lastUpdated: z
-    .boolean()
-    .default(false)
-    .describe(
-      'Define if the last update date should be visible in the page footer.'
-    ),
-
-  /** Define if the previous and next page links should be visible in the page footer. */
-  pagination: z
-    .boolean()
-    .default(true)
-    .describe(
-      'Define if the previous and next page links should be visible in the page footer.'
-    ),
+	/** Title for your website. Will be used in metadata and as browser tab title. */
+	title: z
+		.string()
+		.describe('Title for your website. Will be used in metadata and as browser tab title.'),
+
+	/** Description metadata for your website. Can be used in page metadata. */
+	description: z
+		.string()
+		.optional()
+		.describe('Description metadata for your website. Can be used in page metadata.'),
+
+	/** Set a logo image to show in the navigation bar alongside or instead of the site title. */
+	logo: LogoConfigSchema(),
+
+	/**
+	 * Optional details about the social media accounts for this site.
+	 *
+	 * @example
+	 * social: {
+	 *   codeberg: 'https://codeberg.org/knut/examples',
+	 *   discord: 'https://astro.build/chat',
+	 *   github: 'https://github.com/withastro/starlight',
+	 *   gitlab: 'https://gitlab.com/delucis',
+	 *   linkedin: 'https://www.linkedin.com/company/astroinc',
+	 *   mastodon: 'https://m.webtoo.ls/@astro',
+	 *   threads: 'https://www.threads.net/@nmoodev',
+	 *   twitch: 'https://www.twitch.tv/bholmesdev',
+	 *   twitter: 'https://twitter.com/astrodotbuild',
+	 *   youtube: 'https://youtube.com/@astrodotbuild',
+	 * }
+	 */
+	social: z
+		.record(
+			z.enum([
+				'twitter',
+				'mastodon',
+				'github',
+				'gitlab',
+				'bitbucket',
+				'discord',
+				'gitter',
+				'codeberg',
+				'codePen',
+				'youtube',
+				'threads',
+				'linkedin',
+				'twitch',
+				'microsoftTeams',
+			]),
+			// Link to the respective social profile for this site
+			z.string().url()
+		)
+		.optional(),
+
+	/** The tagline for your website. */
+	tagline: z.string().optional().describe('The tagline for your website.'),
+
+	/** Configure the defaults for the table of contents on each page. */
+	tableOfContents: TableOfContentsSchema(),
+
+	/** Enable and configure “Edit this page” links. */
+	editLink: z
+		.object({
+			/** Set the base URL for edit links. The final link will be `baseUrl` + the current page path. */
+			baseUrl: z.string().url().optional(),
+		})
+		.optional()
+		.default({}),
+
+	/** Configure locales for internationalization (i18n). */
+	locales: z
+		.object({
+			/** Configure a “root” locale to serve a default language from `/`. */
+			root: LocaleSchema.required({ lang: true }).optional(),
+		})
+		.catchall(LocaleSchema)
+		.transform((locales, ctx) => {
+			for (const key in locales) {
+				const locale = locales[key]!;
+				// Fall back to the key in the locales object as the lang.
+				let lang = locale.lang || key;
+
+				// Parse the lang tag so we can check it is valid according to BCP-47.
+				const schema = bcpParse(lang, { forgiving: true });
+				schema.region = schema.region?.toUpperCase();
+				const normalizedLang = bcpStringify(schema);
+
+				// Error if parsing the language tag failed.
+				if (!normalizedLang) {
+					ctx.addIssue({
+						code: z.ZodIssueCode.custom,
+						message: `Could not validate language tag "${lang}" at locales.${key}.lang.`,
+					});
+					return z.NEVER;
+				}
+
+				// Let users know we’re modifying their configured `lang`.
+				if (normalizedLang !== lang) {
+					console.warn(
+						`Warning: using "${normalizedLang}" language tag for locales.${key}.lang instead of "${lang}".`
+					);
+					lang = normalizedLang;
+				}
+
+				// Set the final value as the normalized lang, based on the key if needed.
+				locale.lang = lang;
+			}
+			return locales;
+		})
+		.optional()
+		.describe('Configure locales for internationalization (i18n).'),
+
+	/**
+	 * Specify the default language for this site.
+	 *
+	 * The default locale will be used to provide fallback content where translations are missing.
+	 */
+	defaultLocale: z.string().optional(),
+
+	/** Configure your site’s sidebar navigation items. */
+	sidebar: SidebarItemSchema.array().optional(),
+
+	/**
+	 * Add extra tags to your site’s `<head>`.
+	 *
+	 * Can also be set for a single page in a page’s frontmatter.
+	 *
+	 * @example
+	 * // Add Fathom analytics to your site
+	 * starlight({
+	 *  head: [
+	 *    {
+	 *      tag: 'script',
+	 *      attrs: {
+	 *        src: 'https://cdn.usefathom.com/script.js',
+	 *        'data-site': 'MY-FATHOM-ID',
+	 *        defer: true,
+	 *      },
+	 *    },
+	 *  ],
+	 * })
+	 */
+	head: HeadConfigSchema(),
+
+	/**
+	 * Provide CSS files to customize the look and feel of your Starlight site.
+	 *
+	 * Supports local CSS files relative to the root of your project,
+	 * e.g. `'/src/custom.css'`, and CSS you installed as an npm
+	 * module, e.g. `'@fontsource/roboto'`.
+	 *
+	 * @example
+	 * starlight({
+	 *  customCss: ['/src/custom-styles.css', '@fontsource/roboto'],
+	 * })
+	 */
+	customCss: z.string().array().optional().default([]),
+
+	/** Define if the last update date should be visible in the page footer. */
+	lastUpdated: z
+		.boolean()
+		.default(false)
+		.describe('Define if the last update date should be visible in the page footer.'),
+
+	/** Define if the previous and next page links should be visible in the page footer. */
+	pagination: z
+		.boolean()
+		.default(true)
+		.describe('Define if the previous and next page links should be visible in the page footer.'),
+
+	/** The default favicon for your site which should be a path to an image in the `public/` directory. */
+	favicon: FaviconSchema(),
 });
 
 export const StarlightConfigSchema = UserConfigSchema.strict().transform(
-  ({ locales, defaultLocale, ...config }, ctx) => {
-    if (locales !== undefined && Object.keys(locales).length > 1) {
-      // This is a multilingual site (more than one locale configured).
-      // Make sure we can find the default locale and if not, help the user set it.
-      // We treat the root locale as the default if present and no explicit default is set.
-      const defaultLocaleConfig = locales[defaultLocale || 'root'];
-
-      if (!defaultLocaleConfig) {
-        const availableLocales = Object.keys(locales)
-          .map((l) => `"${l}"`)
-          .join(', ');
-        ctx.addIssue({
-          code: 'custom',
-          message:
-            'Could not determine the default locale. ' +
-            'Please make sure `defaultLocale` in your Starlight config is one of ' +
-            availableLocales,
-        });
-        return z.NEVER;
-      }
-
-      return {
-        ...config,
-        /** Flag indicating if this site has multiple locales set up. */
-        isMultilingual: true,
-        /** Full locale object for this site’s default language. */
-        defaultLocale: { ...defaultLocaleConfig, locale: defaultLocale },
-        locales,
-      } as const;
-    }
-
-    // This is a monolingual site, so things are pretty simple.
-    return {
-      ...config,
-      /** Flag indicating if this site has multiple locales set up. */
-      isMultilingual: false,
-      /** Full locale object for this site’s default language. */
-      defaultLocale: {
-        label: 'English',
-        lang: 'en',
-        dir: 'ltr',
-        locale: undefined,
-        ...locales?.root,
-      },
-      locales: undefined,
-    } as const;
-  }
+	({ locales, defaultLocale, ...config }, ctx) => {
+		if (locales !== undefined && Object.keys(locales).length > 1) {
+			// This is a multilingual site (more than one locale configured).
+			// Make sure we can find the default locale and if not, help the user set it.
+			// We treat the root locale as the default if present and no explicit default is set.
+			const defaultLocaleConfig = locales[defaultLocale || 'root'];
+
+			if (!defaultLocaleConfig) {
+				const availableLocales = Object.keys(locales)
+					.map((l) => `"${l}"`)
+					.join(', ');
+				ctx.addIssue({
+					code: 'custom',
+					message:
+						'Could not determine the default locale. ' +
+						'Please make sure `defaultLocale` in your Starlight config is one of ' +
+						availableLocales,
+				});
+				return z.NEVER;
+			}
+
+			return {
+				...config,
+				/** Flag indicating if this site has multiple locales set up. */
+				isMultilingual: true,
+				/** Full locale object for this site’s default language. */
+				defaultLocale: { ...defaultLocaleConfig, locale: defaultLocale },
+				locales,
+			} as const;
+		}
+
+		// This is a monolingual site, so things are pretty simple.
+		return {
+			...config,
+			/** Flag indicating if this site has multiple locales set up. */
+			isMultilingual: false,
+			/** Full locale object for this site’s default language. */
+			defaultLocale: {
+				label: 'English',
+				lang: 'en',
+				dir: 'ltr',
+				locale: undefined,
+				...locales?.root,
+			},
+			locales: undefined,
+		} as const;
+	}
 );
 
 export type StarlightConfig = z.infer<typeof StarlightConfigSchema>;

package/virtual.d.ts

@@ -1,17 +1,17 @@
 declare module 'virtual:starlight/user-config' {
-  const Config: import('./types').StarlightConfig;
-  export default Config;
+	const Config: import('./types').StarlightConfig;
+	export default Config;
 }
 declare module 'virtual:starlight/project-context' {
-  export default { root: string };
+	export default { root: string };
 }
 
 declare module 'virtual:starlight/user-css' {}
 
 declare module 'virtual:starlight/user-images' {
-  type ImageMetadata = import('astro').ImageMetadata;
-  export const logos: {
-    dark?: ImageMetadata;
-    light?: ImageMetadata;
-  };
+	type ImageMetadata = import('astro').ImageMetadata;
+	export const logos: {
+		dark?: ImageMetadata;
+		light?: ImageMetadata;
+	};
 }