starlight-theme-apple 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.8.0
+
+A redesign that brings the theme much closer to Apple’s developer documentation and moves common site structure into the theme.
+
+### Added
+
+- Full-width site footer outside the article columns, with optional `footer.groups` navigation columns. Without groups it renders a compact bottom row. A thin `PageFrame` wrapper preserves Starlight’s native frame and places the site footer after it. Article metadata and pagination stay in `Footer`.
+
+- Theme-provided `Header`, `Sidebar`, `SocialIcons`, and `Footer` components. Header links, an optional emphasized action, and footer links are configured through new plugin options: `nav`, `action`, `socialAttrs`, and `footer`.
+- Header links are repeated at the top of the small-screen navigation menu.
+- Reference components exported from `starlight-theme-apple/components`: `ReferenceEntry`, `Declaration`, `ReferenceMeta`, `ParameterList`, `Parameter`, `ValueList`, `Availability`, `TopicList`, `TopicLink`, and `Figure`, plus the equivalent `apple-*` HTML classes for generated Markdown.
+- Breadcrumbs link sidebar groups to their overview page when the group has one.
+- Xcode-inspired code colors, applied through Expressive Code’s `styleOverrides` instead of `!important` CSS.
+
+### Changed
+
+
+- Typography, palette, spacing, sidebar, table of contents, asides, cards, buttons, tabs, steps, badges, search, and the splash hero follow Apple’s documentation more closely. Dark mode uses Apple’s black background.
+- The appearance control is Starlight’s native `ThemeSelect`, shown as an icon button. It keeps Light, Dark, and Auto.
+- Component overrides set by you or by earlier plugins now take precedence over the theme’s components. Previously `PageTitle` and `Pagination` were always replaced.
+- The theme stylesheet is loaded before your `customCss`.
+- Layout uses Starlight’s own `--sl-content-width` and `--sl-sidebar-width` instead of fighting Starlight’s layout. The content column is 51.25rem.
+- Shell code blocks render as plain listings rather than empty terminal windows. Add `frame="terminal"` to restore the terminal frame.
+- Peer dependencies are now `@astrojs/starlight >=0.41.0` and `astro >=7.0.0`.
+
+### Removed and renamed tokens
+
+- `--apple-content-width`: use `--sl-content-width`.
+- `--apple-header-height`: use `--sl-nav-height`.
+- `--apple-sidebar-width`, `--apple-toc-width`: use `--sl-sidebar-width`; the table of contents follows Starlight’s layout.
+- `--apple-hover-surface`, `--apple-active-surface`, `--apple-surface`, `--apple-card-background`, `--apple-navigator-background`: use `--apple-fill-secondary`, `--apple-fill`, and `--apple-secondary-background`.
+- `--apple-aside-background`, `--apple-header-background`: replaced by `--apple-secondary-background` and `--apple-background`.
+- `--apple-control-primary-text`: renamed `--apple-button-foreground`.
+- `--apple-warning`: renamed `--apple-caution`; `--apple-tip` and `--apple-note` were added.
+- `--apple-border`, `--apple-link-hover`, `--apple-row-height`, `--apple-section-spacing`, `--apple-disabled-opacity`: removed.

package/README.md

@@ -1,15 +1,57 @@
 # `starlight-theme-apple`
 
-An Astro Starlight theme inspired by Apple Developer Documentation.
+An [Astro Starlight](https://starlight.astro.build) theme modeled on Apple’s developer documentation: system typography on Apple’s documentation scale, a quiet navigator, breadcrumbs, a hairline “On this page” rail, Xcode-colored code, and components for dense API and configuration references. Light and dark appearances are both included.
+
+## Install
+
+```sh
+npm install starlight-theme-apple
+```
+
+```js
+// astro.config.mjs
+import starlight from "@astrojs/starlight";
+import starlightThemeApple from "starlight-theme-apple";
+
+export default {
+  integrations: [starlight({ title: "My Docs", plugins: [starlightThemeApple()] })],
+};
+```
+
+That is the whole setup. No custom CSS is required.
+
+## Optional configuration
+
+```js
+starlightThemeApple({
+  nav: [{ label: "Guides", link: "/guides/" }], // header links, also shown in the mobile menu
+  action: { label: "Download", link: "https://example.com/download" }, // emphasized header button
+  socialAttrs: { github: { "data-analytics": "github" } }, // attributes for Starlight social links
+  footer: {
+    links: [{ label: "GitHub", link: "https://github.com/example/project" }],
+    copyright: "© 2026 Example",
+  },
+});
+```
+
+Paths starting with `/` are resolved against Astro’s `base`.
+
+## Reference components
+
+```mdx
+import { ReferenceEntry, Declaration, ReferenceMeta } from "starlight-theme-apple/components";
+```
+
+`ReferenceEntry`, `Declaration`, `ReferenceMeta`, `ParameterList`, `Parameter`, `ValueList`, `Availability`, `TopicList`, `TopicLink`, and `Figure`. Generators that write Markdown can emit the equivalent `apple-*` HTML classes instead.
 
 ## Documentation
 
-Want to get started immediately?
+See the [documentation site](https://acsandmann.github.io/starlight-theme-apple/) for configuration, customization tokens, component overrides, and examples.
 
-Check out the `starlight-theme-apple` getting started guide.
+Requires Starlight 0.41 or later and Astro 7. Not affiliated with Apple Inc.
 
 ## License
 
-Licensed under the MIT license, Copyright © acsandmann.
+MIT © acsandmann. See [LICENSE](https://github.com/acsandmann/starlight-theme-apple/blob/main/LICENSE).
 
-See [LICENSE](https://github.com/acsandmann/starlight-theme-apple/blob/main/LICENSE) for more information.
+The site footer spans the page below article navigation. Use `footer.groups` for columns (`{ label, links }`); without groups it renders only the bottom row. `footer.links` and `footer.copyright` populate the bottom row. The theme’s `PageFrame` wrapper supplies this outer footer, while the `Footer` override supplies article metadata and pagination.

package/components/Footer.astro

@@ -0,0 +1,19 @@
+---
+import EditLink from "virtual:starlight/components/EditLink";
+import LastUpdated from "virtual:starlight/components/LastUpdated";
+import Pagination from "virtual:starlight/components/Pagination";
+
+const { editUrl, lastUpdated } = Astro.locals.starlightRoute;
+---
+
+<div class="apple-footer">
+  {
+    (editUrl || lastUpdated) && (
+      <div class="apple-footer__meta">
+        <EditLink />
+        <LastUpdated />
+      </div>
+    )
+  }
+  <Pagination />
+</div>

package/components/Header.astro

@@ -0,0 +1,55 @@
+---
+import config from "virtual:starlight/user-config";
+import LanguageSelect from "virtual:starlight/components/LanguageSelect";
+import Search from "virtual:starlight/components/Search";
+import SiteTitle from "virtual:starlight/components/SiteTitle";
+import SocialIcons from "virtual:starlight/components/SocialIcons";
+import ThemeSelect from "virtual:starlight/components/ThemeSelect";
+import themeConfig from "virtual:starlight-theme-apple/config";
+import NavLink from "./NavLink.astro";
+
+const shouldRenderSearch =
+  config.pagefind ||
+  config.components.Search !== "@astrojs/starlight/components/Search.astro";
+const { nav, action } = themeConfig;
+const hasSocial = (config.social ?? []).length > 0;
+---
+
+<div class="apple-header">
+  <div class="apple-header__title">
+    <SiteTitle />
+  </div>
+
+  {
+    nav.length > 0 && (
+      <nav
+        class="apple-header__nav print:hidden"
+        aria-label={Astro.locals.t("starlightThemeApple.primaryNav")}
+      >
+        <ul>
+          {nav.map((item) => (
+            <li>
+              <NavLink item={item} />
+            </li>
+          ))}
+        </ul>
+      </nav>
+    )
+  }
+
+  <div class="apple-header__end print:hidden">
+    {shouldRenderSearch && <Search />}
+    <div class="apple-header__controls">
+      {
+        hasSocial && (
+          <div class="social-icons">
+            <SocialIcons />
+          </div>
+        )
+      }
+      <ThemeSelect />
+      <LanguageSelect />
+    </div>
+    {action && <NavLink item={action} class="apple-header__action" />}
+  </div>
+</div>

package/components/NavLink.astro

@@ -0,0 +1,24 @@
+---
+import { Icon } from "@astrojs/starlight/components";
+import type { StarlightThemeAppleLink } from "../libs/config";
+import { linkProps } from "../libs/links";
+
+interface Props {
+  item: StarlightThemeAppleLink;
+  class?: string;
+}
+
+const { item, class: className } = Astro.props;
+const { href, current, external, attrs } = linkProps(item, Astro.url.pathname);
+---
+
+<a
+  href={href}
+  class:list={["apple-nav-link", className]}
+  aria-current={current ? "true" : undefined}
+  rel={external ? "noopener" : undefined}
+  {...attrs}
+>
+  {item.icon && <Icon name={item.icon} />}
+  <span>{item.label}</span>
+</a>

package/components/PageFrame.astro

@@ -0,0 +1,11 @@
+---
+import Default from "@astrojs/starlight/components/PageFrame.astro";
+import SiteFooter from "./SiteFooter.astro";
+---
+
+<Default>
+  <slot name="header" slot="header" />
+  <slot name="sidebar" slot="sidebar" />
+  <slot />
+</Default>
+<SiteFooter />

package/components/PageTitle.astro

@@ -1,45 +1,29 @@
 ---
+import { breadcrumbs } from "../libs/breadcrumbs";
+
 const { entry, sidebar, siteTitle, siteTitleHref } =
   Astro.locals.starlightRoute;
-const title = entry.data.title;
-
-type Crumb = { href?: string; label: string };
-type SidebarItem =
-  | { type: "link"; isCurrent: boolean }
-  | { type: "group"; label: string; entries: SidebarItem[] };
-
-function findCurrentPath(
-  entries: SidebarItem[],
-  ancestors: Crumb[] = []
-): Crumb[] | undefined {
-  for (const item of entries) {
-    if (item.type === "link" && item.isCurrent) return ancestors;
-    if (item.type === "group") {
-      const path = findCurrentPath(item.entries, [
-        ...ancestors,
-        { label: item.label },
-      ]);
-      if (path) return path;
-    }
-  }
-}
-
-const parents = findCurrentPath(sidebar as SidebarItem[]) ?? [];
+const crumbs = breadcrumbs(sidebar, siteTitle, siteTitleHref);
 ---
 
-<nav class="apple-breadcrumbs" aria-label="Breadcrumb">
-  <a href={siteTitleHref}>{siteTitle}</a>
-  {
-    parents.map((parent) => (
-      <>
-        <span aria-hidden="true">›</span>
-        {parent.href ? (
-          <a href={parent.href}>{parent.label}</a>
-        ) : (
-          <span>{parent.label}</span>
-        )}
-      </>
-    ))
-  }
-</nav>
-<h1 id="_top">{title}</h1>
+{
+  crumbs.length > 0 && (
+    <nav
+      class="apple-breadcrumbs"
+      aria-label={Astro.locals.t("starlightThemeApple.breadcrumbs")}
+    >
+      <ol>
+        {crumbs.map((crumb) => (
+          <li>
+            {crumb.href ? (
+              <a href={crumb.href}>{crumb.label}</a>
+            ) : (
+              <span>{crumb.label}</span>
+            )}
+          </li>
+        ))}
+      </ol>
+    </nav>
+  )
+}
+<h1 id="_top" class="apple-page-title">{entry.data.title}</h1>

package/components/Pagination.astro

@@ -1,34 +1,27 @@
 ---
 const { dir, pagination } = Astro.locals.starlightRoute;
 const { prev, next } = pagination;
-const isRtl = dir === "rtl";
 ---
 
-<div class="pagination-links print:hidden" dir={dir}>
-  {
-    prev && (
-      <a href={prev.href} rel="prev">
-        <span class="pagination-arrow" aria-hidden="true">
-          {isRtl ? "→" : "←"}
-        </span>
-        <span>
-          <small>{Astro.locals.t("page.previousLink")}</small>
-          <span class="link-title">{prev.label}</span>
-        </span>
-      </a>
-    )
-  }
-  {
-    next && (
-      <a href={next.href} rel="next">
-        <span>
-          <small>{Astro.locals.t("page.nextLink")}</small>
-          <span class="link-title">{next.label}</span>
-        </span>
-        <span class="pagination-arrow" aria-hidden="true">
-          {isRtl ? "←" : "→"}
-        </span>
-      </a>
-    )
-  }
-</div>
+{
+  (prev || next) && (
+    <div class="apple-pagination print:hidden" dir={dir}>
+      {prev && (
+        <a href={prev.href} rel="prev">
+          <span class="apple-pagination__label">
+            {Astro.locals.t("page.previousLink")}
+          </span>
+          <span class="apple-pagination__title">{prev.label}</span>
+        </a>
+      )}
+      {next && (
+        <a href={next.href} rel="next">
+          <span class="apple-pagination__label">
+            {Astro.locals.t("page.nextLink")}
+          </span>
+          <span class="apple-pagination__title">{next.label}</span>
+        </a>
+      )}
+    </div>
+  )
+}

package/components/Sidebar.astro

@@ -0,0 +1,27 @@
+---
+import Default from "@astrojs/starlight/components/Sidebar.astro";
+import themeConfig from "virtual:starlight-theme-apple/config";
+import NavLink from "./NavLink.astro";
+
+const { nav, action } = themeConfig;
+const items = action ? [...nav, action] : nav;
+---
+
+{
+  /* Header links are repeated at the top of the small-screen navigation menu. */
+  items.length > 0 && (
+    <nav
+      class="apple-menu-nav md:sl-hidden"
+      aria-label={Astro.locals.t("starlightThemeApple.primaryNav")}
+    >
+      <ul>
+        {items.map((item) => (
+          <li>
+            <NavLink item={item} />
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}
+<Default />

package/components/SiteFooter.astro

@@ -0,0 +1,61 @@
+---
+import { Icon } from "@astrojs/starlight/components";
+import config from "virtual:starlight/user-config";
+import themeConfig from "virtual:starlight-theme-apple/config";
+import NavLink from "./NavLink.astro";
+
+const { siteTitle, siteTitleHref } = Astro.locals.starlightRoute;
+const { groups: configuredGroups, links, copyright } = themeConfig.footer;
+const groups = configuredGroups;
+---
+
+<footer class="apple-site-footer" data-directory={groups.length > 0 ? "" : undefined} data-pagefind-ignore>
+  <div class="apple-site-footer__inner">
+    {
+      groups.length > 0 && (
+        <nav
+          class="apple-site-footer__directory"
+          aria-label={Astro.locals.t("starlightThemeApple.footerNav")}
+        >
+          {groups.map((group) => (
+            <div class="apple-site-footer__group">
+              <h2>{group.label}</h2>
+              <ul>
+                {group.links.map((item) => (
+                  <li>
+                    <NavLink item={item} />
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))}
+        </nav>
+      )
+    }
+    <div class="apple-site-footer__bottom">
+      <p>{copyright ?? <a href={siteTitleHref}>{siteTitle}</a>}</p>
+      {
+        links.length > 0 && (
+          <ul>
+            {links.map((item) => (
+              <li>
+                <NavLink item={item} />
+              </li>
+            ))}
+          </ul>
+        )
+      }
+      {
+        config.credits && (
+          <a
+            class="apple-site-footer__credits"
+            href="https://starlight.astro.build"
+          >
+            <Icon name="starlight" />
+            {Astro.locals.t("builtWithStarlight.label")}
+          </a>
+        )
+      }
+    </div>
+  </div>
+</footer>

package/components/SocialIcons.astro

@@ -0,0 +1,22 @@
+---
+import { Icon } from "@astrojs/starlight/components";
+import config from "virtual:starlight/user-config";
+import themeConfig from "virtual:starlight-theme-apple/config";
+
+const links = config.social ?? [];
+---
+
+{
+  links.map(({ label, href, icon }) => (
+    <a
+      href={href}
+      rel="me"
+      class="sl-flex apple-social-link"
+      title={label}
+      {...themeConfig.socialAttrs[icon]}
+    >
+      <span class="sr-only">{label}</span>
+      <Icon name={icon} />
+    </a>
+  ))
+}

package/components.ts

@@ -0,0 +1,10 @@
+export { default as Availability } from "./user-components/Availability.astro";
+export { default as Declaration } from "./user-components/Declaration.astro";
+export { default as Figure } from "./user-components/Figure.astro";
+export { default as Parameter } from "./user-components/Parameter.astro";
+export { default as ParameterList } from "./user-components/ParameterList.astro";
+export { default as ReferenceEntry } from "./user-components/ReferenceEntry.astro";
+export { default as ReferenceMeta } from "./user-components/ReferenceMeta.astro";
+export { default as TopicLink } from "./user-components/TopicLink.astro";
+export { default as TopicList } from "./user-components/TopicList.astro";
+export { default as ValueList } from "./user-components/ValueList.astro";