@astrojs/starlight 0.0.6 → 0.0.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @astrojs/starlight
 
+## 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/Header.astro

@@ -1,9 +1,9 @@
 ---
-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;
@@ -11,7 +11,7 @@ interface Props {
 ---
 
 <div class="header">
-  <a href={import.meta.env.BASE_URL} class="site-title">{config.title}</a>
+  <SiteTitle />
   <Search />
   <div class="hidden md:flex right-group">
     <SocialIcons />
@@ -29,14 +29,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/SiteTitle.astro

@@ -0,0 +1,74 @@
+---
+import { logos } from 'virtual:starlight/user-images';
+import config from 'virtual:starlight/user-config';
+
+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);
+}
+---
+
+<a href={import.meta.env.BASE_URL} 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 {
+    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/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.7",
   "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/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;
+  };
+}