Support displaying a custom logo in the nav bar (#51)

14 files changed, 186 insertions, 13 deletions

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 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -7 161 40">
+  <path fill="url(#a)" fill-rule="evenodd" d="M15.22 7.77 12.06.94 8.91 7.77l-.15.29L7 6.3a1.18 1.18 0 1 0-1.68 1.68l1.75 1.74-.2.1-.04.02L0 13l6.83 3.16.24.11-1.75 1.76A1.18 1.18 0 1 0 7 19.7l1.76-1.76.15.3 3.15 6.82 3.16-6.83.12-.24 1.71 1.71a1.18 1.18 0 1 0 1.68-1.67L17 16.3l.29-.15L24.13 13 17.3 9.84 17 9.7l1.73-1.73a1.18 1.18 0 1 0-1.68-1.67L15.35 8a4.15 4.15 0 0 1-.12-.21l-.01-.03Zm-3.17.36-.42.9a7.27 7.27 0 0 1-3.55 3.55l-.9.42.9.42a7.27 7.27 0 0 1 3.55 3.55l.42.9.42-.9a7.27 7.27 0 0 1 3.55-3.55l.9-.42-.9-.42a7.27 7.27 0 0 1-3.55-3.55l-.42-.9Z" clip-rule="evenodd"/>
+  <path fill="url(#a)" d="M22.27 4.43a1.18 1.18 0 1 0-1.67-1.68l-.57.57a1.18 1.18 0 0 0 1.68 1.67l.56-.56ZM4.2 5.18c-.46.46-1.2.46-1.67 0l-.56-.56a1.18 1.18 0 0 1 1.67-1.68l.57.57c.46.46.46 1.2 0 1.67Zm0 15.64a1.18 1.18 0 0 0-1.67 0l-.56.56a1.18 1.18 0 0 0 1.67 1.68l.57-.57c.46-.46.46-1.2 0-1.67Zm18.07.75a1.18 1.18 0 0 1-1.67 1.68l-.57-.57a1.19 1.19 0 0 1 1.68-1.67l.56.56Z"/>
+  <path fill="#fff" fill-rule="evenodd" d="M101.72 19.52h-3.55a89.91 89.91 0 0 0 .06-3.93V9.08c0-.7 0-1.4-.02-2.05 0-.65 0-1.3-.02-1.96 0-.65 0-1.34-.02-2.07h3.57l-.07 2.03v12.55l.05 1.94Zm44.45 0h-3.63c.02-.57.02-1.2.02-1.9.02-.7.02-1.46.02-2.28.02-.83.02-1.7.02-2.63 0-.84-.14-1.5-.42-2a2.35 2.35 0 0 0-1.33-1.11c-.6-.25-1.4-.37-2.4-.37-.7 0-1.37.08-2 .24-.6.15-1.14.4-1.61.72-.46.33-.81.76-1.07 1.28a4.07 4.07 0 0 0-.39 1.84v3.44l.03 1.15v.9l.02.72h-3.63a90.31 90.31 0 0 0 .06-3.9v-4.81c0-.72 0-1.42-.02-2.1V6.67c0-.67 0-1.3-.02-1.92 0-.63 0-1.2-.02-1.75h3.67a1231.15 1231.15 0 0 1-.06 3.95 64.28 64.28 0 0 1-.05 2.5l.12.03a4.76 4.76 0 0 1 3.17-2.64 11.3 11.3 0 0 1 3.27-.42c.98 0 1.85.1 2.62.32a5.1 5.1 0 0 1 1.94.98 4 4 0 0 1 1.24 1.66c.29.67.43 1.47.43 2.4 0 .4 0 .78-.02 1.1v.92l-.02.81v2.91l.06 2Zm-35.18-8.47a3.63 3.63 0 0 1 1.92-3.29 7.7 7.7 0 0 1 2.39-.83 17.66 17.66 0 0 1 4.14-.26h1.54c.62 0 1.3 0 2.05.02.75.02 1.52.02 2.3.02h2.3v.43c0 .21 0 .46-.02.73v.72l.03.5a26.5 26.5 0 0 1-2.18-.1 266.79 266.79 0 0 0-1.92-.12v.14a6.23 6.23 0 0 1 2.03.93c.27.21.47.47.6.79.12.3.19.64.19 1.04a2.53 2.53 0 0 1-.7 1.8c-.24.25-.55.49-.95.7-.4.2-.88.37-1.45.51s-1.24.26-2 .34c-.77.07-1.65.11-2.63.11-1.36 0-2.52-.09-3.5-.26l-.21.2a1.7 1.7 0 0 0-.33.49c-.07.15-.1.32-.1.49 0 .27.1.46.32.57.23.12.53.18.92.18a85.08 85.08 0 0 0 5.25-.15 58.4 58.4 0 0 1 2.15-.05c1.01 0 1.84.1 2.48.28.65.19 1.14.48 1.45.9.33.41.5.95.5 1.62a3 3 0 0 1-.18 1.02c-.1.32-.27.6-.51.86-.24.25-.58.48-1 .68-.42.2-.94.37-1.58.51a17 17 0 0 1-2.29.32 55.99 55.99 0 0 1-6.87 0 20.42 20.42 0 0 1-2.5-.3 5.4 5.4 0 0 1-1.45-.47c-.33-.18-.56-.4-.68-.64a1.65 1.65 0 0 1 .04-1.53c.16-.23.38-.43.68-.6a5.11 5.11 0 0 1 1.58-.57v-.09a2.94 2.94 0 0 1-.66-.28 1.54 1.54 0 0 1-.58-.6 1.7 1.7 0 0 1-.17-.77c0-.44.14-.82.4-1.15a5.16 5.16 0 0 1 2.16-1.17v-.05c-.48-.16-.9-.34-1.26-.55a3.73 3.73 0 0 1-1.3-1.32 3.78 3.78 0 0 1-.4-1.75Zm2.97 8.17c.1-.09.2-.18.34-.28.28.02.57.03.9.03a73.12 73.12 0 0 0 3.56-.09 91.74 91.74 0 0 1 3.75-.1c.44 0 .79.03 1.03.1.25.06.43.16.53.3.12.13.17.3.17.51a.8.8 0 0 1-.25.58 1.8 1.8 0 0 1-.84.42c-.38.12-.91.2-1.6.26a34.4 34.4 0 0 1-6.42-.1c-.4-.06-.7-.14-.92-.24a1.1 1.1 0 0 1-.45-.34.83.83 0 0 1 .2-1.05Zm9.22-8.17c0-.46-.16-.85-.47-1.18a2.9 2.9 0 0 0-1.45-.74 9.69 9.69 0 0 0-2.57-.28c-1.06 0-1.93.1-2.6.28-.67.17-1.16.42-1.47.74a1.63 1.63 0 0 0 0 2.24c.3.3.77.54 1.43.7.67.18 1.55.26 2.64.26 1.07 0 1.93-.07 2.59-.23.65-.17 1.13-.4 1.43-.7.3-.32.47-.68.47-1.1Zm-14.53-6.36a1.25 1.25 0 0 0 .02-.84.57.57 0 0 0-.2-.3.84.84 0 0 0-.38-.23 5.67 5.67 0 0 0-1.54-.21c-.45 0-.83.03-1.13.08-.28.04-.5.12-.66.22a.78.78 0 0 0-.32.36 1.1 1.1 0 0 0-.08.45c0 .14.01.27.04.38.03.11.09.23.17.34.1.1.23.19.39.26.17.07.38.13.64.17a6.65 6.65 0 0 0 2.06-.02c.3-.07.53-.17.67-.28a.9.9 0 0 0 .32-.38Zm-3.89 14.83h3.55a506.43 506.43 0 0 0-.07-3.03V9.66c0-.48 0-.97.02-1.45l.05-1.5h-3.55c.02.52.02 1.01.02 1.5.02.48.03.97.03 1.45l.02 1.52v3.56l-.02 1.64-.03 1.56c0 .51 0 1.04-.02 1.58Zm-20.64 0h3.72a102.25 102.25 0 0 1-.09-2.58v-3.12c0-.77.1-1.41.3-1.94a3.14 3.14 0 0 1 2.27-2.03 8.9 8.9 0 0 1 5 .32 23.1 23.1 0 0 1 .14-1.62l.1-.85c.03-.27.07-.5.11-.69a9.23 9.23 0 0 0-3.1-.51c-.75 0-1.44.1-2.07.3-.6.18-1.15.48-1.62.87a4.95 4.95 0 0 0-1.41 2.17l-.15-.02v-.2a381.87 381.87 0 0 1 .09-2.9h-3.29a255.09 255.09 0 0 1 0 12.8ZM49.66 6.72a82.9 82.9 0 0 1 2.2.02V4.03c.28 0 .58 0 .87.02h2.03l.56-.03-.05 2.33v.4h3.23l2.43-.01 2.16-.03a65.92 65.92 0 0 0-.07 1.88v.92l-1.47-.02c-.51-.02-1.06-.02-1.64-.02-.57-.02-1.16-.02-1.78-.02a77.1 77.1 0 0 0-1.83-.03l-1.07-.01c0 .64 0 1.31-.02 2v2.9c0 .54.1 1 .3 1.39.2.37.54.65 1.02.83.49.19 1.15.28 1.99.28a12.78 12.78 0 0 0 4.33-.64l.09.62.08.6c.05.2.08.4.1.62l.12.57.12.56c-.54.11-1.08.21-1.64.3a29.41 29.41 0 0 1-3.59.25 13 13 0 0 1-2.51-.21 6.44 6.44 0 0 1-1.82-.66 4.2 4.2 0 0 1-1.17-1.05 3.8 3.8 0 0 1-.62-1.32 6.16 6.16 0 0 1-.2-1.58V11.6c.02-.65.03-1.32.03-2v-.2h-.75l-1.4-.02V8.06c0-.26-.02-.5-.03-.73v-.62ZM42.33 17.3c-.57.06-1.28.09-2.13.09-.93 0-1.71-.04-2.35-.11a5.9 5.9 0 0 1-1.54-.34 1.83 1.83 0 0 1-.83-.6 1.52 1.52 0 0 1-.26-.9v-.32a7 7 0 0 1-.68.07H33.1a21.65 21.65 0 0 1-.96-.06v.4a4.11 4.11 0 0 0 .23 1.69c.19.44.47.83.86 1.17.38.33.89.6 1.51.83.63.22 1.38.37 2.24.47.89.12 1.92.17 3.1.17 1.42 0 2.62-.08 3.58-.25a7.75 7.75 0 0 0 2.37-.75 3.24 3.24 0 0 0 1.33-1.26c.27-.51.4-1.1.4-1.75 0-.64-.1-1.19-.32-1.64a2.6 2.6 0 0 0-1.06-1.18 6.72 6.72 0 0 0-2.14-.74c-.9-.19-2.06-.32-3.48-.39a28.8 28.8 0 0 1-2.82-.21c-.7-.1-1.22-.22-1.58-.34-.35-.15-.6-.31-.72-.5a1.16 1.16 0 0 1 .02-1.23c.14-.19.38-.34.7-.45.33-.13.77-.22 1.33-.28.55-.06 1.25-.08 2.09-.08.88 0 1.61.03 2.2.1.58.06 1.04.17 1.39.32a1.45 1.45 0 0 1 .98 1.39V11l.62-.02h1.45l.53.02c.17 0 .32.01.45.03v-.22l.02-.21v-.21c0-.6-.1-1.13-.3-1.58-.2-.46-.5-.84-.92-1.16-.4-.31-.9-.56-1.51-.74-.6-.2-1.3-.35-2.11-.43-.82-.1-1.73-.15-2.76-.15-1.36 0-2.53.09-3.5.26a7.3 7.3 0 0 0-2.32.72c-.59.33-1.02.73-1.29 1.22-.27.48-.4 1.05-.4 1.7 0 .58.1 1.1.32 1.56.21.46.58.86 1.1 1.2.54.33 1.25.59 2.16.79.93.2 2.1.33 3.5.4 1.14.05 2.05.11 2.74.2.7.08 1.22.2 1.58.34.37.14.62.3.74.49.13.18.2.4.2.64 0 .26-.07.48-.22.68-.14.2-.38.37-.72.5-.34.1-.8.2-1.39.27Zm106.58-7.8h.53v1.18c0 .5 0 1.02-.02 1.56 0 .52 0 1.04-.02 1.53v1.37c0 .68.1 1.3.32 1.88.23.57.58 1.06 1.05 1.47.48.41 1.1.73 1.87.96.77.23 1.7.34 2.8.34.64 0 1.23-.02 1.77-.08a14 14 0 0 0 1.6-.22c.53-.1 1.06-.22 1.58-.36l-.15-.92-.13-1.04-.1-1a9.42 9.42 0 0 1-3.9.61c-.75 0-1.37-.07-1.87-.21-.48-.16-.84-.4-1.08-.75a2.53 2.53 0 0 1-.34-1.38v-2.95l.02-1.96.94.02a69.12 69.12 0 0 1 3.39.06c.54 0 1.05 0 1.54.02l1.34.02V8.7l.02-1.02.05-.92-1.86.04h-5.39v-.34c.04-.78.06-1.56.07-2.34h-.15a6.35 6.35 0 0 1-2.32 2.1 7.83 7.83 0 0 1-2.88.99v2.31h1.32ZM78.25 19.66h2.95a7.91 7.91 0 0 1-.23-1.58 712.43 712.43 0 0 1-.07-2.22v-1.48a1459.86 1459.86 0 0 1 .07-2.83c0-.79-.14-1.48-.41-2.1a3.73 3.73 0 0 0-1.28-1.6c-.6-.44-1.4-.77-2.41-1a16.44 16.44 0 0 0-3.76-.36 24.73 24.73 0 0 0-5.31.57 19 19 0 0 0-2.33.62l.13.62a20.33 20.33 0 0 1 .45 2.28 9.79 9.79 0 0 1 2.09-.74 19.14 19.14 0 0 1 4.74-.6c.9 0 1.63.06 2.22.17.58.11 1.04.29 1.38.51.34.22.59.48.73.8.14.3.21.68.21 1.1a16.87 16.87 0 0 1-.02.93c-.3-.07-.64-.13-1.02-.18a34.32 34.32 0 0 0-3.97-.23c-1.26 0-2.34.07-3.27.23-.91.14-1.66.37-2.26.68-.59.32-1.02.71-1.3 1.2a4.26 4.26 0 0 0-.1 3.44c.2.48.53.88.97 1.19a4.7 4.7 0 0 0 1.73.68c.7.15 1.53.22 2.5.22 1.34 0 2.5-.14 3.48-.4 1-.3 1.78-.72 2.37-1.29.36-.35.64-.75.82-1.2h.13a37.88 37.88 0 0 0-.01 2.16c.02.11.07.2.12.26.07.05.16.1.26.13l.4.02Zm-.87-5.45c-.8-.1-1.6-.17-2.4-.21-.87-.04-1.81-.06-2.8-.06-.66 0-1.22.04-1.67.12-.46.08-.83.18-1.11.32-.29.15-.5.33-.64.56-.13.23-.2.5-.2.81 0 .3.06.56.18.79.1.23.29.42.53.58.25.14.59.25 1 .34a12.03 12.03 0 0 0 3.9-.1c.7-.17 1.29-.38 1.76-.65.48-.27.84-.59 1.09-.96.24-.37.36-.78.36-1.22v-.32Z" clip-rule="evenodd"/>
+  <defs>
+    <linearGradient id="a" x1="0" x2="23.09" y1="2.15" y2="25.55" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#FCECC5"/>
+      <stop offset="1" stop-color="#EEBD52"/>
+    </linearGradient>
+  </defs>
+</svg>
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 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -7 161 40">
+  <path fill="url(#a)" fill-rule="evenodd" d="M15.22 7.77 12.06.94 8.91 7.77l-.15.29L7 6.3a1.18 1.18 0 1 0-1.68 1.68l1.75 1.74-.2.1-.04.02L0 13l6.83 3.16.24.11-1.75 1.76A1.18 1.18 0 1 0 7 19.7l1.76-1.76.15.3 3.15 6.82 3.16-6.83.12-.24 1.71 1.71a1.18 1.18 0 1 0 1.68-1.67L17 16.3l.29-.15L24.13 13 17.3 9.84 17 9.7l1.73-1.73a1.18 1.18 0 1 0-1.68-1.67L15.35 8a4.15 4.15 0 0 1-.12-.21l-.01-.03Zm-3.17.36-.42.9a7.27 7.27 0 0 1-3.55 3.55l-.9.42.9.42a7.27 7.27 0 0 1 3.55 3.55l.42.9.42-.9a7.27 7.27 0 0 1 3.55-3.55l.9-.42-.9-.42a7.27 7.27 0 0 1-3.55-3.55l-.42-.9Z" clip-rule="evenodd"/>
+  <path fill="url(#a)" d="M22.27 4.43a1.18 1.18 0 1 0-1.67-1.68l-.57.57a1.18 1.18 0 0 0 1.68 1.67l.56-.56ZM4.2 5.18c-.46.46-1.2.46-1.67 0l-.56-.56a1.18 1.18 0 0 1 1.67-1.68l.57.57c.46.46.46 1.2 0 1.67Zm0 15.64a1.18 1.18 0 0 0-1.67 0l-.56.56a1.18 1.18 0 0 0 1.67 1.68l.57-.57c.46-.46.46-1.2 0-1.67Zm18.07.75a1.18 1.18 0 0 1-1.67 1.68l-.57-.57a1.19 1.19 0 0 1 1.68-1.67l.56.56Z"/>
+  <path fill="#23262D" fill-rule="evenodd" d="M101.72 19.52h-3.55a89.91 89.91 0 0 0 .06-3.93V9.08c0-.7 0-1.4-.02-2.05 0-.65 0-1.3-.02-1.96 0-.65 0-1.34-.02-2.07h3.57l-.07 2.03v12.55l.05 1.94Zm44.45 0h-3.63c.02-.57.02-1.2.02-1.9.02-.7.02-1.46.02-2.28.02-.83.02-1.7.02-2.63 0-.84-.14-1.5-.42-2a2.35 2.35 0 0 0-1.33-1.11c-.6-.25-1.4-.37-2.4-.37-.7 0-1.37.08-2 .24-.6.15-1.14.4-1.61.72-.46.33-.81.76-1.07 1.28a4.07 4.07 0 0 0-.39 1.84v3.44l.03 1.15v.9l.02.72h-3.63a90.31 90.31 0 0 0 .06-3.9v-4.81c0-.72 0-1.42-.02-2.1V6.67c0-.67 0-1.3-.02-1.92 0-.63 0-1.2-.02-1.75h3.67a1231.15 1231.15 0 0 1-.06 3.95 64.28 64.28 0 0 1-.05 2.5l.12.03a4.76 4.76 0 0 1 3.17-2.64 11.3 11.3 0 0 1 3.27-.42c.98 0 1.85.1 2.62.32a5.1 5.1 0 0 1 1.94.98 4 4 0 0 1 1.24 1.66c.29.67.43 1.47.43 2.4 0 .4 0 .78-.02 1.1v.92l-.02.81v2.91l.06 2Zm-35.18-8.47a3.63 3.63 0 0 1 1.92-3.29 7.7 7.7 0 0 1 2.39-.83 17.66 17.66 0 0 1 4.14-.26h1.54c.62 0 1.3 0 2.05.02.75.02 1.52.02 2.3.02h2.3v.43c0 .21 0 .46-.02.73v.72l.03.5a26.5 26.5 0 0 1-2.18-.1 266.79 266.79 0 0 0-1.92-.12v.14a6.23 6.23 0 0 1 2.03.93c.27.21.47.47.6.79.12.3.19.64.19 1.04a2.53 2.53 0 0 1-.7 1.8c-.24.25-.55.49-.95.7-.4.2-.88.37-1.45.51s-1.24.26-2 .34c-.77.07-1.65.11-2.63.11-1.36 0-2.52-.09-3.5-.26l-.21.2a1.7 1.7 0 0 0-.33.49c-.07.15-.1.32-.1.49 0 .27.1.46.32.57.23.12.53.18.92.18a85.08 85.08 0 0 0 5.25-.15 58.4 58.4 0 0 1 2.15-.05c1.01 0 1.84.1 2.48.28.65.19 1.14.48 1.45.9.33.41.5.95.5 1.62a3 3 0 0 1-.18 1.02c-.1.32-.27.6-.51.86-.24.25-.58.48-1 .68-.42.2-.94.37-1.58.51a17 17 0 0 1-2.29.32 55.99 55.99 0 0 1-6.87 0 20.42 20.42 0 0 1-2.5-.3 5.4 5.4 0 0 1-1.45-.47c-.33-.18-.56-.4-.68-.64a1.65 1.65 0 0 1 .04-1.53c.16-.23.38-.43.68-.6a5.11 5.11 0 0 1 1.58-.57v-.09a2.94 2.94 0 0 1-.66-.28 1.54 1.54 0 0 1-.58-.6 1.7 1.7 0 0 1-.17-.77c0-.44.14-.82.4-1.15a5.16 5.16 0 0 1 2.16-1.17v-.05c-.48-.16-.9-.34-1.26-.55a3.73 3.73 0 0 1-1.3-1.32 3.78 3.78 0 0 1-.4-1.75Zm2.97 8.17c.1-.09.2-.18.34-.28.28.02.57.03.9.03a73.12 73.12 0 0 0 3.56-.09 91.74 91.74 0 0 1 3.75-.1c.44 0 .79.03 1.03.1.25.06.43.16.53.3.12.13.17.3.17.51a.8.8 0 0 1-.25.58 1.8 1.8 0 0 1-.84.42c-.38.12-.91.2-1.6.26a34.4 34.4 0 0 1-6.42-.1c-.4-.06-.7-.14-.92-.24a1.1 1.1 0 0 1-.45-.34.83.83 0 0 1 .2-1.05Zm9.22-8.17c0-.46-.16-.85-.47-1.18a2.9 2.9 0 0 0-1.45-.74 9.69 9.69 0 0 0-2.57-.28c-1.06 0-1.93.1-2.6.28-.67.17-1.16.42-1.47.74a1.63 1.63 0 0 0 0 2.24c.3.3.77.54 1.43.7.67.18 1.55.26 2.64.26 1.07 0 1.93-.07 2.59-.23.65-.17 1.13-.4 1.43-.7.3-.32.47-.68.47-1.1Zm-14.53-6.36a1.25 1.25 0 0 0 .02-.84.57.57 0 0 0-.2-.3.84.84 0 0 0-.38-.23 5.67 5.67 0 0 0-1.54-.21c-.45 0-.83.03-1.13.08-.28.04-.5.12-.66.22a.78.78 0 0 0-.32.36 1.1 1.1 0 0 0-.08.45c0 .14.01.27.04.38.03.11.09.23.17.34.1.1.23.19.39.26.17.07.38.13.64.17a6.65 6.65 0 0 0 2.06-.02c.3-.07.53-.17.67-.28a.9.9 0 0 0 .32-.38Zm-3.89 14.83h3.55a506.43 506.43 0 0 0-.07-3.03V9.66c0-.48 0-.97.02-1.45l.05-1.5h-3.55c.02.52.02 1.01.02 1.5.02.48.03.97.03 1.45l.02 1.52v3.56l-.02 1.64-.03 1.56c0 .51 0 1.04-.02 1.58Zm-20.64 0h3.72a102.25 102.25 0 0 1-.09-2.58v-3.12c0-.77.1-1.41.3-1.94a3.14 3.14 0 0 1 2.27-2.03 8.9 8.9 0 0 1 5 .32 23.1 23.1 0 0 1 .14-1.62l.1-.85c.03-.27.07-.5.11-.69a9.23 9.23 0 0 0-3.1-.51c-.75 0-1.44.1-2.07.3-.6.18-1.15.48-1.62.87a4.95 4.95 0 0 0-1.41 2.17l-.15-.02v-.2a381.87 381.87 0 0 1 .09-2.9h-3.29a255.09 255.09 0 0 1 0 12.8ZM49.66 6.72a82.9 82.9 0 0 1 2.2.02V4.03c.28 0 .58 0 .87.02h2.03l.56-.03-.05 2.33v.4h3.23l2.43-.01 2.16-.03a65.92 65.92 0 0 0-.07 1.88v.92l-1.47-.02c-.51-.02-1.06-.02-1.64-.02-.57-.02-1.16-.02-1.78-.02a77.1 77.1 0 0 0-1.83-.03l-1.07-.01c0 .64 0 1.31-.02 2v2.9c0 .54.1 1 .3 1.39.2.37.54.65 1.02.83.49.19 1.15.28 1.99.28a12.78 12.78 0 0 0 4.33-.64l.09.62.08.6c.05.2.08.4.1.62l.12.57.12.56c-.54.11-1.08.21-1.64.3a29.41 29.41 0 0 1-3.59.25 13 13 0 0 1-2.51-.21 6.44 6.44 0 0 1-1.82-.66 4.2 4.2 0 0 1-1.17-1.05 3.8 3.8 0 0 1-.62-1.32 6.16 6.16 0 0 1-.2-1.58V11.6c.02-.65.03-1.32.03-2v-.2h-.75l-1.4-.02V8.06c0-.26-.02-.5-.03-.73v-.62ZM42.33 17.3c-.57.06-1.28.09-2.13.09-.93 0-1.71-.04-2.35-.11a5.9 5.9 0 0 1-1.54-.34 1.83 1.83 0 0 1-.83-.6 1.52 1.52 0 0 1-.26-.9v-.32a7 7 0 0 1-.68.07H33.1a21.65 21.65 0 0 1-.96-.06v.4a4.11 4.11 0 0 0 .23 1.69c.19.44.47.83.86 1.17.38.33.89.6 1.51.83.63.22 1.38.37 2.24.47.89.12 1.92.17 3.1.17 1.42 0 2.62-.08 3.58-.25a7.75 7.75 0 0 0 2.37-.75 3.24 3.24 0 0 0 1.33-1.26c.27-.51.4-1.1.4-1.75 0-.64-.1-1.19-.32-1.64a2.6 2.6 0 0 0-1.06-1.18 6.72 6.72 0 0 0-2.14-.74c-.9-.19-2.06-.32-3.48-.39a28.8 28.8 0 0 1-2.82-.21c-.7-.1-1.22-.22-1.58-.34-.35-.15-.6-.31-.72-.5a1.16 1.16 0 0 1 .02-1.23c.14-.19.38-.34.7-.45.33-.13.77-.22 1.33-.28.55-.06 1.25-.08 2.09-.08.88 0 1.61.03 2.2.1.58.06 1.04.17 1.39.32a1.45 1.45 0 0 1 .98 1.39V11l.62-.02h1.45l.53.02c.17 0 .32.01.45.03v-.22l.02-.21v-.21c0-.6-.1-1.13-.3-1.58-.2-.46-.5-.84-.92-1.16-.4-.31-.9-.56-1.51-.74-.6-.2-1.3-.35-2.11-.43-.82-.1-1.73-.15-2.76-.15-1.36 0-2.53.09-3.5.26a7.3 7.3 0 0 0-2.32.72c-.59.33-1.02.73-1.29 1.22-.27.48-.4 1.05-.4 1.7 0 .58.1 1.1.32 1.56.21.46.58.86 1.1 1.2.54.33 1.25.59 2.16.79.93.2 2.1.33 3.5.4 1.14.05 2.05.11 2.74.2.7.08 1.22.2 1.58.34.37.14.62.3.74.49.13.18.2.4.2.64 0 .26-.07.48-.22.68-.14.2-.38.37-.72.5-.34.1-.8.2-1.39.27Zm106.58-7.8h.53v1.18c0 .5 0 1.02-.02 1.56 0 .52 0 1.04-.02 1.53v1.37c0 .68.1 1.3.32 1.88.23.57.58 1.06 1.05 1.47.48.41 1.1.73 1.87.96.77.23 1.7.34 2.8.34.64 0 1.23-.02 1.77-.08a14 14 0 0 0 1.6-.22c.53-.1 1.06-.22 1.58-.36l-.15-.92-.13-1.04-.1-1a9.42 9.42 0 0 1-3.9.61c-.75 0-1.37-.07-1.87-.21-.48-.16-.84-.4-1.08-.75a2.53 2.53 0 0 1-.34-1.38v-2.95l.02-1.96.94.02a69.12 69.12 0 0 1 3.39.06c.54 0 1.05 0 1.54.02l1.34.02V8.7l.02-1.02.05-.92-1.86.04h-5.39v-.34c.04-.78.06-1.56.07-2.34h-.15a6.35 6.35 0 0 1-2.32 2.1 7.83 7.83 0 0 1-2.88.99v2.31h1.32ZM78.25 19.66h2.95a7.91 7.91 0 0 1-.23-1.58 712.43 712.43 0 0 1-.07-2.22v-1.48a1459.86 1459.86 0 0 1 .07-2.83c0-.79-.14-1.48-.41-2.1a3.73 3.73 0 0 0-1.28-1.6c-.6-.44-1.4-.77-2.41-1a16.44 16.44 0 0 0-3.76-.36 24.73 24.73 0 0 0-5.31.57 19 19 0 0 0-2.33.62l.13.62a20.33 20.33 0 0 1 .45 2.28 9.79 9.79 0 0 1 2.09-.74 19.14 19.14 0 0 1 4.74-.6c.9 0 1.63.06 2.22.17.58.11 1.04.29 1.38.51.34.22.59.48.73.8.14.3.21.68.21 1.1a16.87 16.87 0 0 1-.02.93c-.3-.07-.64-.13-1.02-.18a34.32 34.32 0 0 0-3.97-.23c-1.26 0-2.34.07-3.27.23-.91.14-1.66.37-2.26.68-.59.32-1.02.71-1.3 1.2a4.26 4.26 0 0 0-.1 3.44c.2.48.53.88.97 1.19a4.7 4.7 0 0 0 1.73.68c.7.15 1.53.22 2.5.22 1.34 0 2.5-.14 3.48-.4 1-.3 1.78-.72 2.37-1.29.36-.35.64-.75.82-1.2h.13a37.88 37.88 0 0 0-.01 2.16c.02.11.07.2.12.26.07.05.16.1.26.13l.4.02Zm-.87-5.45c-.8-.1-1.6-.17-2.4-.21-.87-.04-1.81-.06-2.8-.06-.66 0-1.22.04-1.67.12-.46.08-.83.18-1.11.32-.29.15-.5.33-.64.56-.13.23-.2.5-.2.81 0 .3.06.56.18.79.1.23.29.42.53.58.25.14.59.25 1 .34a12.03 12.03 0 0 0 3.9-.1c.7-.17 1.29-.38 1.76-.65.48-.27.84-.59 1.09-.96.24-.37.36-.78.36-1.22v-.32Z" clip-rule="evenodd"/>
+  <defs>
+    <linearGradient id="a" x1="2.5" x2="21.61" y1="2.65" y2="25.4" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#FCDF9C"/>
+      <stop offset="1" stop-color="#DA990B"/>
+    </linearGradient>
+  </defs>
+</svg>
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 `<meta name="description">` 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 @@
 /// <reference path="../.astro/types.d.ts" />
-/// <reference types="astro/client" />
+/// <reference types="astro/client-image" />
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 {
 ---
 
 <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;
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);
+}
+---
+
+<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>
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<ReturnType<typeof LogoConfigSchema>>;
+export type LogoConfig = z.output<ReturnType<typeof LogoConfigSchema>>;
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;
+  };
+}