starlight-obsidian 0.1.1 → 0.3.0

package/index.ts

@@ -1,4 +1,5 @@
 import type { StarlightPlugin, StarlightUserConfig } from '@astrojs/starlight/types'
+import type { AstroIntegrationLogger } from 'astro'
 import { z } from 'astro/zod'
 
 import { starlightObsidianIntegration } from './libs/integration'
@@ -7,6 +8,12 @@ import { throwUserError } from './libs/plugin'
 import { addObsidianFiles, getSidebarFromConfig, getSidebarGroupPlaceholder } from './libs/starlight'
 
 const starlightObsidianConfigSchema = z.object({
+  /**
+   * Add links to Starlight headings to make it easier to share a link to a specific section of a page.
+   *
+   * @default false
+   */
+  autoLinkHeadings: z.boolean().default(false),
   /**
    * The name of the Obsidian vault configuration folder if different from the default one.
    *
@@ -30,6 +37,15 @@ const starlightObsidianConfigSchema = z.object({
    * @default 'notes'
    */
   output: z.string().default('notes'),
+  /**
+   * Whether the Starlight Obsidian plugin should skip the generation of the Obsidian vault pages.
+   *
+   * This is useful to disable generating the Obsidian vault pages when deploying on platforms that do not have access
+   * to the Obsidian vault. This will require you to build and commit the pages locally ahead of time.
+   *
+   * @default false
+   */
+  skipGeneration: z.boolean().default(false),
   /**
    * The generated vault pages sidebar group configuration.
    */
@@ -55,6 +71,14 @@ const starlightObsidianConfigSchema = z.object({
       label: z.string().default('Notes'),
     })
     .default({}),
+  /**
+   * Determines if the table of contents top-level heading should be the Starlight default one ("Overview") or the page
+   * title.
+   * This option is useful when the Obsidian vault pages already have a top-level heading named "Overview".
+   *
+   * @default 'title'
+   */
+  tableOfContentsOverview: z.union([z.literal('default'), z.literal('title')]).default('default'),
   /**
    * The absolute or relative path to the Obsidian vault to publish.
    */
@@ -82,44 +106,68 @@ export default function starlightObsidianPlugin(userConfig: StarlightObsidianUse
           return
         }
 
+        const customCss = [...(starlightConfig.customCss ?? []), 'starlight-obsidian/styles/common']
+
+        if (config.autoLinkHeadings) {
+          customCss.push('starlight-obsidian/styles/autolinks-headings')
+        }
+
         const updatedStarlightConfig: Partial<StarlightUserConfig> = {
-          customCss: [...(starlightConfig.customCss ?? []), 'starlight-obsidian/styles'],
+          customCss,
           sidebar: getSidebarFromConfig(config, starlightConfig.sidebar),
         }
 
+        if (!updatedStarlightConfig.components) {
+          updatedStarlightConfig.components = {}
+        }
+
         if (starlightConfig.components?.PageTitle) {
-          logger.warn(
-            'It looks like you already have a `PageTitle` component override in your Starlight configuration.',
-          )
-          logger.warn('To use `starlight-obsidian`, remove the override for the `PageTitle` component.\n')
+          logComponentOverrideWarning(logger, 'PageTitle')
         } else {
-          updatedStarlightConfig.components = {
-            PageTitle: 'starlight-obsidian/overrides/PageTitle.astro',
+          updatedStarlightConfig.components.PageTitle = 'starlight-obsidian/overrides/PageTitle.astro'
+        }
+
+        if (config.tableOfContentsOverview === 'title') {
+          if (starlightConfig.components?.PageSidebar) {
+            logComponentOverrideWarning(logger, 'PageSidebar')
+          } else {
+            updatedStarlightConfig.components.PageSidebar = 'starlight-obsidian/overrides/PageSidebar.astro'
           }
         }
 
-        try {
-          const start = performance.now()
-          logger.info('Generating Starlight pages from Obsidian vault…')
+        if (config.skipGeneration) {
+          logger.warn(
+            `Skipping generation of Starlight pages from Obsidian vault as the 'skipGeneration' option is enabled.`,
+          )
+        } else {
+          try {
+            const start = performance.now()
+            logger.info('Generating Starlight pages from Obsidian vault…')
 
-          const vault = await getVault(config)
-          const obsidianPaths = await getObsidianPaths(vault, config.ignore)
-          await addObsidianFiles(config, vault, obsidianPaths, logger)
+            const vault = await getVault(config)
+            const obsidianPaths = await getObsidianPaths(vault, config.ignore)
+            await addObsidianFiles(config, vault, obsidianPaths, logger)
 
-          const duration = Math.round(performance.now() - start)
-          logger.info(`Starlight pages generated from Obsidian vault in ${duration}ms.`)
-        } catch (error) {
-          logger.error(error instanceof Error ? error.message : String(error))
+            const duration = Math.round(performance.now() - start)
+            logger.info(`Starlight pages generated from Obsidian vault in ${duration}ms.`)
+          } catch (error) {
+            logger.error(error instanceof Error ? error.message : String(error))
 
-          throwUserError('Failed to generate Starlight pages from Obsidian vault.')
+            throwUserError('Failed to generate Starlight pages from Obsidian vault.')
+          }
         }
 
-        addIntegration(starlightObsidianIntegration())
+        addIntegration(starlightObsidianIntegration(config))
         updateConfig(updatedStarlightConfig)
       },
     },
   }
 }
 
+function logComponentOverrideWarning(logger: AstroIntegrationLogger, component: string) {
+  logger.warn(`It looks like you already have a \`${component}\` component override in your Starlight configuration.`)
+  logger.warn(`To use \`starlight-obsidian\`, remove the override for the \`${component}\` component.\n`)
+}
+
 export type StarlightObsidianUserConfig = z.input<typeof starlightObsidianConfigSchema>
 export type StarlightObsidianConfig = z.output<typeof starlightObsidianConfigSchema>

package/libs/integration.ts

@@ -1,19 +1,33 @@
+import { rehypeHeadingIds } from '@astrojs/markdown-remark'
 import type { AstroIntegration } from 'astro'
+import rehypeAutolinkHeadings from 'rehype-autolink-headings'
 import rehypeKatex from 'rehype-katex'
 import remarkMath from 'remark-math'
 
-import { rehypeStarlightObsidian } from './rehype'
+import type { StarlightObsidianConfig } from '..'
 
-export function starlightObsidianIntegration(): AstroIntegration {
+import { getRehypeAutolinkHeadingsOptions, rehypeStarlightObsidian } from './rehype'
+import { vitePluginStarlightObsidianConfig } from './vite'
+
+export function starlightObsidianIntegration(config: StarlightObsidianConfig): AstroIntegration {
   return {
     name: 'starlight-obsidian-integration',
     hooks: {
       'astro:config:setup': ({ updateConfig }) => {
         updateConfig({
           markdown: {
-            rehypePlugins: [rehypeStarlightObsidian, rehypeKatex],
+            rehypePlugins: [
+              ...(config.autoLinkHeadings
+                ? [rehypeHeadingIds, [rehypeAutolinkHeadings, getRehypeAutolinkHeadingsOptions()]]
+                : []),
+              rehypeStarlightObsidian,
+              rehypeKatex,
+            ],
             remarkPlugins: [remarkMath],
           },
+          vite: {
+            plugins: [vitePluginStarlightObsidianConfig(config)],
+          },
         })
       },
     },

package/libs/rehype.ts

@@ -1,5 +1,9 @@
 import type { Element, ElementContent, Root } from 'hast'
+import { toString } from 'hast-util-to-string'
+import { h } from 'hastscript'
+import { escape } from 'html-escaper'
 import type { Literal } from 'mdast'
+import type { Options as RehypeAutolinkHeadingsOptions } from 'rehype-autolink-headings'
 import { CONTINUE, SKIP, visit } from 'unist-util-visit'
 
 const blockIdentifierRegex = /(?<identifier> *\^(?<name>[\w-]+))$/
@@ -25,12 +29,12 @@ export function rehypeStarlightObsidian() {
         const lastGrandChild = lastChild.children.at(-1)
 
         if (lastChild.tagName === 'p') {
-          transformBlockIdentifier(node, lastGrandChild)
+          return transformBlockIdentifier(node, lastGrandChild)
         } else if (lastGrandChild?.type === 'element' && lastGrandChild.tagName === 'li') {
-          transformBlockIdentifier(node, lastGrandChild.children.at(-1))
+          return transformBlockIdentifier(node, lastGrandChild.children.at(-1))
         }
       } else if (node.tagName === 'p' || node.tagName === 'li') {
-        transformBlockIdentifier(node, node.children.at(-1))
+        return transformBlockIdentifier(node, node.children.at(-1))
       }
 
       return CONTINUE
@@ -38,6 +42,24 @@ export function rehypeStarlightObsidian() {
   }
 }
 
+// https://hideoo.dev/notes/starlight-heading-links
+// https://github.com/withastro/docs/blob/main/plugins/rehype-autolink.ts
+// https://amberwilson.co.uk/blog/are-your-anchor-links-accessible/
+export function getRehypeAutolinkHeadingsOptions(): RehypeAutolinkHeadingsOptions {
+  return {
+    behavior: 'after',
+    content: (heading) => {
+      return [
+        h('span', { ariaHidden: 'true' }, '§'),
+        h('span', { class: 'sr-only' }, `Section titled ${escape(toString(heading))}`),
+      ]
+    },
+    group: ({ tagName }) =>
+      h('div', { class: `sl-obs-section sl-obs-section-level-${tagName.slice(1)}`, tabIndex: -1 }),
+    properties: { class: 'sl-obs-heading-link' },
+  }
+}
+
 function transformBlockIdentifier(reference: Element, node: ElementContent | undefined) {
   if (!isNodeWithValue(node)) {
     return CONTINUE

package/libs/starlight.ts

@@ -209,19 +209,21 @@ async function addAlias(
   await ensureDirectory(starlightDirPath)
 
   // Based on https://github.com/withastro/astro/blob/57ab578bc7bdac6c65c2315365c0e94bc98af2b3/packages/astro/src/core/build/generate.ts#L584-L591
-  // but tweaked to add an `<html>` element so that Pagefind does not emit a warning when ignoring the page.
+  // but tweaked to add an `<html>` element so that Pagefind does not emit a warning and ignore the page.
   await fs.writeFile(
     starlightPath,
     `<!doctype html>
-<html>
+<html lang="en">
   <head>
-    <title>Redirecting to: ${to}</title>
+    <title>${vaultFile.stem}</title>
     <meta http-equiv="refresh" content="0;url=${to}">
     <meta name="robots" content="noindex">
     <link rel="canonical" href="${to}">
   </head>
-  <body>
-    <a href="${to}">Redirecting from <code>${from}</code> to "<code>${to}</code>"</a>
+  <body data-pagefind-body>
+    <h2 id="alias">Alias</h2>
+    <code>(name: ${alias})</code>
+    <a href="${to}" data-pagefind-ignore>Redirecting from <code>${from}</code> to "<code>${to}</code>"</a>
   </body>
 </html>`,
   )

package/libs/vite.ts

@@ -0,0 +1,21 @@
+import type { ViteUserConfig } from 'astro'
+
+import type { StarlightObsidianConfig } from '..'
+
+export function vitePluginStarlightObsidianConfig(config: StarlightObsidianConfig): VitePlugin {
+  const moduleId = 'virtual:starlight-obsidian-config'
+  const resolvedModuleId = `\0${moduleId}`
+  const moduleContent = `export default ${JSON.stringify(config)}`
+
+  return {
+    name: 'vite-plugin-starlight-obsidian-config',
+    load(id) {
+      return id === resolvedModuleId ? moduleContent : undefined
+    },
+    resolveId(id) {
+      return id === moduleId ? resolvedModuleId : undefined
+    },
+  }
+}
+
+type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number]

package/overrides/PageSidebar.astro

@@ -0,0 +1,67 @@
+---
+import MobileTableOfContents from '@astrojs/starlight/components/MobileTableOfContents.astro'
+import TableOfContents from '@astrojs/starlight/components/TableOfContents.astro'
+import type { Props } from '@astrojs/starlight/props'
+import config from 'virtual:starlight-obsidian-config'
+
+const toc = Astro.props.toc
+
+if (config.tableOfContentsOverview === 'title' && toc) {
+  const firstTocItem = toc.items.at(0)
+
+  if (firstTocItem) {
+    firstTocItem.text = Astro.props.entry['data'].title
+  }
+}
+---
+
+{
+  Astro.props.toc && (
+    <>
+      <div class="lg:sl-hidden">
+        <MobileTableOfContents {...Astro.props} {toc} />
+      </div>
+      <div class="right-sidebar-panel sl-hidden lg:sl-block">
+        <div class="sl-container">
+          <TableOfContents {...Astro.props} {toc} />
+        </div>
+      </div>
+    </>
+  )
+}
+
+<style>
+  .right-sidebar-panel {
+    padding: 1rem var(--sl-sidebar-pad-x);
+  }
+  .sl-container {
+    width: calc(var(--sl-sidebar-width) - 2 * var(--sl-sidebar-pad-x));
+  }
+  .right-sidebar-panel :global(h2) {
+    color: var(--sl-color-white);
+    font-size: var(--sl-text-h5);
+    font-weight: 600;
+    line-height: var(--sl-line-height-headings);
+    margin-bottom: 0.5rem;
+  }
+  .right-sidebar-panel :global(:where(a)) {
+    display: block;
+    font-size: var(--sl-text-xs);
+    text-decoration: none;
+    color: var(--sl-color-gray-3);
+    overflow-wrap: anywhere;
+  }
+  .right-sidebar-panel :global(:where(a):hover) {
+    color: var(--sl-color-white);
+  }
+  @media (min-width: 72rem) {
+    .sl-container {
+      max-width: calc(
+        (
+          (100vw - var(--sl-sidebar-width) - 2 * var(--sl-content-pad-x) - 2 * var(--sl-sidebar-pad-x)) * 0.25
+            /* MAGIC NUMBER 🥲 */
+        )
+      );
+    }
+  }
+</style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-obsidian",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "Starlight plugin to publish Obsidian vaults.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
@@ -9,22 +9,29 @@
     ".": "./index.ts",
     "./components/Twitter.astro": "./components/Twitter.astro",
     "./components/Youtube.astro": "./components/Youtube.astro",
+    "./overrides/PageSidebar.astro": "./overrides/PageSidebar.astro",
     "./overrides/PageTitle.astro": "./overrides/PageTitle.astro",
     "./schema": "./schema.ts",
-    "./styles": "./styles.css",
+    "./styles/common": "./styles/common.css",
+    "./styles/autolinks-headings": "./styles/autolinks-headings.css",
     "./package.json": "./package.json"
   },
   "dependencies": {
     "@astro-community/astro-embed-twitter": "0.5.3",
     "@astro-community/astro-embed-youtube": "0.4.4",
+    "@astrojs/markdown-remark": "4.2.1",
     "github-slugger": "2.0.0",
     "globby": "14.0.0",
     "hast-util-to-html": "9.0.0",
+    "hast-util-to-string": "3.0.0",
+    "hastscript": "9.0.0",
+    "html-escaper": "3.0.3",
     "is-absolute-url": "4.0.1",
     "mdast-util-find-and-replace": "3.0.1",
     "mdast-util-to-hast": "13.1.0",
     "nanoid": "5.0.4",
     "rehype": "13.0.1",
+    "rehype-autolink-headings": "7.1.0",
     "rehype-katex": "7.0.0",
     "rehype-mermaid": "2.1.0",
     "remark": "15.0.1",
@@ -38,6 +45,7 @@
   "devDependencies": {
     "@astrojs/starlight": "0.16.0",
     "@types/hast": "3.0.3",
+    "@types/html-escaper": "3.0.2",
     "@types/mdast": "4.0.3",
     "@types/unist": "3.0.2",
     "astro": "4.2.1",

package/styles/autolinks-headings.css

@@ -0,0 +1,68 @@
+.sl-markdown-content :not(.sl-obs-section) + :is(.sl-obs-section):not(:where(.not-content *)) {
+  margin-top: 1.5em;
+}
+
+.sl-markdown-content .sl-obs-section {
+  --sl-obs-heading-link-spacing: 0.25em;
+
+  line-height: var(--sl-line-height-headings);
+}
+
+.sl-markdown-content .sl-obs-section.sl-obs-section-level-1 {
+  font-size: var(--sl-text-h1);
+}
+
+.sl-markdown-content .sl-obs-section.sl-obs-section-level-2 {
+  font-size: var(--sl-text-h2);
+}
+
+.sl-markdown-content .sl-obs-section.sl-obs-section-level-3 {
+  font-size: var(--sl-text-h3);
+}
+
+.sl-markdown-content .sl-obs-section.sl-obs-section-level-4 {
+  font-size: var(--sl-text-h4);
+}
+
+.sl-markdown-content .sl-obs-section.sl-obs-section-level-5 {
+  font-size: var(--sl-text-h5);
+}
+
+.sl-markdown-content .sl-obs-section.sl-obs-section-level-6 {
+  font-size: var(--sl-text-h6);
+}
+
+.sl-markdown-content .sl-obs-section > :first-child {
+  display: inline;
+  margin-inline-end: var(--sl-obs-heading-link-spacing);
+}
+
+.sl-markdown-content .sl-obs-heading-link {
+  color: var(--sl-color-gray-3);
+  text-decoration: none;
+}
+
+.sl-markdown-content .sl-obs-heading-link:is(:hover, :focus) {
+  color: var(--sl-color-text-accent);
+}
+
+@media (hover: hover) {
+  .sl-markdown-content .sl-obs-heading-link {
+    opacity: 0;
+  }
+}
+
+.sl-markdown-content .sl-obs-section:hover > .sl-obs-heading-link,
+.sl-markdown-content .sl-obs-heading-link:focus {
+  opacity: 1;
+}
+
+@media (min-width: 95em) {
+  .sl-markdown-content .sl-obs-section {
+    display: flex;
+    flex-direction: row-reverse;
+    gap: var(--sl-obs-heading-link-spacing);
+    justify-content: flex-end;
+    margin-inline-start: calc(-1 * (1ch + var(--sl-obs-heading-link-spacing)));
+  }
+}

package/virtual.d.ts

@@ -0,0 +1,5 @@
+declare module 'virtual:starlight-obsidian-config' {
+  const StarlightObsidianConfig: import('./index').StarlightObsidianConfig
+
+  export default StarlightObsidianConfig
+}