starlight-heading-badges 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present, HiDeoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+<div align="center">
+  <h1>starlight-heading-badges 🔖</h1>
+  <p>Starlight plugin to add badges to your Markdown and MDX headings.</p>
+  <p>
+    <a href="https://i.imgur.com/jVkJd9U.png" title="Screenshot of the Starlight Heading Badges plugin">
+      <img alt="Screenshot of the Starlight Heading Badges plugin" src="https://i.imgur.com/jVkJd9U.png" width="520" />
+    </a>
+  </p>
+</div>
+
+<div align="center">
+  <a href="https://github.com/HiDeoo/starlight-heading-badges/actions/workflows/integration.yml">
+    <img alt="Integration Status" src="https://github.com/HiDeoo/starlight-heading-badges/actions/workflows/integration.yml/badge.svg" />
+  </a>
+  <a href="https://github.com/HiDeoo/starlight-heading-badges/blob/main/LICENSE">
+    <img alt="License" src="https://badgen.net/github/license/HiDeoo/starlight-heading-badges" />
+  </a>
+  <br />
+</div>
+
+## Getting Started
+
+Want to get started immediately? Check out the [getting started guide](https://starlight-heading-badges.vercel.app/getting-started/) or check out the [demo](https://starlight-heading-badges.vercel.app/demo/) to see the theme in action.
+
+## License
+
+Licensed under the MIT License, Copyright © HiDeoo.
+
+See [LICENSE](https://github.com/HiDeoo/starlight-heading-badges/blob/main/LICENSE) for more information.

package/components/HeadingBadgesMobileTableOfContents.astro

@@ -0,0 +1,178 @@
+---
+/**
+ * A copy of the Starlight `<MobileTableOfContents>` component with support for badges.
+ * @see https://github.com/withastro/starlight/blob/1d32c8b0cec0ea5f66351b21b91748dfa78b404b/packages/starlight/components/MobileTableOfContents.astro
+ */
+
+import { Icon } from '@astrojs/starlight/components'
+import type { Props } from '@astrojs/starlight/props'
+
+import TableOfContentsList from './TableOfContentsList.astro'
+
+const { labels, toc } = Astro.props
+---
+
+{
+  toc && (
+    <mobile-starlight-toc data-min-h={toc.minHeadingLevel} data-max-h={toc.maxHeadingLevel}>
+      <nav aria-labelledby="starlight__on-this-page--mobile">
+        <details id="starlight__mobile-toc">
+          <summary id="starlight__on-this-page--mobile" class="sl-flex">
+            <div class="toggle sl-flex">
+              {labels['tableOfContents.onThisPage']}
+              <Icon name={'right-caret'} class="caret" size="1rem" />
+            </div>
+            <span class="display-current" />
+          </summary>
+          <div class="dropdown">
+            <TableOfContentsList toc={toc.items} isMobile />
+          </div>
+        </details>
+      </nav>
+    </mobile-starlight-toc>
+  )
+}
+
+<style>
+  nav {
+    position: fixed;
+    z-index: var(--sl-z-index-toc);
+    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-content-inline-start, 0);
+    }
+  }
+
+  summary {
+    gap: 0.5rem;
+    align-items: center;
+    height: var(--sl-mobile-toc-height);
+    border-bottom: 1px solid var(--sl-color-hairline-shade);
+    padding: 0.5rem 1rem;
+    font-size: var(--sl-text-xs);
+    outline-offset: var(--sl-outline-offset-inside);
+  }
+  summary::marker,
+  summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .toggle {
+    flex-shrink: 0;
+    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;
+    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);
+  }
+
+  .display-current {
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    overflow: hidden;
+    color: var(--sl-color-white);
+  }
+
+  .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);
+    overscroll-behavior: contain;
+  }
+</style>
+
+<script>
+  import { deserializeBadge } from '../libs/badge'
+  import { StarlightTOC } from '../libs/starlight-toc'
+
+  class MobileStarlightTOC extends StarlightTOC {
+    override set current(link: HTMLAnchorElement) {
+      super.current = link
+      const display = this.querySelector('.display-current') as HTMLSpanElement
+      if (display) {
+        const heading = link.dataset['shbHeading']
+        if (heading) {
+          const badge = deserializeBadge(heading)
+          if (badge) {
+            display.textContent = ''
+            display.append(document.createTextNode(`${badge.heading} `))
+            const span = document.createElement('span')
+            span.textContent = badge.text
+            span.dataset['shbBadge'] = ''
+            span.dataset['shbBadgeVariant'] = badge.variant
+            display.append(span)
+
+            return
+          }
+        }
+        display.textContent = link.textContent
+      }
+    }
+
+    override get current(): HTMLAnchorElement | null {
+      return super.current
+    }
+
+    constructor() {
+      super()
+      const details = this.querySelector('details')
+      if (!details) return
+      const closeToC = () => {
+        details.open = false
+      }
+      // Close the table of contents whenever a link is clicked.
+      for (const link of details.querySelectorAll('a')) {
+        link.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()
+          }
+        }
+      })
+    }
+  }
+
+  customElements.define('mobile-starlight-toc', MobileStarlightTOC)
+</script>

package/components/HeadingBadgesTableOfContents.astro

@@ -0,0 +1,25 @@
+---
+/**
+ * A copy of the Starlight `<TableOfContents>` component with support for badges.
+ * @see https://github.com/withastro/starlight/blob/1d32c8b0cec0ea5f66351b21b91748dfa78b404b/packages/starlight/components/TableOfContents.astro
+ */
+
+import type { Props } from '@astrojs/starlight/props'
+
+import TableOfContentsList from './TableOfContentsList.astro'
+
+const { labels, toc } = Astro.props
+---
+
+{
+  toc && (
+    <starlight-toc data-min-h={toc.minHeadingLevel} data-max-h={toc.maxHeadingLevel}>
+      <nav aria-labelledby="starlight__on-this-page">
+        <h2 id="starlight__on-this-page">{labels['tableOfContents.onThisPage']}</h2>
+        <TableOfContentsList toc={toc.items} />
+      </nav>
+    </starlight-toc>
+  )
+}
+
+<script src="../libs/starlight-toc"></script>

package/components/TableOfContentHeading.astro

@@ -0,0 +1,31 @@
+---
+import { Badge } from '@astrojs/starlight/components'
+
+import { deserializeBadge } from '../libs/badge'
+
+interface Props {
+  text: string
+}
+
+const { text } = Astro.props
+
+const badge = deserializeBadge(text)
+---
+
+{
+  badge ? (
+    <span class="shb-heading">
+      {badge.heading.trim()}&nbsp;
+      <Badge size="small" text={badge.text} variant={badge.variant} />
+    </span>
+  ) : (
+    <span>{text}</span>
+  )
+}
+
+<style>
+  .shb-heading .sl-badge {
+    font-size: 0.75rem;
+    padding: 0.0625rem 0.25rem;
+  }
+</style>

package/components/TableOfContentsList.astro

@@ -0,0 +1,86 @@
+---
+/**
+ * A copy of the Starlight `<TableOfContentsList>` component with support for badges.
+ * @see https://github.com/withastro/starlight/blob/1d32c8b0cec0ea5f66351b21b91748dfa78b404b/packages/starlight/components/TableOfContents/TableOfContentsList.astro
+ */
+
+import type { MarkdownHeading } from 'astro'
+
+import TableOfContentHeading from './TableOfContentHeading.astro'
+
+interface TocItem extends MarkdownHeading {
+  children: TocItem[]
+}
+
+interface Props {
+  toc: TocItem[]
+  depth?: number
+  isMobile?: boolean
+}
+
+const { toc, isMobile = false, depth = 0 } = Astro.props
+---
+
+<ul class:list={{ isMobile }}>
+  {
+    toc.map((heading) => (
+      <li>
+        <a href={`#${heading.slug}`} data-shb-heading={heading.text}>
+          <TableOfContentHeading text={heading.text} />
+        </a>
+        {heading.children.length > 0 && <Astro.self toc={heading.children} depth={depth + 1} isMobile={isMobile} />}
+      </li>
+    ))
+  }
+</ul>
+
+<style define:vars={{ depth }}>
+  ul {
+    padding: 0;
+    list-style: none;
+  }
+  a {
+    --pad-inline: 0.5rem;
+    display: block;
+    border-radius: 0.25rem;
+    padding-block: 0.25rem;
+    padding-inline: calc(1rem * var(--depth) + var(--pad-inline)) var(--pad-inline);
+    line-height: 1.25;
+  }
+  a[aria-current='true'] {
+    color: var(--sl-color-text-accent);
+  }
+  .isMobile a {
+    --pad-inline: 1rem;
+    display: flex;
+    justify-content: space-between;
+    gap: var(--pad-inline);
+    border-top: 1px solid var(--sl-color-gray-6);
+    border-radius: 0;
+    padding-block: 0.5rem;
+    color: var(--sl-color-text);
+    font-size: var(--sl-text-sm);
+    text-decoration: none;
+    outline-offset: var(--sl-outline-offset-inside);
+  }
+  .isMobile:first-child > li:first-child > a {
+    border-top: 0;
+  }
+  .isMobile a[aria-current='true'],
+  .isMobile a[aria-current='true']:hover,
+  .isMobile a[aria-current='true']:focus {
+    color: var(--sl-color-white);
+    background-color: unset;
+  }
+  .isMobile a[aria-current='true']::after {
+    content: '';
+    width: 1rem;
+    background-color: var(--sl-color-text-accent);
+    /* Check mark SVG icon */
+    -webkit-mask-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHZpZXdCb3g9JzAgMCAxNCAxNCc+PHBhdGggZD0nTTEwLjkxNCA0LjIwNmEuNTgzLjU4MyAwIDAgMC0uODI4IDBMNS43NCA4LjU1NyAzLjkxNCA2LjcyNmEuNTk2LjU5NiAwIDAgMC0uODI4Ljg1N2wyLjI0IDIuMjRhLjU4My41ODMgMCAwIDAgLjgyOCAwbDQuNzYtNC43NmEuNTgzLjU4MyAwIDAgMCAwLS44NTdaJy8+PC9zdmc+Cg==');
+    mask-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHZpZXdCb3g9JzAgMCAxNCAxNCc+PHBhdGggZD0nTTEwLjkxNCA0LjIwNmEuNTgzLjU4MyAwIDAgMC0uODI4IDBMNS43NCA4LjU1NyAzLjkxNCA2LjcyNmEuNTk2LjU5NiAwIDAgMC0uODI4Ljg1N2wyLjI0IDIuMjRhLjU4My41ODMgMCAwIDAgLjgyOCAwbDQuNzYtNC43NmEuNTgzLjU4MyAwIDAgMCAwLS44NTdaJy8+PC9zdmc+Cg==');
+    -webkit-mask-repeat: no-repeat;
+    mask-repeat: no-repeat;
+    flex-shrink: 0;
+  }
+</style>

package/index.ts

@@ -0,0 +1,27 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types'
+
+import { starlightHeadingBadgesIntegration } from './libs/integration'
+import { overrideComponents } from './libs/plugin'
+
+export default function starlightHeadingBadgesPlugin(): StarlightPlugin {
+  return {
+    name: 'starlight-heading-badges-plugin',
+    hooks: {
+      setup({ addIntegration, config: starlightConfig, logger, updateConfig }) {
+        addIntegration(starlightHeadingBadgesIntegration())
+
+        updateConfig({
+          components: overrideComponents(
+            starlightConfig,
+            [
+              { name: 'MobileTableOfContents', fallback: 'HeadingBadgesMobileTableOfContents' },
+              { name: 'TableOfContents', fallback: 'HeadingBadgesTableOfContents' },
+            ],
+            logger,
+          ),
+          customCss: [...(starlightConfig.customCss ?? []), 'starlight-heading-badges/styles.css'],
+        })
+      },
+    },
+  }
+}

package/libs/badge.ts

@@ -0,0 +1,37 @@
+export const BadgeDirectiveName = 'badge'
+
+const variants = ['caution', 'danger', 'default', 'note', 'success', 'tip'] as const
+
+const serializedBadgeDelimiter = '__SHB__'
+
+export function isBadgeVariant(value: string): value is Variant {
+  return variants.includes(value as Variant)
+}
+
+export function serializeBadge(variant: Variant, text: string) {
+  return [serializedBadgeDelimiter, variant, serializedBadgeDelimiter, text, serializedBadgeDelimiter].join('')
+}
+
+export function deserializeBadge(value: string): Badge | undefined {
+  const serializeBadge = value.split(' ').pop()
+  if (!serializeBadge) return
+
+  const parts = serializeBadge.split(serializedBadgeDelimiter)
+  const [, variant, text] = parts
+
+  if (!variant || !isBadgeVariant(variant) || !text) return undefined
+
+  return {
+    heading: value.replace(new RegExp(`${serializedBadgeDelimiter}.*${serializedBadgeDelimiter}`), ''),
+    text,
+    variant,
+  }
+}
+
+export type Variant = (typeof variants)[number]
+
+export interface Badge {
+  heading: string
+  text: string
+  variant: Variant
+}

package/libs/integration.ts

@@ -0,0 +1,21 @@
+import { rehypeHeadingIds } from '@astrojs/markdown-remark'
+import type { AstroIntegration } from 'astro'
+
+import { rehypeStarlightHeadingBadges } from './rehype'
+import { remarkStarlightHeadingBadges } from './remark'
+
+export function starlightHeadingBadgesIntegration(): AstroIntegration {
+  return {
+    name: 'starlight-heading-badges-integration',
+    hooks: {
+      'astro:config:setup': ({ updateConfig }) => {
+        updateConfig({
+          markdown: {
+            rehypePlugins: [rehypeHeadingIds, rehypeStarlightHeadingBadges],
+            remarkPlugins: [remarkStarlightHeadingBadges],
+          },
+        })
+      },
+    },
+  }
+}

package/libs/plugin.ts

@@ -0,0 +1,30 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types'
+import type { AstroIntegrationLogger } from 'astro'
+
+export function overrideComponents(
+  starlightConfig: StarlightUserConfig,
+  overrides: ComponentOverride[],
+  logger: AstroIntegrationLogger,
+): StarlightUserConfig['components'] {
+  const components = { ...starlightConfig.components }
+
+  for (const { name, fallback } of overrides) {
+    if (starlightConfig.components?.[name]) {
+      logger.warn(`A \`<${name}>\` component override is already defined in your Starlight configuration.`)
+      logger.warn(
+        `To use \`starlight-heading-badges\`, either remove this override or manually render the content from \`starlight-heading-badges/components/${fallback}.astro\`.`,
+      )
+      continue
+    }
+    components[name] = `starlight-heading-badges/overrides/${name}.astro`
+  }
+
+  return components
+}
+
+interface ComponentOverride {
+  name: keyof NonNullable<StarlightUserConfig['components']>
+  fallback: string
+}
+
+type StarlightUserConfig = Parameters<StarlightPlugin['hooks']['setup']>['0']['config']

package/libs/rehype.ts

@@ -0,0 +1,42 @@
+import 'mdast-util-directive'
+
+import type { ElementContent, Root } from 'hast'
+import { CONTINUE, SKIP, visit } from 'unist-util-visit'
+
+import { deserializeBadge, type Badge } from './badge'
+
+export function rehypeStarlightHeadingBadges() {
+  return function transformer(tree: Root) {
+    visit(tree, (node, index, parent) => {
+      if (node.type === 'text') {
+        if (index === undefined || !parent) return CONTINUE
+
+        const badge = deserializeBadge(node.value)
+        if (!badge) return SKIP
+
+        if (badge.heading) {
+          node.value = badge.heading
+          parent.children.splice(index + 1, 0, createBadgeNode(badge))
+        } else {
+          parent.children.splice(index, 1, createBadgeNode(badge))
+        }
+
+        return SKIP
+      }
+
+      return CONTINUE
+    })
+  }
+}
+
+function createBadgeNode(badge: Badge): ElementContent {
+  return {
+    type: 'element',
+    tagName: 'span',
+    properties: {
+      'data-shb-badge': '',
+      'data-shb-badge-variant': badge.variant,
+    },
+    children: [{ type: 'text', value: badge.text }],
+  }
+}

package/libs/remark.ts

@@ -0,0 +1,64 @@
+import 'mdast-util-directive'
+
+import GithubSlugger from 'github-slugger'
+import type { Root } from 'mdast'
+import { CONTINUE, SKIP, visit } from 'unist-util-visit'
+
+import { BadgeDirectiveName, isBadgeVariant, serializeBadge, type Variant } from './badge'
+
+export function remarkStarlightHeadingBadges() {
+  return function transformer(tree: Root) {
+    const slugger = new GithubSlugger()
+
+    visit(tree, (node, index, parent) => {
+      if (!parent || typeof index !== 'number' || parent.type !== 'heading') return CONTINUE
+
+      if (index === 0) {
+        let headingText = ''
+
+        visit(parent, (headingNode, _, headingParent) => {
+          if (
+            headingParent?.type !== 'textDirective' &&
+            (headingNode.type === 'text' || headingNode.type === 'inlineCode')
+          ) {
+            headingText += headingNode.value
+          }
+        })
+
+        headingText = headingText.trim()
+
+        if (!headingText) return CONTINUE
+
+        parent.data ??= {}
+        parent.data.hProperties ??= {}
+        parent.data.hProperties['id'] = slugger.slug(headingText)
+      }
+
+      if (node.type !== 'textDirective' || node.name !== BadgeDirectiveName) return CONTINUE
+
+      const contentNode = node.children[0]
+      if (!contentNode || contentNode.type !== 'text' || contentNode.value.length === 0) return CONTINUE
+
+      let variant: Variant = 'default'
+
+      if (node.attributes?.['variant']) {
+        if (isBadgeVariant(node.attributes['variant'])) {
+          variant = node.attributes['variant']
+        } else {
+          return CONTINUE
+        }
+      }
+
+      if (parent.children.length !== index + 1) {
+        parent.children.splice(parent.children.length, 0, { type: 'text', value: ' ' })
+      }
+      parent.children.splice(index, 1)
+      parent.children.splice(parent.children.length, 0, {
+        type: 'text',
+        value: serializeBadge(variant, contentNode.value),
+      })
+
+      return SKIP
+    })
+  }
+}

package/libs/starlight-toc.ts

@@ -0,0 +1,116 @@
+/**
+ * A copy of the Starlight `<starlight-toc>` component with support for badges.
+ * @see https://github.com/withastro/starlight/blob/1d32c8b0cec0ea5f66351b21b91748dfa78b404b/packages/starlight/components/TableOfContents/starlight-toc.ts
+ */
+
+const PAGE_TITLE_ID = '_top'
+
+export class StarlightTOC extends HTMLElement {
+  private _current = this.querySelector<HTMLAnchorElement>('a[aria-current="true"]')
+  private minH = Number.parseInt(this.dataset['minH'] ?? '2', 10)
+  private maxH = Number.parseInt(this.dataset['maxH'] ?? '3', 10)
+
+  protected set current(link: HTMLAnchorElement) {
+    if (link === this._current) return
+    if (this._current) this._current.removeAttribute('aria-current')
+    link.setAttribute('aria-current', 'true')
+    this._current = link
+  }
+
+  protected get current(): HTMLAnchorElement | null {
+    return this._current
+  }
+
+  constructor() {
+    super()
+
+    /** All the links in the table of contents. */
+    const links = [...this.querySelectorAll('a')]
+
+    /** Walk up the DOM to find the nearest heading. */
+    const getElementHeading = (el: Element | null): HTMLHeadingElement | null => {
+      if (!el) return null
+      const origin = el
+      while (el) {
+        if (this.isHeading(el)) return el
+        // Assign the previous sibling’s last, most deeply nested child to el.
+        el = el.previousElementSibling
+        while (el?.lastElementChild) {
+          el = el.lastElementChild
+        }
+        // Look for headings amongst siblings.
+        const h = getElementHeading(el)
+        if (h) return h
+      }
+      // Walk back up the parent.
+      return getElementHeading(origin.parentElement)
+    }
+
+    /** Handle intersections and set the current link to the heading for the current intersection. */
+    const setCurrent: IntersectionObserverCallback = (entries) => {
+      for (const { isIntersecting, target } of entries) {
+        if (!isIntersecting) continue
+        const heading = getElementHeading(target)
+        if (!heading) continue
+        const link = links.find((link) => link.hash === `#${encodeURIComponent(heading.id)}`)
+        if (link) {
+          this.current = link
+          break
+        }
+      }
+    }
+
+    // Observe elements with an `id` (most likely headings) and their siblings.
+    // Also observe direct children of `.content` to include elements before
+    // the first heading.
+    const toObserve = document.querySelectorAll('main [id], main [id] ~ *, main .content > *')
+
+    let observer: IntersectionObserver | undefined
+    const observe = () => {
+      if (observer) observer.disconnect()
+      observer = new IntersectionObserver(setCurrent, { rootMargin: this.getRootMargin() })
+      for (const element of toObserve) observer.observe(element)
+    }
+    observe()
+
+    // `requestIdleCallback` is not available in Safari.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1))
+    let timeout: NodeJS.Timeout
+    window.addEventListener('resize', () => {
+      // Disable intersection observer while window is resizing.
+      if (observer) observer.disconnect()
+      clearTimeout(timeout)
+      timeout = setTimeout(() => onIdle(observe), 200)
+    })
+  }
+
+  /** Test if an element is a table-of-contents heading. */
+  private isHeading = (el: Element): el is HTMLHeadingElement => {
+    if (el instanceof HTMLHeadingElement) {
+      // Special case for page title h1
+      if (el.id === PAGE_TITLE_ID) return true
+      // Check the heading level is within the user-configured limits for the ToC
+      const level = el.tagName[1]
+      if (level) {
+        const int = Number.parseInt(level, 10)
+        if (int >= this.minH && int <= this.maxH) return true
+      }
+    }
+    return false
+  }
+
+  private getRootMargin(): `-${number}px 0% ${number}px` {
+    const navBarHeight = document.querySelector('header')?.getBoundingClientRect().height ?? 0
+    // `<summary>` only exists in mobile ToC, so will fall back to 0 in large viewport component.
+    const mobileTocHeight = this.querySelector('summary')?.getBoundingClientRect().height ?? 0
+    /** Start intersections at nav height + 2rem padding. */
+    const top = navBarHeight + mobileTocHeight + 32
+    /** End intersections `53px` later. This is slightly more than the maximum `margin-top` in Markdown content. */
+    const bottom = top + 53
+    const height = document.documentElement.clientHeight
+    return `-${top}px 0% ${bottom - height}px`
+  }
+}
+
+customElements.define('starlight-toc', StarlightTOC)

package/overrides/MobileTableOfContents.astro

@@ -0,0 +1,7 @@
+---
+import type { Props } from '@astrojs/starlight/props'
+
+import HeadingBadgesMobileTableOfContents from '../components/HeadingBadgesMobileTableOfContents.astro'
+---
+
+<HeadingBadgesMobileTableOfContents {...Astro.props} />

package/overrides/TableOfContents.astro

@@ -0,0 +1,7 @@
+---
+import type { Props } from '@astrojs/starlight/props'
+
+import HeadingBadgesTableOfContents from '../components/HeadingBadgesTableOfContents.astro'
+---
+
+<HeadingBadgesTableOfContents {...Astro.props} />

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "starlight-heading-badges",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Starlight plugin to add badges to your Markdown and MDX headings.",
+  "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./components/HeadingBadgesMobileTableOfContents.astro": "./components/HeadingBadgesMobileTableOfContents.astro",
+    "./components/HeadingBadgesTableOfContents.astro": "./components/HeadingBadgesTableOfContents.astro",
+    "./overrides/MobileTableOfContents.astro": "./overrides/MobileTableOfContents.astro",
+    "./overrides/TableOfContents.astro": "./overrides/TableOfContents.astro",
+    "./styles.css": "./styles.css",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@astrojs/markdown-remark": "^5.1.1",
+    "github-slugger": "^2.0.0",
+    "unist-util-visit": "^5.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.45.0",
+    "@types/hast": "^3.0.4",
+    "@types/mdast": "^4.0.4",
+    "mdast-util-directive": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.24.5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "starlight",
+    "plugin",
+    "badges",
+    "headings",
+    "documentation",
+    "astro"
+  ],
+  "homepage": "https://github.com/HiDeoo/starlight-heading-badges",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HiDeoo/starlight-heading-badges.git",
+    "directory": "packages/starlight-heading-badges"
+  },
+  "bugs": "https://github.com/HiDeoo/starlight-heading-badges/issues",
+  "scripts": {
+    "test": "playwright install --with-deps chromium && playwright test",
+    "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0"
+  }
+}

package/styles.css

@@ -0,0 +1,60 @@
+span[data-shb-badge] {
+  background-color: var(--sl-color-bg-badge);
+  border: 1px solid var(--sl-color-border-badge);
+  border-radius: 0.25rem;
+  color: var(--sl-color-text-badge);
+  display: inline-block;
+  font-family: var(--sl-font-system-mono);
+  font-size: var(--sl-text-sm);
+  line-height: normal;
+  overflow-wrap: anywhere;
+  padding: 0.175rem 0.35rem;
+  vertical-align: middle;
+}
+
+:is(h5, h6) span[data-shb-badge] {
+  font-size: var(--sl-text-xs);
+  padding: 0.0625rem 0.25rem;
+}
+
+mobile-starlight-toc span[data-shb-badge] {
+  font-size: 0.75rem;
+  margin-inline-start: 1ch;
+  padding: 0.0625rem 0.25rem;
+}
+
+span[data-shb-badge-variant='default'] {
+  --sl-color-bg-badge: var(--sl-badge-default-bg);
+  --sl-color-border-badge: var(--sl-badge-default-border);
+  --sl-color-text-badge: var(--sl-badge-default-text);
+}
+
+span[data-shb-badge-variant='note'] {
+  --sl-color-bg-badge: var(--sl-badge-note-bg);
+  --sl-color-border-badge: var(--sl-badge-note-border);
+  --sl-color-text-badge: var(--sl-badge-note-text);
+}
+
+span[data-shb-badge-variant='danger'] {
+  --sl-color-bg-badge: var(--sl-badge-danger-bg);
+  --sl-color-border-badge: var(--sl-badge-danger-border);
+  --sl-color-text-badge: var(--sl-badge-danger-text);
+}
+
+span[data-shb-badge-variant='success'] {
+  --sl-color-bg-badge: var(--sl-badge-success-bg);
+  --sl-color-border-badge: var(--sl-badge-success-border);
+  --sl-color-text-badge: var(--sl-badge-success-text);
+}
+
+span[data-shb-badge-variant='tip'] {
+  --sl-color-bg-badge: var(--sl-badge-tip-bg);
+  --sl-color-border-badge: var(--sl-badge-tip-border);
+  --sl-color-text-badge: var(--sl-badge-tip-text);
+}
+
+span[data-shb-badge-variant='caution'] {
+  --sl-color-bg-badge: var(--sl-badge-caution-bg);
+  --sl-color-border-badge: var(--sl-badge-caution-border);
+  --sl-color-text-badge: var(--sl-badge-caution-text);
+}