From 3adbdbbb71a4b3648984fa1028fa116d0aff9a7d Mon Sep 17 00:00:00 2001
From: Chris Swithinbank
Date: Tue, 16 May 2023 16:44:13 +0200
Subject: Support displaying a custom logo in the nav bar (#51)
---
.changeset/polite-numbers-check.md | 5 ++
.changeset/real-beers-drum.md | 5 ++
docs/astro.config.mjs | 5 ++
docs/src/assets/logo-dark.svg | 11 ++++
docs/src/assets/logo-light.svg | 11 ++++
docs/src/content/docs/environmental-impact.md | 3 +-
docs/src/content/docs/reference/configuration.md | 23 ++++++++
docs/src/env.d.ts | 2 +-
packages/starlight/components/Header.astro | 14 +----
packages/starlight/components/SiteTitle.astro | 74 ++++++++++++++++++++++++
packages/starlight/index.ts | 6 ++
packages/starlight/schemas/logo.ts | 28 +++++++++
packages/starlight/utils/user-config.ts | 4 ++
packages/starlight/virtual.d.ts | 8 +++
14 files changed, 186 insertions(+), 13 deletions(-)
create mode 100644 .changeset/polite-numbers-check.md
create mode 100644 .changeset/real-beers-drum.md
create mode 100644 docs/src/assets/logo-dark.svg
create mode 100644 docs/src/assets/logo-light.svg
create mode 100644 packages/starlight/components/SiteTitle.astro
create mode 100644 packages/starlight/schemas/logo.ts
diff --git a/.changeset/polite-numbers-check.md b/.changeset/polite-numbers-check.md
new file mode 100644
index 00000000..dac1f975
--- /dev/null
+++ b/.changeset/polite-numbers-check.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Support displaying a custom logo in the nav bar.
diff --git a/.changeset/real-beers-drum.md b/.changeset/real-beers-drum.md
new file mode 100644
index 00000000..d8aa21c7
--- /dev/null
+++ b/.changeset/real-beers-drum.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": patch
+---
+
+All Starlight projects now use Astro’s experimental optimized asset support.
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 783555e7..c679b3a1 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -7,6 +7,11 @@ export default defineConfig({
integrations: [
starlight({
title: 'Starlight',
+ logo: {
+ light: '/src/assets/logo-light.svg',
+ dark: '/src/assets/logo-dark.svg',
+ replacesTitle: true,
+ },
editLink: {
baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
},
diff --git a/docs/src/assets/logo-dark.svg b/docs/src/assets/logo-dark.svg
new file mode 100644
index 00000000..8c5f408b
--- /dev/null
+++ b/docs/src/assets/logo-dark.svg
@@ -0,0 +1,11 @@
+
diff --git a/docs/src/assets/logo-light.svg b/docs/src/assets/logo-light.svg
new file mode 100644
index 00000000..c189f252
--- /dev/null
+++ b/docs/src/assets/logo-light.svg
@@ -0,0 +1,11 @@
+
diff --git a/docs/src/content/docs/environmental-impact.md b/docs/src/content/docs/environmental-impact.md
index 2f1b81f3..86d5f397 100644
--- a/docs/src/content/docs/environmental-impact.md
+++ b/docs/src/content/docs/environmental-impact.md
@@ -20,7 +20,8 @@ With a good caching strategy, subsequent navigations can download as little as 1
### Images
-While Starlight provides a good baseline, images you add to your docs pages can quickly increase your page weight. Try enabling Astro’s [optimized asset support][assets] if your docs require a lot of images.
+While Starlight provides a good baseline, images you add to your docs pages can quickly increase your page weight.
+Starlight uses Astro’s [optimized asset support][assets] to optimize local images in your Markdown and MDX files.
### UI components
diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md
index cddc7906..a3cd1902 100644
--- a/docs/src/content/docs/reference/configuration.md
+++ b/docs/src/content/docs/reference/configuration.md
@@ -19,6 +19,29 @@ Set the title for your website. Will be used in metadata and in the browser tab
Set the description for your website. Used in metadata shared with search engines in the `` tag if `description` is not set in a page’s frontmatter.
+### `logo`
+
+**type:** [`LogoConfig`](#logoconfig)
+
+Set a logo image to show in the navigation bar alongside or instead of the site title. You can either set a single `src` property or set separate image sources for `light` and `dark`.
+
+```js
+starlight({
+ logo: {
+ src: '/src/assets/my-logo.svg',
+ },
+});
+```
+
+#### `LogoConfig`
+
+```ts
+type LogoConfig = { alt?: string; replacesTitle?: boolean } & (
+ | { src: string }
+ | { light: string; dark: string }
+);
+```
+
### `tableOfContents`
**type:** `{ minHeadingLevel?: number; maxHeadingLevel?: number; }`
diff --git a/docs/src/env.d.ts b/docs/src/env.d.ts
index acef35f1..4170bce9 100644
--- a/docs/src/env.d.ts
+++ b/docs/src/env.d.ts
@@ -1,2 +1,2 @@
///
-///
+///
diff --git a/packages/starlight/components/Header.astro b/packages/starlight/components/Header.astro
index 235ade3a..565f2503 100644
--- a/packages/starlight/components/Header.astro
+++ b/packages/starlight/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 {
---
@@ -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;
diff --git a/packages/starlight/components/SiteTitle.astro b/packages/starlight/components/SiteTitle.astro
new file mode 100644
index 00000000..737b4fe2
--- /dev/null
+++ b/packages/starlight/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);
+}
+---
+
+
+ {
+ config.logo && logos.dark && (
+ <>
+
+ {/* Show light alternate if a user configure both light and dark logos. */}
+ {!('src' in config.logo) && (
+
+ )}
+
+ )
+ }
+
+ {config.title}
+
+
+
+
diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
index f08b9179..e3a5f3bf 100644
--- a/packages/starlight/index.ts
+++ b/packages/starlight/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) => [
diff --git a/packages/starlight/schemas/logo.ts b/packages/starlight/schemas/logo.ts
new file mode 100644
index 00000000..a6854ad2
--- /dev/null
+++ b/packages/starlight/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>;
+export type LogoConfig = z.output>;
diff --git a/packages/starlight/utils/user-config.ts b/packages/starlight/utils/user-config.ts
index 434c088e..0b38dd67 100644
--- a/packages/starlight/utils/user-config.ts
+++ b/packages/starlight/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({
diff --git a/packages/starlight/virtual.d.ts b/packages/starlight/virtual.d.ts
index bcf8563f..839acc1b 100644
--- a/packages/starlight/virtual.d.ts
+++ b/packages/starlight/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;
+ };
+}
--
cgit