@astrojs/starlight 0.0.6 → 0.0.8

package/404.astro

@@ -17,6 +17,7 @@ import ThemeProvider from './components/ThemeProvider.astro';
 
 // Important that this is the last import so it can override built-in styles.
 import 'virtual:starlight/user-css';
+import { withBase } from './utils/base';
 
 const { lang = 'en', dir = 'ltr', locale } = config.defaultLocale || {};
 ---
@@ -37,7 +38,7 @@ const { lang = 'en', dir = 'ltr', locale } = config.defaultLocale || {};
           <p>Houston, we have a problem.</p>
           <p>
             We couldn’t find that link. Check the address or <a
-              href={import.meta.env.BASE_URL}>head back home</a
+              href={withBase('/')}>head back home</a
             >.
           </p>
         </MarkdownContent>

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @astrojs/starlight
 
+## 0.0.8
+
+### Patch Changes
+
+- [#62](https://github.com/withastro/starlight/pull/62) [`a91191e`](https://github.com/withastro/starlight/commit/a91191e8308ffa746a3eadeea61e39412f32f926) Thanks [@delucis](https://github.com/delucis)! - Make `base` support consistent, including when `trailingSlash: 'never'` is set.
+
+- [#61](https://github.com/withastro/starlight/pull/61) [`608f34c`](https://github.com/withastro/starlight/commit/608f34cbbe485c39730f33828971397f9c8a3534) Thanks [@liruifengv](https://github.com/liruifengv)! - Fix toc headingsObserver rootMargin
+
+- [#66](https://github.com/withastro/starlight/pull/66) [`9ca67d8`](https://github.com/withastro/starlight/commit/9ca67d8984f76c22e5411d7352aa8e0bd4514f42) Thanks [@Yan-Thomas](https://github.com/Yan-Thomas)! - Make site title width fit the content
+
+- [#64](https://github.com/withastro/starlight/pull/64) [`4460e55`](https://github.com/withastro/starlight/commit/4460e55de210fd9a23a762fe76f5c32297d68d76) Thanks [@delucis](https://github.com/delucis)! - Fix table of contents intersection observer for all possible viewport sizes.
+
+- [#67](https://github.com/withastro/starlight/pull/67) [`38c2c1f`](https://github.com/withastro/starlight/commit/38c2c1f1ed25d6efe6ab2637ca2d9fbcdafcd240) Thanks [@TheOtterlord](https://github.com/TheOtterlord)! - Fix background color on select component
+
+- [#57](https://github.com/withastro/starlight/pull/57) [`5b6cccb`](https://github.com/withastro/starlight/commit/5b6cccb7f9ee5810c75fbbb45496e2a1d022f7dd) Thanks [@BryceRussell](https://github.com/BryceRussell)! - Update site title link to include locale
+
+## 0.0.7
+
+### Patch Changes
+
+- [#55](https://github.com/withastro/starlight/pull/55) [`8597b9c`](https://github.com/withastro/starlight/commit/8597b9c1002f8c5073d25ae5cacd4060ded2f8c8) Thanks [@delucis](https://github.com/delucis)! - Fix routing logic to handle `index.md` slug differences between docs collection root and nested directories.
+
+- [#54](https://github.com/withastro/starlight/pull/54) [`db728d6`](https://github.com/withastro/starlight/commit/db728d61afa5cea060c66f746a4cc4ab3e1c3bcd) Thanks [@TheOtterlord](https://github.com/TheOtterlord)! - Add padding to scroll preventing headings being obscured by nav
+
+- [#51](https://github.com/withastro/starlight/pull/51) [`3adbdbb`](https://github.com/withastro/starlight/commit/3adbdbbb71a4b3648984fa1028fa116d0aff9a7d) Thanks [@delucis](https://github.com/delucis)! - Support displaying a custom logo in the nav bar.
+
+- [#51](https://github.com/withastro/starlight/pull/51) [`3adbdbb`](https://github.com/withastro/starlight/commit/3adbdbbb71a4b3648984fa1028fa116d0aff9a7d) Thanks [@delucis](https://github.com/delucis)! - All Starlight projects now use Astro’s experimental optimized asset support.
+
 ## 0.0.6
 
 ### Patch Changes

package/components/HeadSEO.astro

@@ -4,6 +4,7 @@ import config from 'virtual:starlight/user-config';
 import type { HeadConfigSchema } from '../schemas/head';
 import { createHead } from '../utils/head';
 import { localizedUrl } from '../utils/localizedUrl';
+import { withBase } from '../utils/base';
 
 interface Props {
   data: CollectionEntry<'docs'>['data'];
@@ -32,7 +33,7 @@ const headDefaults: z.input<ReturnType<typeof HeadConfigSchema>> = [
     tag: 'link',
     attrs: {
       rel: 'shortcut icon',
-      href: import.meta.env.BASE_URL + 'favicon.svg',
+      href: withBase('/favicon.svg'),
       type: 'image/svg+xml',
     },
   },
@@ -80,7 +81,7 @@ if (Astro.site) {
     tag: 'link',
     attrs: {
       rel: 'sitemap',
-      href: import.meta.env.BASE_URL + 'sitemap-index.xml',
+      href: withBase('/sitemap-index.xml'),
     },
   });
 }

package/components/Header.astro

@@ -1,22 +1,24 @@
 ---
-import config from 'virtual:starlight/user-config';
 import LanguageSelect from './LanguageSelect.astro';
 import Search from './Search.astro';
-import ThemeSelect from './ThemeSelect.astro';
+import SiteTitle from './SiteTitle.astro';
 import SocialIcons from './SocialIcons.astro';
+import ThemeSelect from './ThemeSelect.astro';
 
 interface Props {
   locale: string | undefined;
 }
+
+const { locale } = Astro.props
 ---
 
 <div class="header">
-  <a href={import.meta.env.BASE_URL} class="site-title">{config.title}</a>
+  <SiteTitle {locale} />
   <Search />
   <div class="hidden md:flex right-group">
     <SocialIcons />
     <ThemeSelect />
-    <LanguageSelect locale={Astro.props.locale} />
+    <LanguageSelect {locale}/>
   </div>
 </div>
 
@@ -29,14 +31,6 @@ interface Props {
     height: 100%;
   }
 
-  .site-title {
-    font-size: var(--sl-text-h4);
-    font-weight: 600;
-    color: var(--sl-color-text-accent);
-    text-decoration: none;
-    white-space: nowrap;
-  }
-
   .right-group {
     gap: 1rem;
     align-items: center;

package/components/RightSidebar.astro

@@ -1,13 +1,13 @@
 ---
 import type { MarkdownHeading } from 'astro';
-import type { CollectionEntry } from 'astro:content';
 import config from 'virtual:starlight/user-config';
+import type { StarlightDocsEntry } from '../utils/routing';
 import EditLink from './EditLink.astro';
 import RightSidebarPanel from './RightSidebarPanel.astro';
 import TableOfContents from './TableOfContents.astro';
 
 interface Props {
-  entry: CollectionEntry<'docs'>;
+  entry: StarlightDocsEntry;
   headings: MarkdownHeading[];
 }
 

package/components/Select.astro

@@ -72,6 +72,10 @@ interface Props {
     appearance: none;
   }
 
+  option {
+    background-color: var(--sl-color-bg-nav);
+  }
+
   @media (min-width: 50rem) {
     select {
       font-size: var(--sl-text-sm);

package/components/SiteTitle.astro

@@ -0,0 +1,82 @@
+---
+import { logos } from 'virtual:starlight/user-images';
+import config from 'virtual:starlight/user-config';
+import { withBase } from '../utils/base';
+
+interface Props {
+  locale: string | undefined;
+}
+
+if (config.logo) {
+  let err: string | undefined;
+  if ('src' in config.logo) {
+    if (!logos.dark || !logos.light) {
+      err = `Could not resolve logo import for "${config.logo.src}" (logo.src)`;
+    }
+  } else {
+    if (!logos.dark) {
+      err = `Could not resolve logo import for "${config.logo.dark}" (logo.dark)`;
+    } else if (!logos.light) {
+      err = `Could not resolve logo import for "${config.logo.light}" (logo.light)`;
+    }
+  }
+  if (err) throw new Error(err);
+}
+
+const href = withBase(Astro.props.locale || '/');
+---
+
+<a {href} class="site-title flex">
+  {
+    config.logo && logos.dark && (
+      <>
+        <img
+          class:list={{ 'dark-only': !('src' in config.logo) }}
+          alt={config.logo.alt}
+          src={logos.dark.src}
+          width={logos.dark.width}
+          height={logos.dark.height}
+        />
+        {/* Show light alternate if a user configure both light and dark logos. */}
+        {!('src' in config.logo) && (
+          <img
+            class="light-only"
+            alt={config.logo.alt}
+            src={logos.light?.src}
+            width={logos.light?.width}
+            height={logos.light?.height}
+          />
+        )}
+      </>
+    )
+  }
+  <span class:list={{ 'sr-only': config.logo?.replacesTitle }}>
+    {config.title}
+  </span>
+</a>
+
+<style>
+  .site-title {
+    justify-self: flex-start;
+    align-items: center;
+    gap: var(--sl-nav-gap);
+    font-size: var(--sl-text-h4);
+    font-weight: 600;
+    color: var(--sl-color-text-accent);
+    text-decoration: none;
+    white-space: nowrap;
+  }
+  img {
+    height: calc(var(--sl-nav-height) - 2 * var(--sl-nav-pad-y));
+    width: auto;
+    max-width: 100%;
+    object-fit: contain;
+    object-position: 0 50%;
+  }
+  :global([data-theme='light']) .dark-only {
+    display: none;
+  }
+  :global([data-theme='dark']) .light-only {
+    display: none;
+  }
+</style>

package/components/TableOfContents/MobileTableOfContents.astro

@@ -121,7 +121,7 @@ const toc = generateToC(Astro.props.headings, config.tableOfContents);
     }
 
     constructor() {
-      super();
+      super({ smallViewport: true });
       const details = this.querySelector('details');
       if (!details) return;
       const closeToC = () => {

package/components/TableOfContents/starlight-toc.ts

@@ -12,7 +12,7 @@ export class StarlightTOC extends HTMLElement {
     this._current = link;
   }
 
-  constructor() {
+  constructor({ smallViewport = false } = {}) {
     super();
 
     /** All the links in the table of contents. */
@@ -68,17 +68,35 @@ export class StarlightTOC extends HTMLElement {
       }
     };
 
-    const headingsObserver = new IntersectionObserver(setCurrent, {
-      rootMargin: '5% 0% -85%',
-    });
-
     // Observe elements with an `id` (most likely headings) and their siblings.
     // Also observe direct children of `.content` to include elements before
     // the first heading.
     const toObserve = document.querySelectorAll(
       'main [id], main [id] ~ *, main .content > *'
     );
-    toObserve.forEach((h) => headingsObserver.observe(h));
+    /** Start intersections at nav height + 2rem padding. */
+    const top = (smallViewport ? 104 : 64) + 32;
+    /** End intersections 1.5rem later. */
+    const bottom = top + 24;
+
+    let observer: IntersectionObserver | undefined;
+    function observe() {
+      if (observer) observer.disconnect();
+      const height = document.documentElement.clientHeight;
+      const rootMargin = `-${top}px 0% ${bottom - height}px`;
+      observer = new IntersectionObserver(setCurrent, { rootMargin });
+      toObserve.forEach((h) => observer!.observe(h));
+    }
+    observe();
+
+    const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
+    let timeout: NodeJS.Timeout;
+    window.addEventListener('resize', () => {
+      // Disable intersection observer while window is resizing.
+      if (observer) observer.disconnect();
+      clearTimeout(timeout);
+      timeout = setTimeout(() => onIdle(observe), 200);
+    });
   }
 }
 

package/index.astro

@@ -47,6 +47,20 @@ const prevNextLinks = getPrevNextLinks(sidebar);
 <html lang={lang} dir={dir}>
   <head>
     <HeadSEO data={entry.data} lang={lang} />
+    <style>
+      /* Add scroll padding to ensure anchor headings aren't obscured by nav */
+      html {
+        /* Additional padding is needed to account for the mobile TOC */
+        scroll-padding-top: calc(
+          1.5rem + var(--sl-nav-height) + var(--sl-mobile-toc-height)
+        );
+      }
+      @media (min-width: 72em) {
+        html {
+          scroll-padding-top: calc(1.5rem + var(--sl-nav-height));
+        }
+      }
+    </style>
   </head>
   <body>
     <ThemeProvider />

package/index.ts

@@ -45,6 +45,7 @@ export default function StarlightIntegration(
                 ? {}
                 : { theme: 'css-variables' },
           },
+          experimental: { assets: true },
         };
         updateConfig(newConfig);
       },
@@ -84,6 +85,11 @@ function vitePluginStarlightUserConfig(
     'virtual:starlight/user-css': opts.customCss
       .map((id) => `import "${id}";`)
       .join(''),
+    'virtual:starlight/user-images': opts.logo
+      ? 'src' in opts.logo
+        ? `import src from "${opts.logo.src}"; export const logos = { dark: src, light: src };`
+        : `import dark from "${opts.logo.dark}"; import light from "${opts.logo.light}"; export const logos = { dark, light };`
+      : 'export const logos = {};',
   };
   const resolutionMap = Object.fromEntries(
     (Object.keys(modules) as (keyof typeof modules)[]).map((key) => [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",

package/schemas/logo.ts

@@ -0,0 +1,28 @@
+import { z } from 'astro/zod';
+
+export const LogoConfigSchema = () =>
+  z
+    .union([
+      z.object({
+        /** Source of the image file to use. */
+        src: z.string(),
+        /** Alternative text description of the logo. */
+        alt: z.string().default(''),
+        /** Set to `true` to hide the site title text and only show the logo. */
+        replacesTitle: z.boolean().default(false),
+      }),
+      z.object({
+        /** Source of the image file to use in dark mode. */
+        dark: z.string(),
+        /** Source of the image file to use in light mode. */
+        light: z.string(),
+        /** Alternative text description of the logo. */
+        alt: z.string().default(''),
+        /** Set to `true` to hide the site title text and only show the logo. */
+        replacesTitle: z.boolean().default(false),
+      }),
+    ])
+    .optional();
+
+export type LogoUserConfig = z.input<ReturnType<typeof LogoConfigSchema>>;
+export type LogoConfig = z.output<ReturnType<typeof LogoConfigSchema>>;

package/utils/base.ts

@@ -0,0 +1,14 @@
+const base = stripTrailingSlash(import.meta.env.BASE_URL);
+
+/** Get the a root-relative URL path with the site’s `base` prefixed. */
+export function withBase(path: string) {
+  path = stripLeadingSlash(stripTrailingSlash(path));
+  return path ? base + '/' + path + '/' : base + '/';
+}
+
+function stripLeadingSlash(path: string) {
+  return path.replace(/^\//, '');
+}
+function stripTrailingSlash(path: string) {
+  return path.replace(/\/$/, '');
+}

package/utils/navigation.ts

@@ -1,7 +1,8 @@
 import { basename, dirname } from 'node:path';
 import config from 'virtual:starlight/user-config';
-import { slugToPathname } from './slugs';
+import { withBase } from './base';
 import { Route, getLocaleRoutes, routes } from './routing';
+import { slugToPathname } from './slugs';
 import type {
   AutoSidebarGroup,
   SidebarItem,
@@ -100,12 +101,7 @@ function linkFromConfig(
 
 /** 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;
-  }
+  if (!isAbsolute(href)) href = withBase(href);
   const isCurrent = href === currentPathname;
   return { type: 'link', label, href, isCurrent };
 }

package/utils/routing.ts

@@ -8,8 +8,12 @@ import {
   slugToParam,
 } from './slugs';
 
+export type StarlightDocsEntry = Omit<CollectionEntry<'docs'>, 'slug'> & {
+  slug: string;
+};
+
 export interface Route extends LocaleData {
-  entry: CollectionEntry<'docs'>;
+  entry: StarlightDocsEntry;
   entryMeta: LocaleData;
   slug: string;
   isFallback?: true;
@@ -21,8 +25,17 @@ interface Path extends GetStaticPathsItem {
   props: Route;
 }
 
+/**
+ * Astro is inconsistent in its `index.md` slug generation. In most cases,
+ * `index` is stripped, but in the root of a collection, we get a slug of `index`.
+ * We map that to an empty string for consistent behaviour.
+ */
+const normalizeIndexSlug = (slug: string) => (slug === 'index' ? '' : slug);
+
 /** All entries in the docs content collection. */
-const docs = await getCollection('docs');
+const docs: StarlightDocsEntry[] = (await getCollection('docs')).map(
+  ({ slug, ...entry }) => ({ ...entry, slug: normalizeIndexSlug(slug) })
+);
 
 function getRoutes(): Route[] {
   const routes: Route[] = docs.map((entry) => ({
@@ -87,7 +100,7 @@ export function getLocaleRoutes(locale: string | undefined): Route[] {
  * 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'>[] {
+function getLocaleDocs(locale: string | undefined): StarlightDocsEntry[] {
   return filterByLocale(docs, locale);
 }
 
@@ -98,11 +111,16 @@ function filterByLocale<T extends { slug: string }>(
 ): T[] {
   if (config.locales) {
     if (locale && locale in config.locales) {
-      return items.filter((i) => i.slug.startsWith(locale + '/'));
+      return items.filter(
+        (i) => i.slug === locale || i.slug.startsWith(locale + '/')
+      );
     } else if (config.locales.root) {
       const langKeys = Object.keys(config.locales).filter((k) => k !== 'root');
+      const isLangIndex = new RegExp(`^(${langKeys.join('|')})$`);
       const isLangDir = new RegExp(`^(${langKeys.join('|')})/`);
-      return items.filter((i) => !isLangDir.test(i.slug));
+      return items.filter(
+        (i) => !isLangIndex.test(i.slug) && !isLangDir.test(i.slug)
+      );
     }
   }
   return items;

package/utils/slugs.ts

@@ -1,4 +1,3 @@
-import type { CollectionEntry } from 'astro:content';
 import config from 'virtual:starlight/user-config';
 
 export interface LocaleData {
@@ -16,9 +15,7 @@ export interface LocaleData {
  * Root locale slugs will return `undefined`.
  * @param slug A collection entry slug
  */
-function slugToLocale(
-  slug: CollectionEntry<'docs'>['slug']
-): string | undefined {
+function slugToLocale(slug: string): string | undefined {
   const locales = Object.keys(config.locales || {});
   const baseSegment = slug.split('/')[0];
   if (baseSegment && locales.includes(baseSegment)) return baseSegment;
@@ -26,9 +23,7 @@ function slugToLocale(
 }
 
 /** Get locale information for a given slug. */
-export function slugToLocaleData(
-  slug: CollectionEntry<'docs'>['slug']
-): LocaleData {
+export function slugToLocaleData(slug: string): LocaleData {
   const locale = slugToLocale(slug);
   return { dir: localeToDir(locale), lang: localeToLang(locale), locale };
 }
@@ -56,7 +51,7 @@ function localeToDir(locale: string | undefined): 'ltr' | 'rtl' {
 }
 
 export function slugToParam(slug: string): string | undefined {
-  return slug === 'index'
+  return slug === 'index' || slug === ''
     ? undefined
     : slug.endsWith('/index')
     ? slug.replace('/index', '')
@@ -79,13 +74,16 @@ export function slugToPathname(slug: string): string {
  * localizedSlug('en/home', undefined)  // => 'home'
  */
 export function localizedSlug(
-  slug: CollectionEntry<'docs'>['slug'],
+  slug: string,
   locale: string | undefined
 ): string {
   const slugLocale = slugToLocale(slug);
   if (slugLocale === locale) return slug;
+  locale = locale || '';
   if (slugLocale) {
-    return slug.replace(slugLocale + '/', locale ? locale + '/' : '');
+    return slug
+      .replace(slugLocale + '/', locale ? locale + '/' : '')
+      .replace(/\/$/, '');
   }
-  return locale + '/' + slug;
+  return slug ? locale + '/' + slug : locale;
 }

package/utils/user-config.ts

@@ -1,6 +1,7 @@
 import { z } from 'astro/zod';
 import { parse as bcpParse, stringify as bcpStringify } from 'bcp-47';
 import { HeadConfigSchema } from '../schemas/head';
+import { LogoConfigSchema } from '../schemas/logo';
 
 const LocaleSchema = z.object({
   /** The label for this language to show in UI, e.g. `"English"`, `"العربية"`, or `"简体中文"`. */
@@ -101,6 +102,9 @@ const UserConfigSchema = z.object({
       '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({

package/virtual.d.ts

@@ -7,3 +7,11 @@ declare module 'virtual:starlight/project-context' {
 }
 
 declare module 'virtual:starlight/user-css' {}
+
+declare module 'virtual:starlight/user-images' {
+  type ImageMetadata = import('astro').ImageMetadata;
+  export const logos: {
+    dark?: ImageMetadata;
+    light?: ImageMetadata;
+  };
+}