starlight-obsidian 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # starlight-obsidian
 
+## 0.13.0
+
+### Minor Changes
+
+- [#74](https://github.com/HiDeoo/starlight-obsidian/pull/74) [`175ab3f`](https://github.com/HiDeoo/starlight-obsidian/commit/175ab3f553eb77ee4004d30330c05b6f416393b4) Thanks [@HiDeoo](https://github.com/HiDeoo)! - ⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now `0.39.0`.
+
+  Please use the `@astrojs/upgrade` command to upgrade your project:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
+- [#74](https://github.com/HiDeoo/starlight-obsidian/pull/74) [`175ab3f`](https://github.com/HiDeoo/starlight-obsidian/commit/175ab3f553eb77ee4004d30330c05b6f416393b4) Thanks [@HiDeoo](https://github.com/HiDeoo)! - ⚠️ **BREAKING CHANGE:** Updates sidebar generation to support Starlight `0.39` autogenerated sidebar entries.
+
+  The previously exported `obsidianSidebarGroup` has been replaced by `obsidianSidebarEntries`, which now expands to the generated Obsidian sidebar entries.
+  The `sidebar.label` and `sidebar.collapsed` plugin options have been removed.
+
+  To migrate, create a [sidebar group](https://starlight.astro.build/guides/sidebar/#groups) in your Starlight configuration and place `obsidianSidebarEntries` in that group’s `items` array:
+
+  ```diff
+  -import starlightObsidian, { obsidianSidebarGroup } from 'starlight-obsidian'
+  +import starlightObsidian, { obsidianSidebarEntries } from 'starlight-obsidian'
+
+  starlight({
+    plugins: [
+      starlightObsidian({
+        vault: '../path/to/vault',
+        sidebar: {
+  -       label: 'Notes',
+  -       collapsed: true,
+          collapsedFolders: true,
+        },
+      }),
+    ],
+    sidebar: [
+  -   obsidianSidebarGroup,
+  +   {
+  +     label: 'Notes',
+  +     collapsed: true,
+  +     items: [obsidianSidebarEntries],
+  +   },
+    ],
+  })
+  ```
+
 ## 0.12.1
 
 ### Patch Changes

package/index.ts

@@ -8,7 +8,12 @@ import { starlightObsidianIntegration } from './libs/integration'
 import { getObsidianPaths, getVault } from './libs/obsidian'
 import { stripLeadingAndTrailingSlashes } from './libs/path'
 import { throwUserError } from './libs/plugin'
-import { addObsidianFiles, getSidebarFromConfig, getSidebarGroupPlaceholder, type SidebarGroup } from './libs/starlight'
+import {
+  addObsidianFiles,
+  getSidebarEntriesPlaceholder,
+  getSidebarFromConfig,
+  type SidebarAutoEntries,
+} from './libs/starlight'
 
 const starlightObsidianConfigSchema = z.object({
   /**
@@ -88,31 +93,24 @@ const starlightObsidianConfigSchema = z.object({
    */
   skipGeneration: z.boolean().default(false),
   /**
-   * The generated vault pages sidebar group configuration.
+   * The generated vault pages sidebar entries configuration.
    */
   sidebar: z
     .object({
       /**
-       * Whether the generated vault pages root sidebar group should be collapsed by default.
-       *
-       * @default false
+       * @deprecated Use the `collapsed` option of the Starlight sidebar group that contains the vault pages instead.
        */
-      collapsed: z.boolean().default(false),
+      collapsed: z.never().optional(),
       /**
        * Whether the sidebar groups of your vault nested folders should be collapsed by default.
        *
-       * Defaults to the value of the `collapsed` option.
+       * @default false
        */
-      collapsedFolders: z.boolean().optional(),
+      collapsedFolders: z.boolean().default(false),
       /**
-       * The generated vault pages sidebar group label.
-       *
-       * The value can be a string, or for multilingual sites, an object with values for each different locale.
-       * When using the object form, the keys must be BCP-47 tags (e.g. `en`, `ar`, or `zh-CN`).
-       *
-       * @default 'Notes'
+       * @deprecated Use the `label` option of the Starlight sidebar group that contains the vault pages instead.
        */
-      label: z.union([z.string(), z.record(z.string(), z.string())]).default('Notes'),
+      label: z.never().optional(),
     })
     .prefault({}),
   /**
@@ -131,19 +129,22 @@ const starlightObsidianConfigSchema = z.object({
 
 let overridesInjected = false
 
-export const obsidianSidebarGroup = getSidebarGroupPlaceholder()
+export const obsidianSidebarEntries = getSidebarEntriesPlaceholder()
 
 export default function starlightObsidianPlugin(userConfig: StarlightObsidianUserConfig): StarlightPlugin {
-  return makeStarlightObsidianPlugin(obsidianSidebarGroup)(userConfig)
+  return makeStarlightObsidianPlugin(obsidianSidebarEntries)(userConfig)
 }
 
-export function createStarlightObsidianPlugin(): [plugin: typeof starlightObsidianPlugin, sidebarGroup: SidebarGroup] {
-  const sidebarGroup = getSidebarGroupPlaceholder(Symbol(randomBytes(24).toString('base64url')))
-  return [makeStarlightObsidianPlugin(sidebarGroup), sidebarGroup]
+export function createStarlightObsidianPlugin(): [
+  plugin: typeof starlightObsidianPlugin,
+  sidebarEntries: SidebarAutoEntries,
+] {
+  const sidebarEntries = getSidebarEntriesPlaceholder(Symbol(randomBytes(24).toString('base64url')))
+  return [makeStarlightObsidianPlugin(sidebarEntries), sidebarEntries]
 }
 
 function makeStarlightObsidianPlugin(
-  sidebarGroup: SidebarGroup,
+  sidebarEntries: SidebarAutoEntries,
 ): (userConfig: StarlightObsidianUserConfig) => StarlightPlugin {
   overridesInjected = true
 
@@ -151,6 +152,18 @@ function makeStarlightObsidianPlugin(
     const parsedConfig = starlightObsidianConfigSchema.safeParse(userConfig)
 
     if (!parsedConfig.success) {
+      const isUsingRemovedSidebarGroupConfig = parsedConfig.error.issues.some((issue) => {
+        const path = issue.path.join('.')
+        return path === 'sidebar.label' || path === 'sidebar.collapsed'
+      })
+
+      if (isUsingRemovedSidebarGroupConfig) {
+        throwUserError(
+          'The `sidebar.label` and `sidebar.collapsed` options have been removed.',
+          'Create a group in your Starlight sidebar configuration, set the `label` and `collapsed` options on that group, and add `obsidianSidebarEntries` to its `items` array.\nFor more information see https://starlight.astro.build/guides/sidebar/#groups',
+        )
+      }
+
       const isUsingDeprecatedCopyStarlightFrontmatter = parsedConfig.error.issues.some(
         (issue) => issue.path.join('.') === 'copyStarlightFrontmatter',
       )
@@ -197,7 +210,7 @@ ${z.prettifyError(parsedConfig.error)}
               ...overrideStarlightComponent(starlightConfig.components, logger, 'PageTitle'),
             },
             customCss: [...(starlightConfig.customCss ?? []), 'starlight-obsidian/styles/common'],
-            sidebar: getSidebarFromConfig(config, starlightConfig, sidebarGroup),
+            sidebar: getSidebarFromConfig(config, starlightConfig, sidebarEntries),
           }
 
           if (config.skipGeneration) {

package/libs/starlight.ts

@@ -15,7 +15,7 @@ const assetsPath = 'src/assets'
 const docsPath = 'src/content/docs'
 const publicPath = 'public'
 
-const starlightObsidianSidebarGroupLabel = Symbol('StarlightObsidianSidebarGroupLabel')
+const starlightObsidianSidebarEntriesDirectory = Symbol('StarlightObsidianSidebarEntriesDirectory')
 
 const obsidianToStarlightCalloutTypeMap: Record<string, string> = {
   note: 'note',
@@ -66,65 +66,40 @@ const starlightFrontmatterKeys = [
   'sidebar',
 ]
 
-export function getSidebarGroupPlaceholder(label = starlightObsidianSidebarGroupLabel): SidebarManualGroup {
-  return {
-    items: [],
-    label: label.toString(),
-  }
+export function getSidebarEntriesPlaceholder(directory = starlightObsidianSidebarEntriesDirectory): SidebarAutoEntries {
+  return { autogenerate: { directory: directory.toString() } }
 }
 
 export function getSidebarFromConfig(
   config: StarlightObsidianConfig,
   starlightConfig: HookParameters<'config:setup'>['config'],
-  sidebarGroupPlaceholder: SidebarGroup,
+  sidebarEntriesPlaceholder: SidebarAutoEntries,
 ): StarlightUserConfig['sidebar'] {
   if (!starlightConfig.sidebar || starlightConfig.sidebar.length === 0) {
     return starlightConfig.sidebar
   }
 
-  function replaceSidebarGroupPlaceholder(group: SidebarManualGroup): SidebarItem {
-    if (group.label === sidebarGroupPlaceholder.label) {
-      const defaultLocaleConfig = starlightConfig.locales?.[starlightConfig.defaultLocale ?? 'root']
-      const label =
-        typeof config.sidebar.label === 'string'
-          ? config.sidebar.label
-          : config.sidebar.label[defaultLocaleConfig?.lang ?? 'en']
-
-      if (!label || label.length === 0) {
-        throw new Error('The generated vault pages sidebar group label must have a key for the default language.')
-      }
-
-      const group: SidebarGroup = {
+  function replaceSidebarEntriesPlaceholder(item: SidebarItem): SidebarItem {
+    if (isObsidianSidebarEntriesPlaceholder(item, sidebarEntriesPlaceholder)) {
+      return {
         autogenerate: {
-          collapsed: config.sidebar.collapsedFolders ?? config.sidebar.collapsed,
           directory: config.output,
+          collapsed: config.sidebar.collapsedFolders,
         },
-        collapsed: config.sidebar.collapsed,
-        label,
-      }
-
-      if (typeof config.sidebar.label !== 'string') {
-        group['translations'] = config.sidebar.label
       }
-
-      return group
     }
 
-    if (isSidebarGroup(group)) {
+    if (isSidebarGroup(item)) {
       return {
-        ...group,
-        items: group.items.map((item) => {
-          return isSidebarGroup(item) ? replaceSidebarGroupPlaceholder(item) : item
-        }),
+        ...item,
+        items: item.items.map(replaceSidebarEntriesPlaceholder),
       }
     }
 
-    return group
+    return item
   }
 
-  return starlightConfig.sidebar.map((item) => {
-    return isSidebarGroup(item) ? replaceSidebarGroupPlaceholder(item) : item
-  })
+  return starlightConfig.sidebar.map(replaceSidebarEntriesPlaceholder)
 }
 
 export async function addObsidianFiles(
@@ -297,20 +272,27 @@ function throwVaultFileError(error: unknown, vaultFile: VaultFile): never {
   throw new Error(`${vaultFile.path} — ${error instanceof Error ? error.message : String(error)}`, { cause: error })
 }
 
-function isSidebarGroup(item: SidebarItem): item is SidebarManualGroup {
+function isSidebarGroup(item: SidebarItem): item is SidebarGroup {
   return typeof item === 'object' && 'items' in item
 }
 
+function isObsidianSidebarEntriesPlaceholder(
+  item: SidebarItem,
+  placeholder: SidebarAutoEntries,
+): item is SidebarAutoEntries {
+  return (
+    typeof item === 'object' &&
+    'autogenerate' in item &&
+    item.autogenerate.directory === placeholder.autogenerate.directory
+  )
+}
+
 interface OutputPaths {
   asset: string
   content: string
   file: string
 }
 
-interface SidebarManualGroup {
-  items: SidebarManualGroup[]
-  label: string
-}
-
 type SidebarItem = NonNullable<StarlightUserConfig['sidebar']>[number]
-export type SidebarGroup = Exclude<SidebarItem, string>
+type SidebarGroup = Extract<SidebarItem, { items: unknown[] }>
+export type SidebarAutoEntries = Extract<SidebarItem, { autogenerate: unknown }>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-obsidian",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "license": "MIT",
   "description": "Starlight plugin to publish Obsidian vaults.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
@@ -48,7 +48,7 @@
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.34.0"
+    "@astrojs/starlight": ">=0.39.0"
   },
   "engines": {
     "node": ">=22.12.0"