starlight-obsidian 0.3.0 → 0.4.0

package/index.ts

@@ -21,6 +21,17 @@ const starlightObsidianConfigSchema = z.object({
    * @see https://help.obsidian.md/Files+and+folders/Configuration+folder
    */
   configFolder: z.string().startsWith('.').default('.obsidian'),
+  /**
+   * Whether the Starlight Obsidian plugin should copy known Starlight frontmatter fields from Obsidian notes to the
+   * generated pages.
+   *
+   * This is useful if you want to customize the generated Starlight pages from Obsidian. Note that the values are not
+   * validated and are copied as-is so it's up to you to ensure they are compatible with Starlight.
+   *
+   * @default false
+   * @see https://starlight.astro.build/reference/frontmatter/
+   */
+  copyStarlightFrontmatter: z.boolean().default(false),
   /**
    * A list of glob patterns to ignore when generating the Obsidian vault pages.
    * This option can be used to ignore files or folders.

package/libs/obsidian.ts

@@ -155,7 +155,8 @@ export function isObsidianFile(filePath: string, type?: 'image' | 'audio' | 'vid
 
 export function parseObsidianFrontmatter(content: string): ObsidianFrontmatter | undefined {
   try {
-    return obsidianFrontmatterSchema.parse(yaml.parse(content))
+    const raw: unknown = yaml.parse(content)
+    return { ...obsidianFrontmatterSchema.parse(raw), raw: raw as ObsidianFrontmatter['raw'] }
   } catch {
     return
   }
@@ -222,4 +223,6 @@ export interface VaultFile extends BaseVaultFile {
   isEqualStem(otherStem: string): boolean
 }
 
-export type ObsidianFrontmatter = z.output<typeof obsidianFrontmatterSchema>
+export type ObsidianFrontmatter = z.output<typeof obsidianFrontmatterSchema> & {
+  raw: Record<string | number, unknown>
+}

package/libs/remark.ts

@@ -29,7 +29,7 @@ import {
   type VaultFile,
 } from './obsidian'
 import { extractPathAndAnchor, getExtension, isAnchor } from './path'
-import { getStarlightCalloutType, isAssetFile } from './starlight'
+import { getStarlightCalloutType, getStarlightLikeFrontmatter, isAssetFile } from './starlight'
 
 const generateAssetImportId = customAlphabet('abcdefghijklmnopqrstuvwxyz', 6)
 
@@ -420,21 +420,28 @@ async function handleMermaid(tree: Root, file: VFile) {
 }
 
 function getFrontmatterNodeValue(file: VFile, obsidianFrontmatter?: ObsidianFrontmatter) {
-  const frontmatter: Frontmatter = {
+  let frontmatter: Frontmatter = {
     title: file.stem,
     editUrl: false,
   }
 
+  if (obsidianFrontmatter && file.data.copyStarlightFrontmatter) {
+    const starlightLikeFrontmatter = getStarlightLikeFrontmatter(obsidianFrontmatter.raw)
+    frontmatter = { ...frontmatter, ...starlightLikeFrontmatter }
+  }
+
   if (file.data.includeKatexStyles) {
-    frontmatter.head = [
-      {
-        tag: 'link',
-        attrs: {
-          rel: 'stylesheet',
-          href: 'https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css',
-        },
+    if (!frontmatter.head) {
+      frontmatter.head = []
+    }
+
+    frontmatter.head.push({
+      tag: 'link',
+      attrs: {
+        rel: 'stylesheet',
+        href: 'https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css',
       },
-    ]
+    })
   }
 
   const ogImage = obsidianFrontmatter?.cover ?? obsidianFrontmatter?.image
@@ -634,6 +641,7 @@ function ensureTransformContext(file: VFile): asserts file is VFile & { data: Tr
 export interface TransformContext {
   aliases?: string[]
   assetImports?: [id: string, path: string][]
+  copyStarlightFrontmatter?: boolean
   files: VaultFile[]
   includeKatexStyles?: boolean
   includeTwitterComponent?: boolean

package/libs/starlight.ts

@@ -8,7 +8,7 @@ import type { StarlightObsidianConfig } from '..'
 
 import { copyFile, ensureDirectory, removeDirectory } from './fs'
 import { transformMarkdownToString } from './markdown'
-import { getObsidianVaultFiles, isObsidianFile, type Vault, type VaultFile } from './obsidian'
+import { getObsidianVaultFiles, isObsidianFile, type ObsidianFrontmatter, type Vault, type VaultFile } from './obsidian'
 import { getExtension } from './path'
 
 const assetsPath = 'src/assets'
@@ -47,6 +47,24 @@ const obsidianToStarlightCalloutTypeMap: Record<string, string> = {
   cite: 'note',
 }
 
+// https://github.com/withastro/starlight/blob/main/packages/starlight/schema.ts
+const starlightFrontmatterKeys = [
+  'title',
+  // The `description` property is ignored as it's part of the Obsidian frontmatter too.
+  'slug',
+  'editUrl',
+  'head',
+  'tableOfContents',
+  'template',
+  'hero',
+  'banner',
+  'lastUpdated',
+  'prev',
+  'next',
+  'pagefind',
+  'sidebar',
+]
+
 export function getSidebarGroupPlaceholder(): SidebarManualGroup {
   return {
     items: [],
@@ -135,6 +153,18 @@ export function isAssetFile(filePath: string): boolean {
   return getExtension(filePath) !== '.bmp' && isObsidianFile(filePath, 'image')
 }
 
+export function getStarlightLikeFrontmatter(rawFrontmatter: ObsidianFrontmatter['raw']): Record<string, unknown> {
+  const frontmatter: Record<string, unknown> = {}
+
+  for (const key of starlightFrontmatterKeys) {
+    if (key in rawFrontmatter) {
+      frontmatter[key] = rawFrontmatter[key]
+    }
+  }
+
+  return frontmatter
+}
+
 async function addContent(
   config: StarlightObsidianConfig,
   vault: Vault,
@@ -151,6 +181,7 @@ async function addContent(
       type,
     } = await transformMarkdownToString(vaultFile.fsPath, obsidianContent, {
       files: vaultFiles,
+      copyStarlightFrontmatter: config.copyStarlightFrontmatter,
       output: config.output,
       vault,
     })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-obsidian",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "Starlight plugin to publish Obsidian vaults.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",