@astrojs/starlight 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @astrojs/starlight
 
+## 0.0.4
+
+### Patch Changes
+
+- [#40](https://github.com/withastro/starlight/pull/40) [`e22dd76`](https://github.com/withastro/starlight/commit/e22dd76136f9749bb5d43f96241385faccfc90a1) Thanks [@delucis](https://github.com/delucis)! - Generate sitemaps for Starlight sites
+
+- [#38](https://github.com/withastro/starlight/pull/38) [`623b577`](https://github.com/withastro/starlight/commit/623b577319b1dea2d6c42f1b680139fb858d85d6) Thanks [@delucis](https://github.com/delucis)! - Add tab components for use in MDX.
+
+## 0.0.3
+
+### Patch Changes
+
+- [`1f62c75`](https://github.com/withastro/starlight/commit/1f62c75297ed44da721350840744823876a64bc5) Thanks [@delucis](https://github.com/delucis)! - Add repo, issues & homepage links to package.json
+
+- [#36](https://github.com/withastro/starlight/pull/36) [`62265e4`](https://github.com/withastro/starlight/commit/62265e4a653d161483e3844b568ab150334e9238) Thanks [@delucis](https://github.com/delucis)! - Collapse table of contents in dropdown on narrower viewports
+
 ## 0.0.2
 
 ### Patch Changes

package/README.md

@@ -1,4 +1,4 @@
-# Starlight
+# <img src="https://github.com/withastro/starlight/assets/357379/494fcd83-42aa-4891-87e0-87402fa0b6f3" alt="" align="left" width="40" height="40"> Starlight
 
 > **Warning**
 > This tool is an early release and very much still work in progress!  

package/components/HeadSEO.astro

@@ -40,6 +40,8 @@ const description = data.description || config.description;
   href={import.meta.env.BASE_URL + 'favicon.svg'}
   type="image/svg+xml"
 />
+{/* Link to sitemap, but only when `site` is set. */}
+{Astro.site && <link rel="sitemap" href="/sitemap-index.xml" />}
 
 <!-- OpenGraph Tags -->
 <meta property="og:title" content={title} />

package/components/Header.astro

@@ -30,7 +30,7 @@ interface Props {
   }
 
   .site-title {
-    font-size: var(--sl-text-2xl);
+    font-size: var(--sl-text-h4);
     font-weight: 600;
     color: var(--sl-color-text-accent);
     text-decoration: none;

package/components/RightSidebar.astro

@@ -0,0 +1,29 @@
+---
+import type { MarkdownHeading } from 'astro';
+import type { CollectionEntry } from 'astro:content';
+import config from 'virtual:starlight/user-config';
+import EditLink from './EditLink.astro';
+import RightSidebarPanel from './RightSidebarPanel.astro';
+import TableOfContents from './TableOfContents.astro';
+
+interface Props {
+  entry: CollectionEntry<'docs'>;
+  headings: MarkdownHeading[];
+}
+
+const { entry, headings } = Astro.props;
+---
+
+<RightSidebarPanel>
+  <TableOfContents headings={headings} />
+</RightSidebarPanel>
+<RightSidebarPanel>
+  {
+    config.editLink.baseUrl && (
+      <>
+        <h2>Contribute</h2>
+        <EditLink data={entry.data} id={entry.id} />
+      </>
+    )
+  }
+</RightSidebarPanel>

package/components/TableOfContents/MobileTableOfContents.astro

@@ -0,0 +1,125 @@
+---
+import type { MarkdownHeading } from 'astro';
+import config from 'virtual:starlight/user-config';
+import { generateToC } from './generateToC';
+import TableOfContentsList from './TableOfContentsList.astro';
+import Icon from '../Icon.astro';
+
+interface Props {
+  headings: MarkdownHeading[];
+}
+
+const toc = generateToC(Astro.props.headings, config.tableOfContents);
+---
+
+<nav aria-labelledby="starlight__on-this-page--mobile" class="lg:hidden">
+  <details id="starlight__mobile-toc">
+    <summary id="starlight__on-this-page--mobile" class="flex">
+      <div class="toggle flex">
+        On this page
+        <Icon name={'right-caret'} class="caret" size="1rem" />
+      </div>
+    </summary>
+    <div class="dropdown">
+      <TableOfContentsList toc={toc} isMobile />
+    </div>
+  </details>
+</nav>
+
+<style>
+  nav {
+    position: fixed;
+    top: calc(var(--sl-nav-height) - 1px);
+    inset-inline: 0;
+    border-top: 1px solid var(--sl-color-gray-5);
+    background-color: var(--sl-color-bg-nav);
+  }
+  @media (min-width: 50rem) {
+    nav {
+      inset-inline-start: var(--sl-sidebar-width);
+    }
+  }
+
+  summary {
+    height: var(--sl-mobile-toc-height);
+    border-bottom: 1px solid var(--sl-color-hairline-shade);
+    padding: 0.5rem 1rem;
+    outline-offset: var(--sl-outline-offset-inside);
+  }
+  summary::marker,
+  summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .toggle {
+    gap: 1rem;
+    align-items: center;
+    justify-content: space-between;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.5rem;
+    padding-block: 0.5rem;
+    padding-inline-start: 0.75rem;
+    padding-inline-end: 0.5rem;
+    font-size: var(--sl-text-xs);
+    line-height: 1;
+    background-color: var(--sl-color-black);
+    user-select: none;
+    cursor: pointer;
+  }
+  details[open] .toggle {
+    color: var(--sl-color-white);
+    border-color: var(--sl-color-accent);
+  }
+  details .toggle:hover {
+    color: var(--sl-color-white);
+    border-color: var(--sl-color-gray-2);
+  }
+
+  :global([dir='rtl']) .caret {
+    transform: rotateZ(180deg);
+  }
+  details[open] .caret {
+    transform: rotateZ(90deg);
+  }
+
+  .dropdown {
+    --border-top: 1px;
+    margin-top: calc(-1 * var(--border-top));
+    border: var(--border-top) solid var(--sl-color-gray-6);
+    border-top-color: var(--sl-color-hairline-shade);
+    max-height: calc(85vh - var(--sl-nav-height) - var(--sl-mobile-toc-height));
+    overflow-y: auto;
+    background-color: var(--sl-color-black);
+    box-shadow: var(--sl-shadow-md);
+  }
+</style>
+
+<script>
+  const details = document.querySelector<HTMLDetailsElement>(
+    '#starlight__mobile-toc'
+  );
+  if (details) {
+    const closeToC = () => {
+      details.open = false;
+    };
+    // Close the table of contents whenever a link is clicked.
+    details.querySelectorAll('a').forEach((a) => {
+      a.addEventListener('click', closeToC);
+    });
+    // Close the table of contents when a user clicks outside of it.
+    window.addEventListener('click', (e) => {
+      if (!details.contains(e.target as Node)) closeToC();
+    });
+    // Or when they press the escape key.
+    window.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape' && details.open) {
+        const hasFocus = details.contains(document.activeElement);
+        closeToC();
+        if (hasFocus) {
+          const summary = details.querySelector('summary');
+          if (summary) summary.focus();
+        }
+      }
+    });
+  }
+</script>

package/components/TableOfContents/TableOfContentsList.astro

@@ -3,33 +3,54 @@ import type { generateToC } from './generateToC';
 
 interface Props {
   toc: ReturnType<typeof generateToC>;
-  nested?: boolean;
+  depth?: number;
+  isMobile?: boolean;
 }
 
-const { toc, nested } = Astro.props;
+const { toc, isMobile = false, depth = 0 } = Astro.props;
 ---
 
-<ul class:list={{ nested }}>
+<ul class:list={{ isMobile }}>
   {
     toc.map((heading) => (
       <li>
         <a href={'#' + heading.slug}>{heading.text}</a>
         {heading.children.length > 0 && (
-          <Astro.self toc={heading.children} nested />
+          <Astro.self
+            toc={heading.children}
+            depth={depth + 1}
+            isMobile={isMobile}
+          />
         )}
       </li>
     ))
   }
 </ul>
 
-<style>
+<style define:vars={{ depth }}>
   ul {
     padding: 0;
   }
-  .nested {
-    padding-inline-start: 1rem;
-  }
   ul :global(::marker) {
     color: transparent;
   }
+  a {
+    --pad-inline: 0rem;
+    display: block;
+    padding-inline: calc(1rem * var(--depth) + var(--pad-inline))
+      var(--pad-inline);
+  }
+  .isMobile a {
+    --pad-inline: 1rem;
+    border-top: 1px solid var(--sl-color-gray-6);
+    padding-block: 0.5rem;
+    color: var(--sl-color-text);
+    font-size: var(--sl-text-sm);
+    line-height: 1.25;
+    text-decoration: none;
+    outline-offset: var(--sl-outline-offset-inside);
+  }
+  .isMobile:first-child > li:first-child > a {
+    border-top: 0;
+  }
 </style>

package/components.ts

@@ -0,0 +1,2 @@
+export { default as Tabs } from './user-components/Tabs.astro';
+export { default as TabItem } from './user-components/TabItem.astro';

package/index.astro

@@ -1,6 +1,5 @@
 ---
 import type { InferGetStaticPropsType } from 'astro';
-import config from 'virtual:starlight/user-config';
 
 import { getPrevNextLinks, getSidebar } from './utils/navigation';
 import { paths } from './utils/routing';
@@ -13,17 +12,16 @@ import './style/util.css';
 
 // Components — can override built-in CSS, but not user CSS.
 import ContentPanel from './components/ContentPanel.astro';
-import EditLink from './components/EditLink.astro';
 import FallbackContentNotice from './components/FallbackContentNotice.astro';
 import HeadSEO from './components/HeadSEO.astro';
 import Header from './components/Header.astro';
 import LastUpdated from './components/LastUpdated.astro';
 import MarkdownContent from './components/MarkdownContent.astro';
 import PrevNextLinks from './components/PrevNextLinks.astro';
-import RightSidebarPanel from './components/RightSidebarPanel.astro';
+import RightSidebar from './components/RightSidebar.astro';
 import Sidebar from './components/Sidebar.astro';
 import SkipLink from './components/SkipLink.astro';
-import TableOfContents from './components/TableOfContents.astro';
+import MobileTableOfContents from './components/TableOfContents/MobileTableOfContents.astro';
 import ThemeProvider from './components/ThemeProvider.astro';
 import PageFrame from './layout/PageFrame.astro';
 import TwoColumnContent from './layout/TwoColumnContent.astro';
@@ -58,22 +56,9 @@ const prevNextLinks = getPrevNextLinks(sidebar);
     <PageFrame>
       <Header slot="header" locale={locale} />
       <Sidebar slot="sidebar" sidebar={sidebar} locale={locale} />
+      <MobileTableOfContents headings={headings} />
       <TwoColumnContent>
-        <Fragment slot="right-sidebar">
-          <RightSidebarPanel>
-            <TableOfContents headings={headings} />
-          </RightSidebarPanel>
-          <RightSidebarPanel>
-            {
-              config.editLink.baseUrl && (
-                <>
-                  <h2>Contribute</h2>
-                  <EditLink data={entry.data} id={entry.id} />
-                </>
-              )
-            }
-          </RightSidebarPanel>
-        </Fragment>
+        <RightSidebar slot="right-sidebar" entry={entry} headings={headings} />
         <main
           id="starlight__overview"
           data-pagefind-body

package/index.ts

@@ -9,6 +9,7 @@ import { spawn } from 'node:child_process';
 import { dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { starlightAsides } from './integrations/asides';
+import { starlightSitemap } from './integrations/sitemap';
 import {
   StarlightUserConfig,
   StarlightConfig,
@@ -63,7 +64,7 @@ export default function StarlightIntegration(
     },
   };
 
-  return [Starlight, mdx()];
+  return [starlightSitemap(userConfig), Starlight, mdx()];
 }
 
 function resolveVirtualModuleId(id: string) {

package/integrations/sitemap.ts

@@ -0,0 +1,22 @@
+import sitemap, { SitemapOptions } from '@astrojs/sitemap';
+import type { StarlightConfig } from '../types';
+
+/**
+ * A wrapped version of the `@astrojs/sitemap` integration configured based
+ * on Starlight i18n config.
+ */
+export function starlightSitemap(opts: StarlightConfig) {
+  const sitemapConfig: SitemapOptions = {};
+  if (opts.isMultilingual) {
+    sitemapConfig.i18n = {
+      defaultLocale: opts.defaultLocale.locale! || 'root',
+      locales: Object.fromEntries(
+        Object.entries(opts.locales).map(([locale, config]) => [
+          locale,
+          config?.lang!,
+        ])
+      ),
+    };
+  }
+  return sitemap(sitemapConfig);
+}

package/layout/PageFrame.astro

@@ -50,6 +50,7 @@ const hasSidebar = Astro.slots.has('sidebar');
   .sidebar-pane {
     visibility: var(--sl-sidebar-visibility, hidden);
     position: fixed;
+    z-index: var(--sl-z-index-menu);
     inset-block: 0;
     inset-inline-start: 0;
     padding-top: var(--sl-nav-height);
@@ -67,7 +68,7 @@ const hasSidebar = Astro.slots.has('sidebar');
   }
 
   .main-frame {
-    padding-top: var(--sl-nav-height);
+    padding-top: calc(var(--sl-nav-height) + var(--sl-mobile-toc-height));
   }
 
   @media (min-width: 50rem) {

package/layout/TwoColumnContent.astro

@@ -1,5 +1,5 @@
 <div class="container">
-  <aside class="right-sidebar-container">
+  <aside class="right-sidebar-container hidden lg:block">
     <div class="right-sidebar"><slot name="right-sidebar" /></div>
   </aside>
   <div class="main-pane"><slot /></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -10,9 +10,17 @@
   ],
   "author": "Chris Swithinbank <swithinbank@gmail.com>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/withastro/starlight",
+    "directory": "packages/starlight"
+  },
+  "bugs": "https://github.com/withastro/starlight/issues",
+  "homepage": "https://starlight.astro.build",
   "type": "module",
   "exports": {
     ".": "./index.ts",
+    "./components": "./components.ts",
     "./schema": "./schema.ts",
     "./types": "./types.ts",
     "./index.astro": "./index.astro",
@@ -27,16 +35,19 @@
   },
   "dependencies": {
     "@astrojs/mdx": "^0.19.1",
+    "@astrojs/sitemap": "^1.3.1",
     "@pagefind/default-ui": "^0.12.0",
     "@types/mdast": "^3.0.11",
     "bcp-47": "^2.1.0",
     "execa": "^7.1.1",
     "hastscript": "^7.2.0",
     "pagefind": "^0.12.0",
+    "rehype": "^12.0.1",
     "remark-directive": "^2.0.1",
     "unified": "^10.1.2",
     "unist-util-remove": "^3.1.1",
-    "unist-util-visit": "^4.1.2"
+    "unist-util-visit": "^4.1.2",
+    "vfile": "^5.3.7"
   },
   "scripts": {}
 }

package/style/props.css

@@ -113,17 +113,21 @@
   --__sb-font-mono: var(--sl-font-mono, ''), var(--sl-font-system-mono);
 
   /** Key layout values */
-  --sl-nav-height: 4rem;
+  --sl-nav-height: 3.5rem;
   --sl-nav-pad-x: 1.5rem;
   --sl-nav-pad-y: 0.75rem;
+  --sl-mobile-toc-height: 3rem;
   --sl-sidebar-width: 18.75rem;
   --sl-sidebar-pad-x: 1rem;
   --sl-content-width: 45rem;
   --sl-content-pad-x: 1rem;
   --sl-menu-button-size: 2rem;
   --sl-nav-gap: var(--sl-content-pad-x);
+  /* Offset required to show outline inside an element instead of round the outside */
+  --sl-outline-offset-inside: -0.1875rem;
 
   /* Global z-index values */
+  --sl-z-index-menu: 5;
   --sl-z-index-navbar: 10;
   --sl-z-index-skiplink: 20;
 }
@@ -183,6 +187,7 @@
 
 @media (min-width: 50em) {
   :root {
+    --sl-nav-height: 4rem;
     --sl-text-h1: var(--sl-text-5xl);
     --sl-text-h2: var(--sl-text-4xl);
     --sl-text-h3: var(--sl-text-3xl);
@@ -193,5 +198,6 @@
 @media (min-width: 72rem) {
   :root {
     --sl-content-pad-x: 1.5rem;
+    --sl-mobile-toc-height: 0rem;
   }
 }

package/style/util.css

@@ -30,3 +30,14 @@
     display: block;
   }
 }
+@media (min-width: 72rem) {
+  .lg\:hidden {
+    display: none;
+  }
+  .lg\:flex {
+    display: flex;
+  }
+  .lg\:block {
+    display: block;
+  }
+}

package/user-components/TabItem.astro

@@ -0,0 +1,17 @@
+---
+import { TabItemTagname } from './rehype-tabs';
+
+interface Props {
+  label: string;
+}
+
+const { label } = Astro.props;
+
+if (!label) {
+  throw new Error('Missing prop `label` on `<TabItem>` component.');
+}
+---
+
+<TabItemTagname data-label={label}>
+  <slot />
+</TabItemTagname>

package/user-components/Tabs.astro

@@ -0,0 +1,148 @@
+---
+import { processPanels } from './rehype-tabs';
+
+const panelHtml = await Astro.slots.render('default');
+const { html, panels } = processPanels(panelHtml);
+---
+
+<starlight-tabs>
+  {
+    panels && (
+      <div class="tablist-wrapper">
+        <ul role="tablist">
+          {panels.map(({ label, panelId, tabId }, idx) => (
+            <li role="presentation" class="tab">
+              <a
+                role="tab"
+                href={'#' + panelId}
+                id={tabId}
+                aria-selected={idx === 0 && 'true'}
+                tabindex={idx !== 0 ? -1 : 0}
+              >
+                {label}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </div>
+    )
+  }
+  <Fragment set:html={html} />
+</starlight-tabs>
+
+<style>
+  starlight-tabs {
+    display: block;
+  }
+
+  .tablist-wrapper {
+    overflow-x: auto;
+  }
+
+  [role='tablist'] {
+    display: flex;
+    list-style: none;
+    border-bottom: 2px solid var(--sl-color-gray-5);
+    padding: 0;
+  }
+
+  [role='tablist'] .tab + .tab {
+    margin-top: 0;
+  }
+  .tab {
+    margin-bottom: -2px;
+  }
+  .tab > [role='tab'] {
+    display: block;
+    padding: 0 1.25rem;
+    text-decoration: none;
+    border-bottom: 2px solid var(--sl-color-gray-5);
+    color: var(--sl-color-gray-3);
+  }
+  .tab [role='tab'][aria-selected] {
+    color: var(--sl-color-white);
+    border-color: var(--sl-color-text-accent);
+    font-weight: 600;
+  }
+
+  .tablist-wrapper ~ :global([role='tabpanel']) {
+    margin-top: 1rem;
+  }
+</style>
+
+<script>
+  class StarlightTabs extends HTMLElement {
+    tabs: HTMLAnchorElement[];
+    panels: HTMLElement[];
+
+    constructor() {
+      super();
+      const tablist = this.querySelector<HTMLUListElement>('[role="tablist"]')!;
+      this.tabs = [
+        ...tablist.querySelectorAll<HTMLAnchorElement>('[role="tab"]'),
+      ];
+      this.panels = [
+        ...this.querySelectorAll<HTMLElement>('[role="tabpanel"]'),
+      ];
+
+      this.tabs.forEach((tab, i) => {
+        // Handle clicks for mouse users
+        tab.addEventListener('click', (e) => {
+          e.preventDefault();
+          const currentTab = tablist.querySelector('[aria-selected]');
+          if (e.currentTarget !== currentTab) {
+            this.switchTab(e.currentTarget as HTMLAnchorElement, i);
+          }
+        });
+
+        // Handle keyboard input
+        tab.addEventListener('keydown', (e) => {
+          const index = this.tabs.indexOf(e.currentTarget as any);
+          // Work out which key the user is pressing and
+          // Calculate the new tab's index where appropriate
+          const dir =
+            e.key === 'ArrowLeft'
+              ? index - 1
+              : e.key === 'ArrowRight'
+              ? index + 1
+              : e.key === 'ArrowDown'
+              ? 'down'
+              : null;
+          if (dir === null) return;
+          // If the down key is pressed, move focus to the open panel,
+          // otherwise switch to the adjacent tab
+          if (dir === 'down') {
+            e.preventDefault();
+            this.panels[i]?.focus();
+          } else if (this.tabs[dir]) {
+            e.preventDefault();
+            this.switchTab(this.tabs[dir], dir);
+          }
+        });
+      });
+    }
+
+    switchTab(newTab: HTMLAnchorElement | null | undefined, index: number) {
+      if (!newTab) return;
+
+      // Mark all tabs as unselected and hide all tab panels.
+      this.tabs.forEach((tab) => {
+        tab.removeAttribute('aria-selected');
+        tab.setAttribute('tabindex', '-1');
+      });
+      this.panels.forEach((oldPanel) => {
+        oldPanel.hidden = true;
+      });
+
+      // Show new panel and mark new tab as selected.
+      const newPanel = this.panels[index];
+      if (newPanel) newPanel.hidden = false;
+      // Restore active tab to the default tab order.
+      newTab.removeAttribute('tabindex');
+      newTab.setAttribute('aria-selected', 'true');
+      newTab.focus();
+    }
+  }
+
+  customElements.define('starlight-tabs', StarlightTabs);
+</script>

package/user-components/rehype-tabs.ts

@@ -0,0 +1,82 @@
+import { rehype } from 'rehype';
+import { CONTINUE, SKIP, visit } from 'unist-util-visit';
+
+interface Panel {
+  panelId: string;
+  tabId: string;
+  label: string;
+}
+
+declare module 'vfile' {
+  interface DataMap {
+    panels: Panel[];
+  }
+}
+
+export const TabItemTagname = 'starlight-tab-item';
+
+let count = 0;
+const getIDs = () => {
+  const id = count++;
+  return { panelId: 'tab-panel-' + id, tabId: 'tab-' + id };
+};
+
+/**
+ * Rehype processor to extract tab panel data and turn each
+ * `<starlight-tab-item>` into a `<section>` with the necessary
+ * attributes.
+ */
+const tabsProcessor = rehype()
+  .data('settings', { fragment: true })
+  .use(function tabs() {
+    return (tree, file) => {
+      file.data.panels = [];
+      let isFirst = true;
+      visit(tree, 'element', (node) => {
+        if (node.tagName !== TabItemTagname || !node.properties) {
+          return CONTINUE;
+        }
+
+        const { dataLabel } = node.properties;
+        const ids = getIDs();
+        file.data.panels?.push({
+          ...ids,
+          label: String(dataLabel),
+        });
+
+        // Remove `<TabItem>` props
+        delete node.properties.dataLabel;
+        // Turn into `<section>` with required attributes
+        node.tagName = 'section';
+        node.properties.id = ids.panelId;
+        node.properties['aria-labelledby'] = ids.tabId;
+        node.properties.role = 'tabpanel';
+        node.properties.tabindex = -1;
+        // Hide all panels except the first
+        // TODO: make initially visible tab configurable
+        if (isFirst) {
+          isFirst = false;
+        } else {
+          node.properties.hidden = true;
+        }
+
+        // Skip over the tab panel’s children.
+        return SKIP;
+      });
+    };
+  });
+
+/**
+ * Process tab panel items to extract data for the tab links and format
+ * each tab panel correctly.
+ * @param html Inner HTML passed to the `<Tabs>` component.
+ */
+export const processPanels = (html: string) => {
+  const file = tabsProcessor.processSync({ value: html });
+  return {
+    /** Data for each tab panel. */
+    panels: file.data.panels,
+    /** Processed HTML for the tab panels. */
+    html: file.toString(),
+  };
+};