@astrojs/starlight 0.1.3 → 0.2.0

package/404.astro

@@ -36,7 +36,7 @@ const { lang = 'en', dir = 'ltr', locale } = config.defaultLocale || {};
       <Header slot="header" {locale} />
       <main>
         <MarkdownContent>
-          <h1 id="starlight__overview">404</h1>
+          <h1 id="_top" data-page-title>404</h1>
           <p>Houston, we have a problem.</p>
           <p>
             We couldn’t find that link. Check the address or

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @astrojs/starlight
 
+## 0.2.0
+
+### Minor Changes
+
+- [#171](https://github.com/withastro/starlight/pull/171) [`198c3f0`](https://github.com/withastro/starlight/commit/198c3f001410f259dab7d085136a37afe863cfa4) Thanks [@delucis](https://github.com/delucis)! - Add Starlight generator tag to HTML output
+
+- [#217](https://github.com/withastro/starlight/pull/217) [`490fd98`](https://github.com/withastro/starlight/commit/490fd98d4e7b38ec01c568eee0ab00844e59c53d) Thanks [@delucis](https://github.com/delucis)! - Updated sidebar styles. Sidebars now support top-level links and groups are styled with a subtle border and indentation to improve comprehension of nesting.
+
+- [#178](https://github.com/withastro/starlight/pull/178) [`d046c55`](https://github.com/withastro/starlight/commit/d046c55a62290c15f2e09faf4359f02df9492f6d) Thanks [@delucis](https://github.com/delucis)! - Add support for translating the Pagefind search modal
+
+- [#210](https://github.com/withastro/starlight/pull/210) [`cb5b121`](https://github.com/withastro/starlight/commit/cb5b1210e23548e2983865a4b38308b0f54dc7ce) Thanks [@delucis](https://github.com/delucis)! - Change page title ID to `_top` for cleaner hash URLs
+
+  ⚠️ Potentially breaking change if you were linking manually to `#starlight__overview` anywhere. If you were, update these links to use `#_top` instead.
+
+### Patch Changes
+
+- [#208](https://github.com/withastro/starlight/pull/208) [`09fc565`](https://github.com/withastro/starlight/commit/09fc565d44bd3abb4508541b458531de8624036f) Thanks [@delucis](https://github.com/delucis)! - Update `@astrojs/mdx` and `@astrojs/sitemap` to latest
+
+- [#216](https://github.com/withastro/starlight/pull/216) [`54905c5`](https://github.com/withastro/starlight/commit/54905c502c5e6de5516e36ddcd4969893572baa5) Thanks [@morinokami](https://github.com/morinokami)! - Encode heading id when finding current link
+
+## 0.1.4
+
+### Patch Changes
+
+- [#190](https://github.com/withastro/starlight/pull/190) [`a3809e4`](https://github.com/withastro/starlight/commit/a3809e4f1e14f3949e9e25f7ffbdea2920408edb) Thanks [@gabrielemercolino](https://github.com/gabrielemercolino)! - Added Italian language support
+
+- [#193](https://github.com/withastro/starlight/pull/193) [`c9ca4eb`](https://github.com/withastro/starlight/commit/c9ca4ebe10f4776999e3fff4ac4c19ac0a714bac) Thanks [@BryceRussell](https://github.com/BryceRussell)! - Fix bottom padding for sidebar on larger screen sizes
+
 ## 0.1.3
 
 ### Patch Changes

package/components/HeadSEO.astro

@@ -5,6 +5,7 @@ import type { HeadConfigSchema } from '../schemas/head';
 import { createHead } from '../utils/head';
 import { localizedUrl } from '../utils/localizedUrl';
 import { fileWithBase } from '../utils/base';
+import { version } from '../package.json';
 
 interface Props {
   data: CollectionEntry<'docs'>['data'];
@@ -28,6 +29,10 @@ const headDefaults: z.input<ReturnType<typeof HeadConfigSchema>> = [
   { tag: 'title', content: title },
   { tag: 'link', attrs: { rel: 'canonical', href: canonical?.href } },
   { tag: 'meta', attrs: { name: 'generator', content: Astro.generator } },
+  {
+    tag: 'meta',
+    attrs: { name: 'generator', content: `Starlight v${version}` },
+  },
   // Favicon
   {
     tag: 'link',

package/components/Hero.astro

@@ -38,7 +38,7 @@ const imageAttrs = {
   }
   <div class="flex stack">
     <div class="flex copy">
-      <h1 id="starlight__overview" set:html={title} />
+      <h1 id="_top" data-page-title set:html={title} />
       {tagline && <div class="tagline" set:html={tagline} />}
     </div>
     {

package/components/Search.astro

@@ -8,9 +8,18 @@ interface Props {
 }
 
 const t = useTranslations(Astro.props.locale);
+const pagefindTranslations = {
+  placeholder: t('search.label'),
+  ...Object.fromEntries(
+    Object.entries(t.pick('pagefind.')).map(([key, value]) => [
+      key.replace('pagefind.', ''),
+      value,
+    ])
+  ),
+};
 ---
 
-<site-search>
+<site-search data-translations={JSON.stringify(pagefindTranslations)}>
   <button data-open-modal disabled>
     {
       /* The span is `aria-hidden` because it is not shown on small screens. Instead, the icon label is used for accessibility purposes. */
@@ -96,23 +105,31 @@ const t = useTranslations(Astro.props.locale);
           e.preventDefault();
         }
       });
+
+      let translations = {};
+      try {
+        translations = JSON.parse(this.dataset.translations || '{}');
+      } catch {}
+
+      window.addEventListener('DOMContentLoaded', () => {
+        if (import.meta.env.DEV) return;
+        const onIdle =
+          window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
+        onIdle(async () => {
+          const { PagefindUI } = await import('@pagefind/default-ui');
+          new PagefindUI({
+            element: '#starlight__search',
+            baseUrl: import.meta.env.BASE_URL,
+            bundlePath:
+              import.meta.env.BASE_URL.replace(/\/$/, '') + '/_pagefind/',
+            showImages: false,
+            translations,
+          });
+        });
+      });
     }
   }
   customElements.define('site-search', SiteSearch);
-
-  window.addEventListener('DOMContentLoaded', () => {
-    if (import.meta.env.DEV) return;
-    const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
-    onIdle(async () => {
-      const { PagefindUI } = await import('@pagefind/default-ui');
-      new PagefindUI({
-        element: '#starlight__search',
-        baseUrl: import.meta.env.BASE_URL,
-        bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/_pagefind/',
-        showImages: false,
-      });
-    });
-  });
 </script>
 
 <style>

package/components/Sidebar.astro

@@ -28,13 +28,15 @@ const { sidebar, locale } = Astro.props;
     gap: 1rem;
   }
 
-  .sidebar > :global(:last-child) {
-    padding-bottom: 1rem;
-  }
-
   .mobile-preferences {
     justify-content: space-between;
     border-top: 1px solid var(--sl-color-gray-6);
     padding: 0.5rem 0;
   }
+
+  @media (min-width: 50rem) {
+    .sidebar > :global(:nth-last-child(2)) {
+      padding-bottom: 1rem;
+    }
+  }
 </style>

package/components/SidebarSublist.astro

@@ -4,24 +4,29 @@ import Icon from './Icon.astro';
 
 interface Props {
   sublist: SidebarEntry[];
+  nested?: boolean;
 }
 ---
 
-<ul>
+<ul class:list={{ 'top-level': !Astro.props.nested }}>
   {
     Astro.props.sublist.map((entry) => (
-      <li class:list={{ 'sidebar-group': entry.type === 'group' }}>
+      <li>
         {entry.type === 'link' ? (
-          <a href={entry.href} aria-current={entry.isCurrent && 'page'}>
+          <a
+            href={entry.href}
+            aria-current={entry.isCurrent && 'page'}
+            class:list={{ large: !Astro.props.nested }}
+          >
             {entry.label}
           </a>
         ) : (
           <details open>
             <summary>
-              <h2>{entry.label}</h2>
+              <h2 class="large">{entry.label}</h2>
               <Icon name="right-caret" class="caret" size="1.25rem" />
             </summary>
-            <Astro.self sublist={entry.entries} />
+            <Astro.self sublist={entry.entries} nested />
           </details>
         )}
       </li>
@@ -36,13 +41,19 @@ interface Props {
     padding: 0;
   }
 
-  h2 {
+  ul ul li {
+    margin-inline-start: var(--sl-sidebar-item-padding-inline);
+    border-inline-start: 1px solid var(--sl-color-hairline-light);
+    padding-inline-start: var(--sl-sidebar-item-padding-inline);
+  }
+
+  .large {
     font-size: var(--sl-text-lg);
     font-weight: 600;
     color: var(--sl-color-white);
   }
 
-  .sidebar-group + .sidebar-group {
+  .top-level > li + li {
     margin-top: 0.75rem;
   }
 
@@ -91,10 +102,10 @@ interface Props {
   }
 
   @media (min-width: 50rem) {
-    .sidebar-group + .sidebar-group {
+    .top-level > li + li {
       margin-top: 0.5rem;
     }
-    h2 {
+    .large {
       font-size: var(--sl-text-base);
     }
     a {

package/components/SkipLink.astro

@@ -8,7 +8,7 @@ interface Props {
 const t = useTranslations(Astro.props.locale);
 ---
 
-<a href="#starlight__overview">{t('skipLink.label')}</a>
+<a href="#_top">{t('skipLink.label')}</a>
 
 <style>
   a {

package/components/TableOfContents/generateToC.ts

@@ -25,7 +25,7 @@ export function generateToC(
   headings: MarkdownHeading[],
   { minHeadingLevel, maxHeadingLevel, title = 'Overview' }: TocOpts
 ) {
-  const overview = { depth: 2, slug: 'starlight__overview', text: title };
+  const overview = { depth: 2, slug: '_top', text: title };
   headings = [
     overview,
     ...headings.filter(

package/components/TableOfContents/starlight-toc.ts

@@ -22,7 +22,7 @@ export class StarlightTOC extends HTMLElement {
     const isHeading = (el: Element): el is HTMLHeadingElement => {
       if (el instanceof HTMLHeadingElement) {
         // Special case for page title h1
-        if (el.id === 'starlight__overview') return true;
+        if ('pageTitle' in el.dataset) return true;
         // Check the heading level is within the user-configured limits for the ToC
         const level = el.tagName[1];
         if (level) {
@@ -60,7 +60,7 @@ export class StarlightTOC extends HTMLElement {
         if (!isIntersecting) continue;
         const heading = getElementHeading(target);
         if (!heading) continue;
-        const link = links.find((link) => link.hash === '#' + heading.id);
+        const link = links.find((link) => link.hash === '#' + encodeURIComponent(heading.id));
         if (link) {
           this.current = link;
           break;

package/index.astro

@@ -102,7 +102,8 @@ const hasHero = Boolean(entry.data.hero);
           ) : (
             <ContentPanel>
               <h1
-                id="starlight__overview"
+                id="_top"
+                data-page-title
                 style="font-size: var(--sl-text-h1); line-height: var(--sl-line-height-headings); font-weight: 600; color: var(--sl-color-white); margin-top: 1rem;"
               >
                 {entry.data.title}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -34,8 +34,8 @@
     "astro": "^2.5.0"
   },
   "dependencies": {
-    "@astrojs/mdx": "^0.19.1",
-    "@astrojs/sitemap": "^1.3.1",
+    "@astrojs/mdx": "^0.19.7",
+    "@astrojs/sitemap": "^1.3.3",
     "@pagefind/default-ui": "^1.0.0-alpha.5",
     "@types/mdast": "^3.0.11",
     "bcp-47": "^2.1.0",
@@ -47,7 +47,7 @@
     "unified": "^10.1.2",
     "unist-util-remove": "^3.1.1",
     "unist-util-visit": "^4.1.2",
-    "vfile": "^5.3.7"
+    "vfile": "^6.0.0"
   },
   "scripts": {}
 }

package/schemas/i18n.ts

@@ -1,6 +1,14 @@
 import { z } from 'astro/zod';
 
 export function i18nSchema() {
+  return starlightI18nSchema().merge(pagefindI18nSchema());
+}
+
+export function builtinI18nSchema() {
+  return starlightI18nSchema().required().strict().merge(pagefindI18nSchema());
+}
+
+function starlightI18nSchema() {
   return z
     .object({
       'skipLink.label': z
@@ -89,3 +97,69 @@ export function i18nSchema() {
     })
     .partial();
 }
+
+function pagefindI18nSchema() {
+  return z
+    .object({
+      'pagefind.clear_search': z
+        .string()
+        .describe(
+          'Pagefind UI translation. English default value: `"Clear"`. See https://pagefind.app/docs/ui/#translations'
+        ),
+
+      'pagefind.load_more': z
+        .string()
+        .describe(
+          'Pagefind UI translation. English default value: `"Load more results"`. See https://pagefind.app/docs/ui/#translations'
+        ),
+
+      'pagefind.search_label': z
+        .string()
+        .describe(
+          'Pagefind UI translation. English default value: `"Search this site"`. See https://pagefind.app/docs/ui/#translations'
+        ),
+
+      'pagefind.filters_label': z
+        .string()
+        .describe(
+          'Pagefind UI translation. English default value: `"Filters"`. See https://pagefind.app/docs/ui/#translations'
+        ),
+
+      'pagefind.zero_results': z
+        .string()
+        .describe(
+          'Pagefind UI translation. English default value: `"No results for [SEARCH_TERM]"`. See https://pagefind.app/docs/ui/#translations'
+        ),
+
+      'pagefind.many_results': z
+        .string()
+        .describe(
+          'Pagefind UI translation. English default value: `"[COUNT] results for [SEARCH_TERM]"`. See https://pagefind.app/docs/ui/#translations'
+        ),
+
+      'pagefind.one_result': z
+        .string()
+        .describe(
+          'Pagefind UI translation. English default value: `"[COUNT] result for [SEARCH_TERM]"`. See https://pagefind.app/docs/ui/#translations'
+        ),
+
+      'pagefind.alt_search': z
+        .string()
+        .describe(
+          'Pagefind UI translation. English default value: `"No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead"`. See https://pagefind.app/docs/ui/#translations'
+        ),
+
+      'pagefind.search_suggestion': z
+        .string()
+        .describe(
+          'Pagefind UI translation. English default value: `"No results for [SEARCH_TERM]. Try one of the following searches:"`. See https://pagefind.app/docs/ui/#translations'
+        ),
+
+      'pagefind.searching': z
+        .string()
+        .describe(
+          'Pagefind UI translation. English default value: `"Searching for [SEARCH_TERM]..."`. See https://pagefind.app/docs/ui/#translations'
+        ),
+    })
+    .partial();
+}

package/style/props.css

@@ -43,6 +43,7 @@
   --sl-color-bg-nav: var(--sl-color-gray-6);
   --sl-color-bg-sidebar: var(--sl-color-gray-6);
   --sl-color-bg-inline-code: var(--sl-color-gray-5);
+  --sl-color-hairline-light: var(--sl-color-gray-5);
   --sl-color-hairline: var(--sl-color-gray-6);
   --sl-color-hairline-shade: var(--sl-color-black);
 
@@ -150,6 +151,7 @@
   --sl-color-bg-nav: var(--sl-color-gray-7);
   --sl-color-bg-sidebar: var(--sl-color-bg);
   --sl-color-bg-inline-code: var(--sl-color-gray-6);
+  --sl-color-hairline-light: var(--sl-color-gray-6);
   --sl-color-hairline-shade: var(--sl-color-gray-6);
 
   --sl-color-backdrop-overlay: hsla(225, 9%, 36%, 0.66);

package/translations/README.md

@@ -0,0 +1,14 @@
+# Starlight UI translation files
+
+This directory contains translation data for Starlight’s UI.
+Each language has its own JSON file and follows the [translation structure described in Starlight’s docs](https://starlight.astro.build/guides/i18n/#translate-starlights-ui).
+
+## Add a new language
+
+1. Create a JSON file named using the BCP-47 tag for the language, e.g. `en.json` or `ja.json`.
+
+2. Fill the file with translations for each UI string. You can base your translations on [`en.json`](./en.json). Translate only the values, leaving the keys in English (e.g. `"search.label": "Buscar"`).
+
+3. Import your file in [`index.ts`](./index.ts) and add your language to the `Object.entries`.
+
+4. Open a pull request on GitHub to add your file to Starlight!

package/translations/index.ts

@@ -1,13 +1,14 @@
-import { i18nSchema } from '../schemas/i18n';
+import { builtinI18nSchema } from '../schemas/i18n';
 import en from './en.json';
 import es from './es.json';
 import de from './de.json';
 import ja from './ja.json';
 import pt from './pt.json';
 import fr from './fr.json';
+import it from './it.json';
 
-const parse = i18nSchema().required().strict().parse;
+const { parse } = builtinI18nSchema();
 
 export default Object.fromEntries(
-  Object.entries({ en, es, de, ja, pt, fr }).map(([key, dict]) => [key, parse(dict)])
+  Object.entries({ en, es, de, ja, pt, fr, it }).map(([key, dict]) => [key, parse(dict)])
 );

package/translations/it.json

@@ -0,0 +1,20 @@
+{
+	"skipLink.label": "Salta ai contenuti",
+	"search.label": "Cerca",
+	"search.shortcutLabel": "(Usa / per cercare)",
+	"search.cancelLabel": "Cancella",
+	"themeSelect.accessibleLabel": "Seleziona tema",
+	"themeSelect.dark": "Scuro",
+	"themeSelect.light": "Chiaro",
+	"themeSelect.auto": "Auto",
+	"languageSelect.accessibleLabel": "Seleziona lingua",
+	"menuButton.accessibleLabel": "Menu",
+	"sidebarNav.accessibleLabel": "Principale",
+	"tableOfContents.onThisPage": "In questa pagina",
+	"tableOfContents.overview": "Panoramica",
+	"i18n.untranslatedContent": "Questi contenuti non sono ancora disponibili nella tua lingua.",
+	"page.editLink": "Modifica pagina",
+	"page.lastUpdated": "Ultimo aggiornamento:",
+	"page.previousLink": "Indietro",
+	"page.nextLink": "Avanti"
+}

package/utils/translations.ts

@@ -38,7 +38,12 @@ export function useTranslations(locale: string | undefined) {
     builtinTranslations[lang],
     userTranslations[lang]
   );
-  return (key: keyof typeof dictionary) => dictionary[key];
+  const t = <K extends keyof typeof dictionary>(key: K) => dictionary[key];
+  t.pick = (startOfKey: string) =>
+    Object.fromEntries(
+      Object.entries(dictionary).filter(([k]) => k.startsWith(startOfKey))
+    );
+  return t;
 }
 
 /** Build a dictionary by layering preferred translation sources. */

package/utils/user-config.ts

@@ -95,14 +95,6 @@ const SidebarItemSchema = z.union([
 ]);
 export type SidebarItem = z.infer<typeof SidebarItemSchema>;
 
-const SidebarGroupSchema: z.ZodType<
-  | z.output<typeof ManualSidebarGroupSchema>
-  | z.output<typeof AutoSidebarGroupSchema>,
-  z.ZodTypeDef,
-  | z.input<typeof ManualSidebarGroupSchema>
-  | z.input<typeof AutoSidebarGroupSchema>
-> = z.union([ManualSidebarGroupSchema, AutoSidebarGroupSchema]);
-
 const UserConfigSchema = z.object({
   /** Title for your website. Will be used in metadata and as browser tab title. */
   title: z
@@ -202,7 +194,7 @@ const UserConfigSchema = z.object({
   defaultLocale: z.string().optional(),
 
   /** Configure your site’s sidebar navigation items. */
-  sidebar: SidebarGroupSchema.array().optional(),
+  sidebar: SidebarItemSchema.array().optional(),
 
   /**
    * Add extra tags to your site’s `<head>`.