Add a customization guide (#230)

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

2 files changed, 436 insertions, 0 deletions

diff --git a/docs/src/content/docs/guides/customization.mdx b/docs/src/content/docs/guides/customization.mdx
new file mode 100644
index 00000000..d7d3e5bd
--- /dev/null
+++ b/docs/src/content/docs/guides/customization.mdx
@@ -0,0 +1,420 @@
+---
+title: Customizing Starlight
+description: Learn how to make your Starlight site your own with custom styles, fonts, and more.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import FileTree from '../../../components/file-tree.astro';
+
+Starlight provides sensible default styling and features, so you can get started quickly with no configuration needed.
+When you want to start customizing the look and feel of your Starlight site, this guide has you covered.
+
+## Add your logo
+
+Adding a custom logo to the site header is a quick way to add your individual branding to a Starlight site.
+
+1. Add your logo image file to the `src/assets/` directory:
+
+   <FileTree>
+
+   - src/
+     - assets/
+       - **my-logo.svg**
+     - content/
+   - astro.config.mjs
+
+   </FileTree>
+
+2. Add the path to your logo as Starlight’s [`logo.src`](/reference/configuration/#logo) option in `astro.config.mjs`:
+
+   ```js
+   // astro.config.mjs
+   import { defineConfig } from 'astro/config';
+   import starlight from '@astrojs/starlight';
+
+   export default defineConfig({
+     integrations: [
+       starlight({
+         title: 'Docs With My Logo',
+         logo: {
+           src: '/src/assets/my-logo.svg',
+         },
+       }),
+     ],
+   });
+   ```
+
+By default, the logo will be displayed alongside your site’s `title`.
+If your logo image already includes the site title, you can visually hide the title text by setting the `replacesTitle` option.
+The `title` text will still be included for screen readers so that the header remains accessible.
+
+```js
+starlight({
+  title: 'Docs With My Logo',
+  logo: {
+    src: '/src/assets/my-logo.svg',
+    replacesTitle: true,
+  },
+}),
+```
+
+### Light and dark logo variants
+
+You can display different versions of your logo in light and dark modes.
+
+1. Add an image file for each variant to `src/assets/`:
+
+   <FileTree>
+
+   - src/
+     - assets/
+       - **light-logo.svg**
+       - **dark-logo.svg**
+     - content/
+   - astro.config.mjs
+
+   </FileTree>
+
+2. Add the path to your logo variants as the `light` and `dark` options instead of `src` in `astro.config.mjs`:
+
+   ```js
+   starlight({
+     title: 'Docs With My Logo',
+     logo: {
+       light: '/src/assets/light-logo.svg',
+       dark: '/src/assets/dark-logo.svg',
+     },
+   }),
+   ```
+
+## Page layout
+
+By default, Starlight pages use a layout with a global navigation sidebar and a table of contents that shows the current page headings.
+
+You can apply a wider page layout without sidebars by setting [`template: splash`](/reference/frontmatter/#template) in a page’s frontmatter.
+This works particularly well for landing pages and you can see it in action on the [homepage of this site](/).
+
+```md
+---
+# src/content/docs/index.md
+
+title: My Landing Page
+template: splash
+---
+```
+
+## Table of contents
+
+Starlight displays a table of contents on each page to make it easier for readers to jump to the heading they are looking for.
+You can customize — or even disable — the table of contents globally in the Starlight integration or on a page-by-page basis in frontmatter.
+
+By default, `<h2>` and `<h3>` headings are included in the table of contents. Change which headings levels to include site-wide using the `minHeadingLevel` and `maxHeadingLevel` options in your [global `tableOfContents`](/reference/configuration/#tableofcontents). Override these defaults on an individual page by adding the corresponding [frontmatter `tableOfContents`](/reference/frontmatter/#tableofcontents) properties:
+
+<Tabs>
+  <TabItem label="Frontmatter">
+
+```md
+---
+# src/content/docs/example.md
+title: Page with only H2s in the table of contents
+tableOfContents:
+  minHeadingLevel: 2
+  maxHeadingLevel: 2
+---
+```
+
+  </TabItem>
+  <TabItem label="Global config">
+
+```js
+// astro.config.mjs
+
+defineConfig({
+  integrations: [
+    starlight({
+      title: '',
+      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
+    }),
+  ],
+});
+```
+
+  </TabItem>
+</Tabs>
+
+Disable the table of contents entirely by setting the `tableOfContents` option to `false`:
+
+<Tabs>
+  <TabItem label="Frontmatter">
+
+```md
+---
+# src/content/docs/example.md
+title: Page without a table of contents
+tableOfContents: false
+---
+```
+
+  </TabItem>
+  <TabItem label="Global config">
+
+```js
+// astro.config.mjs
+
+defineConfig({
+  integrations: [
+    starlight({
+      title: 'Docs with table of contents disabled globally',
+      tableOfContents: false,
+    }),
+  ],
+});
+```
+
+  </TabItem>
+</Tabs>
+
+## Social links
+
+Starlight has built-in support for adding links to your social media accounts to the site header via the [`social`](/reference/configuration/#social) option in the Starlight integration.
+
+Currently, links to Discord, GitHub, Mastodon, and Twitter are supported.
+Let us know on GitHub or Discord if you need support for another service!
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: 'Docs With Social Links',
+      social: {
+        discord: 'https://astro.build/chat',
+        github: 'https://github.com/withastro/starlight',
+        mastodon: 'https://m.webtoo.ls/@astro',
+        twitter: 'https://twitter.com/astrodotbuild',
+      },
+    }),
+  ],
+});
+```
+
+## Edit links
+
+Starlight can display an “Edit page” link in each page’s footer.
+This makes it easy for a reader to find the file to edit to improve your docs.
+For open-source projects in particular, this can help encourage contributions from your community.
+
+To enable edit links, set [`editLink.baseUrl`](/reference/configuration/#editlink) to the URL used to edit your repository in the Starlight integration config.
+The value of `editLink.baseUrl` will be prepended to the path to the current page to form the full edit link.
+
+Common patterns include:
+
+- GitHub: `https://github.com/USER_NAME/REPO_NAME/edit/BRANCH_NAME/`
+- GitLab: `https://gitlab.com/USER_NAME/REPO_NAME/-/edit/BRANCH_NAME/`
+
+If your Starlight project is not in the root of your repository, include the path to the project at the end of the base URL.
+
+This example shows the edit link configured for the Starlight docs, which live in the `docs/` subdirectory on the `main` branch of the `withastro/starlight` repository on GitHub:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: 'Docs With Edit Links',
+      editLink: {
+        baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
+      },
+    }),
+  ],
+});
+```
+
+## Custom CSS styles
+
+Customize the styles applied to your Starlight site by providing additional CSS files to modify or extend Starlight’s default styles.
+
+1. Add a CSS file to your `src/` directory.
+   For example, you could override Starlight’s default blue accent hue to purple:
+
+   ```css
+   /* src/styles/custom.css */
+   :root {
+     --sl-hue-accent: 270;
+   }
+   ```
+
+2. Add the path to your CSS file to Starlight’s `customCss` array in `astro.config.mjs`:
+
+   ```js
+   // astro.config.mjs
+   import { defineConfig } from 'astro/config';
+   import starlight from '@astrojs/starlight';
+
+   export default defineConfig({
+     integrations: [
+       starlight({
+         title: 'Docs With Custom CSS',
+         customCss: [
+           // Path to your custom CSS file, starting with /
+           '/src/styles/custom.css',
+         ],
+       }),
+     ],
+   });
+   ```
+
+## Custom fonts
+
+By default, Starlight uses sans-serif fonts available on a user’s local device for all text.
+This ensures documentation loads quickly in a font that is familiar to each user, without requiring extra bandwidth to download large font files.
+
+If you must add a custom font to your Starlight site, you can set up fonts to use in custom CSS files or with any other [Astro styling technique](https://docs.astro.build/en/guides/styling/).
+
+### Set up fonts
+
+If you already have font files, follow the [local set-up guide](#set-up-local-font-files).
+To use Google Fonts, follow the [Fontsource set-up guide](#set-up-a-fontsource-font).
+
+#### Set up local font files
+
+1. Add your font files to a `src/fonts/` directory and create an empty `font-face.css` file:
+
+   <FileTree>
+
+   - src/
+     - content/
+     - fonts/
+       - **CustomFont.woff2**
+       - **font-face.css**
+   - astro.config.mjs
+
+   </FileTree>
+
+2. Add an [`@font-face` declaration](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) for each of your fonts in `src/fonts/font-face.css`.
+   Use a relative path to the font file in the `url()` function.
+
+   ```css
+   /* src/fonts/font-face.css */
+
+   @font-face {
+     font-family: 'Custom Font';
+     /* Use a relative path to the local font file in `url()`. */
+     src: url('./CustomFont.woff2') format('woff2');
+     font-weight: normal;
+     font-style: normal;
+     font-display: swap;
+   }
+   ```
+
+3. Add the path to your `font-face.css` file to Starlight’s `customCss` array in `astro.config.mjs`:
+
+   ```js
+   // astro.config.mjs
+   import { defineConfig } from 'astro/config';
+   import starlight from '@astrojs/starlight';
+
+   export default defineConfig({
+     integrations: [
+       starlight({
+         title: 'Docs With a Custom Typeface',
+         customCss: [
+           // Path to your @font-face CSS file.
+           '/src/fonts/font-face.css',
+         ],
+       }),
+     ],
+   });
+   ```
+
+#### Set up a Fontsource font
+
+The [Fontsource](https://fontsource.org/) project simplifies using Google Fonts and other open-source fonts.
+It provides npm modules you can install for the fonts you want to use and includes ready-made CSS files to add to your project.
+
+1.  Find the font you want to use in [Fontsource’s catalog](https://fontsource.org/).
+    This example will use [IBM Plex Serif](https://fontsource.org/fonts/ibm-plex-serif).
+
+2.  Install the package for your chosen font.
+    You can find the package name by clicking “Install” on the Fontsource font page.
+
+         <Tabs>
+
+    <TabItem label="npm">
+
+    ```sh
+    npm install @fontsource/ibm-plex-serif
+    ```
+
+           </TabItem>
+
+        <TabItem label="pnpm">
+
+    ```sh
+    pnpm install @fontsource/ibm-plex-serif
+    ```
+
+           </TabItem>
+
+        <TabItem label="Yarn">
+
+    ```sh
+    yarn add @fontsource/ibm-plex-serif
+    ```
+
+           </TabItem>
+
+      </Tabs>
+
+3.  Add Fontsource CSS files to Starlight’s `customCss` array in `astro.config.mjs`:
+
+    ```js
+    // astro.config.mjs
+    import { defineConfig } from 'astro/config';
+    import starlight from '@astrojs/starlight';
+
+    export default defineConfig({
+      integrations: [
+        starlight({
+          title: 'Docs With a Custom Typeface',
+          customCss: [
+            // Fontsource files for to regular and semi-bold font weights.
+            '@fontsource/ibm-plex-serif/400.css',
+            '@fontsource/ibm-plex-serif/600.css',
+          ],
+        }),
+      ],
+    });
+    ```
+
+    Fontsource ships multiple CSS files for each font. See the [Fontsource documentation](https://fontsource.org/docs/getting-started/install#4-weights-and-styles) on including different weights and styles to understand which to use.
+
+### Use fonts
+
+To apply the font you set up to your site, use your chosen font’s name in a custom CSS file.
+For example, to override Starlight’s default font everywhere, set the `--sl-font` custom property:
+
+```css
+/* src/styles/custom.css */
+
+:root {
+  --sl-font: 'IBM Plex Serif', serif;
+}
+```
+
+You can also write more targeted CSS if you want to apply your font more selectively.
+For example, to only set a font on the main content, but not the sidebars:
+
+```css
+/* src/styles/custom.css */
+
+main {
+  font-family: 'IBM Plex Serif', serif;
+}
+```
diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index 7d1f04cc..66620541 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/docs/src/content/docs/reference/frontmatter.md
@@ -57,6 +57,22 @@ head:
 Overrides the [global `tableOfContents` config](/reference/configuration/#tableofcontents).
 Customize the heading levels to be included or set to `false` to hide the table of contents on this page.
 
+```md
+---
+title: Page with only H2s in the table of contents
+tableOfContents:
+  minHeadingLevel: 2
+  maxHeadingLevel: 2
+---
+```
+
+```md
+---
+title: Page with no table of contents
+tableOfContents: false
+---
+```
+
 ### `template`
 
 **type:** `'doc' | 'splash'`