@astrojs/starlight 0.0.1

package/utils/navigation.ts

@@ -0,0 +1,232 @@
+import { basename, dirname } from 'node:path';
+import config from 'virtual:starlight/user-config';
+import { slugToPathname } from './slugs';
+import { Route, getLocaleRoutes, routes } from './routing';
+import type {
+  AutoSidebarGroup,
+  SidebarItem,
+  SidebarLinkItem,
+} from './user-config';
+
+export interface Link {
+  type: 'link';
+  label: string;
+  href: string;
+  isCurrent: boolean;
+}
+
+interface Group {
+  type: 'group';
+  label: string;
+  entries: (Link | Group)[];
+}
+
+export type SidebarEntry = Link | Group;
+
+/**
+ * A representation of the route structure. For each object entry:
+ * if it’s a folder, the key is the directory name, and value is the directory
+ * content; if it’s a route entry, the key is the last segment of the route, and value
+ * is the entry’s full slug.
+ */
+interface Dir {
+  [item: string]: Dir | string;
+}
+
+/** Convert an item in a user’s sidebar config to a sidebar entry. */
+function configItemToEntry(
+  item: SidebarItem,
+  currentPathname: string,
+  locale: string | undefined,
+  routes: Route[]
+): SidebarEntry {
+  if ('link' in item) {
+    return linkFromConfig(item, locale, currentPathname);
+  } else if ('autogenerate' in item) {
+    return groupFromAutogenerateConfig(item, locale, routes, currentPathname);
+  } else {
+    return {
+      type: 'group',
+      label: item.label,
+      entries: item.items.map((i) =>
+        configItemToEntry(i, currentPathname, locale, routes)
+      ),
+    };
+  }
+}
+
+/** Autogenerate a group of links from a user’s sidebar config. */
+function groupFromAutogenerateConfig(
+  item: AutoSidebarGroup,
+  locale: string | undefined,
+  routes: Route[],
+  currentPathname: string
+): Group {
+  const { directory } = item.autogenerate;
+  const localeDir = locale ? locale + '/' + directory : directory;
+  const dirDocs = routes.filter((doc) => doc.slug.startsWith(localeDir));
+  const tree = treeify(dirDocs, localeDir);
+  return {
+    type: 'group',
+    label: item.label,
+    entries: sidebarFromDir(tree, currentPathname, locale),
+  };
+}
+
+/** Check if a string starts with one of `http://` or `https://`. */
+const isAbsolute = (link: string) => /^https?:\/\//.test(link);
+
+/** Ensure the passed path starts and ends with trailing slashes. */
+function ensureLeadingAndTrailingSlashes(href: string): string {
+  if (href[0] !== '/') href = '/' + href;
+  if (href[href.length - 1] !== '/') href += '/';
+  return href;
+}
+
+/** Create a link entry from a user config object. */
+function linkFromConfig(
+  item: SidebarLinkItem,
+  locale: string | undefined,
+  currentPathname: string
+) {
+  let href = item.link;
+  if (!isAbsolute(href)) {
+    href = ensureLeadingAndTrailingSlashes(href);
+    // Inject current locale into link.
+    if (locale) href = '/' + locale + href;
+  }
+  return makeLink(href, item.label, currentPathname);
+}
+
+/** Create a link entry. */
+function makeLink(href: string, label: string, currentPathname: string): Link {
+  if (!isAbsolute(href)) {
+    href = ensureLeadingAndTrailingSlashes(href);
+    /** Base URL with trailing `/` stripped. */
+    const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+    if (base) href = base + href;
+  }
+  const isCurrent = href === currentPathname;
+  return { type: 'link', label, href, isCurrent };
+}
+
+/** Get the segments leading to a page. */
+function getBreadcrumbs(slug: string, baseDir: string): string[] {
+  // Ensure base directory ends in a trailing slash.
+  if (!baseDir.endsWith('/')) baseDir += '/';
+  // Strip base directory from slug if present.
+  const relativeSlug = slug.startsWith(baseDir)
+    ? slug.replace(baseDir, '')
+    : slug;
+  let dir = dirname(relativeSlug);
+  // Return no breadcrumbs for items in the root directory.
+  if (dir === '.') return [];
+  return dir.split('/');
+}
+
+/** Turn a flat array of routes into a tree structure. */
+function treeify(routes: Route[], baseDir: string): Dir {
+  const treeRoot: Dir = {};
+  routes.forEach((doc) => {
+    const breadcrumbs = getBreadcrumbs(doc.slug, baseDir);
+
+    // Walk down the route’s path to generate the tree.
+    let currentDir = treeRoot;
+    breadcrumbs.forEach((dir) => {
+      // Create new folder if needed.
+      if (typeof currentDir[dir] === 'undefined') currentDir[dir] = {};
+      // Go into the subdirectory.
+      currentDir = currentDir[dir] as Dir;
+    });
+    // We’ve walked through the path. Register the route in this directory.
+    currentDir[basename(doc.slug)] = doc.slug;
+  });
+  return treeRoot;
+}
+
+/** Create a link entry for a given content collection entry. */
+function linkFromSlug(slug: string, currentPathname: string): Link {
+  const doc = routes.find((doc) => doc.slug === slug)!;
+  return makeLink(
+    slugToPathname(doc.slug),
+    doc.entry.data.title,
+    currentPathname
+  );
+}
+
+/** Create a group entry for a given content collection directory. */
+function groupFromDir(
+  dir: Dir,
+  fullPath: string,
+  dirName: string,
+  currentPathname: string,
+  locale: string | undefined
+): Group {
+  const entries = Object.entries(dir).map(([key, dirOrSlug]) =>
+    dirToItem(dirOrSlug, `${fullPath}/${key}`, key, currentPathname, locale)
+  );
+  return {
+    type: 'group',
+    label: dirName,
+    entries,
+  };
+}
+
+/** Create a sidebar entry for a directory or content slug. */
+function dirToItem(
+  dirOrSlug: Dir[string],
+  fullPath: string,
+  dirName: string,
+  currentPathname: string,
+  locale: string | undefined
+): SidebarEntry {
+  return typeof dirOrSlug === 'string'
+    ? linkFromSlug(dirOrSlug, currentPathname)
+    : groupFromDir(dirOrSlug, fullPath, dirName, currentPathname, locale);
+}
+
+/** Create a sidebar entry for a given content directory. */
+function sidebarFromDir(
+  tree: Dir,
+  currentPathname: string,
+  locale: string | undefined
+) {
+  return Object.entries(tree).map(([key, dirOrSlug]) =>
+    dirToItem(dirOrSlug, key, key, currentPathname, locale)
+  );
+}
+
+/** Get the sidebar for the current page. */
+export function getSidebar(
+  pathname: string,
+  locale: string | undefined
+): SidebarEntry[] {
+  const routes = getLocaleRoutes(locale);
+  if (config.sidebar) {
+    return config.sidebar.map((group) =>
+      configItemToEntry(group, pathname, locale, routes)
+    );
+  } else {
+    const tree = treeify(routes, locale || '');
+    return sidebarFromDir(tree, pathname, locale);
+  }
+}
+
+/** Turn the nested tree structure of a sidebar into a flat list of all the links. */
+function flattenSidebar(sidebar: SidebarEntry[]): Link[] {
+  return sidebar.flatMap((entry) =>
+    entry.type === 'group' ? flattenSidebar(entry.entries) : entry
+  );
+}
+
+/** Get previous/next pages in the sidebar if there are any. */
+export function getPrevNextLinks(sidebar: SidebarEntry[]): {
+  prev: Link | undefined;
+  next: Link | undefined;
+} {
+  const entries = flattenSidebar(sidebar);
+  const currentIndex = entries.findIndex((entry) => entry.isCurrent);
+  const prev = entries[currentIndex - 1];
+  const next = entries[currentIndex + 1];
+  return { prev, next };
+}

package/utils/routing.ts

@@ -0,0 +1,109 @@
+import type { GetStaticPathsItem } from 'astro';
+import { CollectionEntry, getCollection } from 'astro:content';
+import config from 'virtual:starlight/user-config';
+import {
+  LocaleData,
+  localizedSlug,
+  slugToLocaleData,
+  slugToParam,
+} from './slugs';
+
+export interface Route extends LocaleData {
+  entry: CollectionEntry<'docs'>;
+  entryMeta: LocaleData;
+  slug: string;
+  isFallback?: true;
+  [key: string]: unknown;
+}
+
+interface Path extends GetStaticPathsItem {
+  params: { slug: string | undefined };
+  props: Route;
+}
+
+/** All entries in the docs content collection. */
+const docs = await getCollection('docs');
+
+function getRoutes(): Route[] {
+  const routes: Route[] = docs.map((entry) => ({
+    entry,
+    slug: entry.slug,
+    entryMeta: slugToLocaleData(entry.slug),
+    ...slugToLocaleData(entry.slug),
+  }));
+
+  // In multilingual sites, add required fallback routes.
+  if (config.isMultilingual) {
+    /** Entries in the docs content collection for the default locale. */
+    const defaultLocaleDocs = getLocaleDocs(
+      config.defaultLocale?.locale === 'root'
+        ? undefined
+        : config.defaultLocale?.locale
+    );
+    for (const key in config.locales) {
+      if (key === config.defaultLocale.locale) continue;
+      const localeConfig = config.locales[key];
+      if (!localeConfig) continue;
+      const locale = key === 'root' ? undefined : key;
+      const localeDocs = getLocaleDocs(locale);
+      for (const fallback of defaultLocaleDocs) {
+        const slug = localizedSlug(fallback.slug, locale);
+        const doesNotNeedFallback = localeDocs.some((doc) => doc.slug === slug);
+        if (doesNotNeedFallback) continue;
+        routes.push({
+          entry: fallback,
+          slug,
+          isFallback: true,
+          lang: localeConfig.lang || 'en',
+          locale,
+          dir: localeConfig.dir,
+          entryMeta: slugToLocaleData(fallback.slug),
+        });
+      }
+    }
+  }
+
+  return routes;
+}
+export const routes = getRoutes();
+
+function getPaths(): Path[] {
+  return routes.map((route) => ({
+    params: { slug: slugToParam(route.slug) },
+    props: route,
+  }));
+}
+export const paths = getPaths();
+
+/**
+ * Get all routes for a specific locale.
+ * A locale of `undefined` is treated as the “root” locale, if configured.
+ */
+export function getLocaleRoutes(locale: string | undefined): Route[] {
+  return filterByLocale(routes, locale);
+}
+
+/**
+ * Get all entries in the docs content collection for a specific locale.
+ * A locale of `undefined` is treated as the “root” locale, if configured.
+ */
+function getLocaleDocs(locale: string | undefined): CollectionEntry<'docs'>[] {
+  return filterByLocale(docs, locale);
+}
+
+/** Filter an array to find items whose slug matches the passed locale. */
+function filterByLocale<T extends { slug: string }>(
+  items: T[],
+  locale: string | undefined
+): T[] {
+  if (config.locales) {
+    if (locale && locale in config.locales) {
+      return items.filter((i) => i.slug.startsWith(locale + '/'));
+    } else if (config.locales.root) {
+      const langKeys = Object.keys(config.locales).filter((k) => k !== 'root');
+      const isLangDir = new RegExp(`^(${langKeys.join('|')})/`);
+      return items.filter((i) => !isLangDir.test(i.slug));
+    }
+  }
+  return items;
+}

package/utils/slugs.ts

@@ -0,0 +1,91 @@
+import type { CollectionEntry } from 'astro:content';
+import config from 'virtual:starlight/user-config';
+
+export interface LocaleData {
+  /** Writing direction. */
+  dir: 'ltr' | 'rtl';
+  /** BCP-47 language tag. */
+  lang: string;
+  /** The base path at which a language is served. `undefined` for root locale slugs. */
+  locale: string | undefined;
+}
+
+/**
+ * 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
+ */
+function slugToLocale(
+  slug: CollectionEntry<'docs'>['slug']
+): string | undefined {
+  const locales = Object.keys(config.locales || {});
+  const baseSegment = slug.split('/')[0];
+  if (baseSegment && locales.includes(baseSegment)) return baseSegment;
+  return undefined;
+}
+
+/** Get locale information for a given slug. */
+export function slugToLocaleData(
+  slug: CollectionEntry<'docs'>['slug']
+): LocaleData {
+  const locale = slugToLocale(slug);
+  return { dir: localeToDir(locale), lang: localeToLang(locale), locale };
+}
+
+/**
+ * Get the BCP-47 language tag for the given locale.
+ * @param locale Locale string or `undefined` for the root locale.
+ */
+function localeToLang(locale: string | undefined): string {
+  const lang = locale
+    ? config.locales?.[locale]?.lang
+    : config.locales?.root?.lang;
+  return lang || 'en';
+}
+
+/**
+ * Get the configured writing direction for the given locale.
+ * @param locale Locale string or `undefined` for the root locale.
+ */
+function localeToDir(locale: string | undefined): 'ltr' | 'rtl' {
+  const dir = locale
+    ? config.locales?.[locale]?.dir
+    : config.locales?.root?.dir;
+  return dir || 'ltr';
+}
+
+export function slugToParam(slug: string): string | undefined {
+  return slug === 'index'
+    ? undefined
+    : slug.endsWith('/index')
+    ? slug.replace('/index', '')
+    : slug;
+}
+
+export function slugToPathname(slug: string): string {
+  const param = slugToParam(slug);
+  return param ? '/' + param + '/' : '/';
+}
+
+/**
+ * Convert a slug to a different locale.
+ * For example, passing a slug of `en/home` and a locale of `fr` results in `fr/home`.
+ * An undefined locale is treated as the root locale, resulting in `home`
+ * @param slug A collection entry slug
+ * @param locale The target locale
+ * @example
+ * localizedSlug('en/home', 'fr')       // => 'fr/home'
+ * localizedSlug('en/home', undefined)  // => 'home'
+ */
+export function localizedSlug(
+  slug: CollectionEntry<'docs'>['slug'],
+  locale: string | undefined
+): string {
+  const slugLocale = slugToLocale(slug);
+  if (slugLocale === locale) return slug;
+  if (slugLocale) {
+    return slug.replace(slugLocale + '/', locale ? locale + '/' : '');
+  }
+  return locale + '/' + slug;
+}

package/utils/user-config.ts

@@ -0,0 +1,250 @@
+import { z } from 'astro/zod';
+import { parse as bcpParse, stringify as bcpStringify } from 'bcp-47';
+
+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.'
+    ),
+});
+
+const SidebarLinkItemSchema = z.object({
+  /** The visible label for this item in the sidebar. */
+  label: 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 = z.object({
+  /** The visible label for this item in the sidebar. */
+  label: z.string(),
+  /** Enable autogenerating a sidebar category from a specific docs directory. */
+  autogenerate: z.object({
+    /** The directory to generate sidebar items for. */
+    directory: z.string(),
+    // 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 ManualSidebarGroup = {
+  /** The visible label for this item in the sidebar. */
+  label: string;
+  /** Array of links and subcategories to display in this category. */
+  items: Array<
+    | SidebarLinkItem
+    | z.infer<typeof AutoSidebarGroupSchema>
+    | ManualSidebarGroup
+  >;
+};
+
+const ManualSidebarGroupSchema: z.ZodType<ManualSidebarGroup> = z.object({
+  /** The visible label for this item in the sidebar. */
+  label: z.string(),
+  /** 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,
+]);
+export type SidebarItem = z.infer<typeof SidebarItemSchema>;
+
+const SidebarGroupSchema: z.ZodType<
+  ManualSidebarGroup | z.infer<typeof AutoSidebarGroupSchema>
+> = z.union([ManualSidebarGroupSchema, AutoSidebarGroupSchema]);
+
+const StarlightUserConfigSchema = 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.'
+    ),
+
+  /** Optional details about the social media accounts for this site. */
+  social: z
+    .object({
+      /** Main Twitter handle for this site, e.g. `'astrodotbuild'`. */
+      twitter: z.string().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: z
+    .object({
+      /** The level to start including headings at in the table of contents. Default: 2. */
+      minHeadingLevel: z.number().int().min(1).max(6).optional().default(2),
+      /** The level to stop including headings at in the table of contents. Default: 3. */
+      maxHeadingLevel: z.number().int().min(1).max(6).optional().default(3),
+    })
+    .optional()
+    .default({ minHeadingLevel: 2, maxHeadingLevel: 3 })
+    .refine((toc) => toc.minHeadingLevel <= toc.maxHeadingLevel, {
+      message: 'minHeadingLevel must be less than or equal to maxHeadingLevel',
+    }),
+
+  /** 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: SidebarGroupSchema.array().optional(),
+
+  /**
+   * 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([]),
+});
+
+export const StarlightConfigSchema = StarlightUserConfigSchema.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: undefined,
+      locales: undefined,
+    } as const;
+  }
+);
+
+export type StarlightConfig = z.infer<typeof StarlightConfigSchema>;
+export type StarlightUserConfig = z.input<typeof StarlightConfigSchema>;

package/virtual.d.ts

@@ -0,0 +1,9 @@
+declare module 'virtual:starlight/user-config' {
+  const Config: import('./types').StarlightConfig;
+  export default Config;
+}
+declare module 'virtual:starlight/project-context' {
+  export default { root: string };
+}
+
+declare module 'virtual:starlight/user-css' {}