starlight-obsidian 0.3.0 → 0.4.1

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

@@ -9,7 +9,7 @@ import yaml from 'yaml'
 import type { StarlightObsidianConfig } from '..'
 
 import { isDirectory, isFile } from './fs'
-import { getExtension, isAnchor, slugifyPath, stripExtension } from './path'
+import { getExtension, isAnchor, slashify, slugifyPath, stripExtension } from './path'
 import { throwUserError } from './plugin'
 import { isAssetFile } from './starlight'
 
@@ -56,7 +56,7 @@ export async function getVault(config: StarlightObsidianConfig): Promise<Vault>
 
   return {
     options,
-    path: vaultPath,
+    path: slashify(vaultPath),
   }
 }
 
@@ -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/path.ts

@@ -37,3 +37,18 @@ export function slugifyPath(filePath: string) {
     })
     .join('/')
 }
+
+// https://github.com/sindresorhus/slash
+export function slashify(filePath: string) {
+  const isExtendedLengthPath = filePath.startsWith('\\\\?\\')
+
+  if (isExtendedLengthPath) {
+    return filePath
+  }
+
+  return filePath.replaceAll('\\', '/')
+}
+
+export function osPath(filePath: string) {
+  return filePath.replaceAll('/', path.sep)
+}

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)
 
@@ -38,7 +38,7 @@ const commentReplacementRegex = /%%(?<comment>(?:(?!%%).)+)%%/gs
 const wikilinkReplacementRegex = /!?\[\[(?<url>(?:(?![[\]|]).)+)(?:\|(?<maybeText>(?:(?![[\]]).)+))?]]/g
 const tagReplacementRegex = /(?:^|\s)#(?<tag>[\w/-]+)/g
 const calloutRegex = /^\[!(?<type>\w+)][+-]? ?(?<title>.*)$/
-const imageSizeRegex = /^(?<altText>.*)\|(?:(?<widthOnly>\d+)|(?:(?<width>\d+)x(?<height>\d+)))$/
+const imageSizeRegex = /^(?:(?<altText>.*)\|)?(?:(?<widthOnly>\d+)|(?:(?<width>\d+)x(?<height>\d+)))$/
 
 const asideDelimiter = ':::'
 
@@ -358,7 +358,7 @@ function handleBlockquotes(node: Blockquote, context: VisitorContext) {
     return SKIP
   }
 
-  const [firstLine, ...otherLines] = firstGrandChild.value.split('\n')
+  const [firstLine, ...otherLines] = firstGrandChild.value.split(/\r?\n/)
 
   if (!firstLine) {
     return SKIP
@@ -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
@@ -478,7 +485,7 @@ function getRelativeFilePath(file: VFile, relativePath: string) {
 function getAssetPath(file: VFile, relativePath: string) {
   ensureTransformContext(file)
 
-  return path.posix.join('../../..', path.relative(file.dirname, file.data.vault.path), 'assets', relativePath)
+  return path.posix.join('../../..', path.posix.relative(file.dirname, file.data.vault.path), 'assets', relativePath)
 }
 
 function getFilePathFromVaultFile(vaultFile: VaultFile, url: string) {
@@ -527,6 +534,7 @@ function handleImagesWithSize(node: Image, context: VisitorContext, type: 'asset
     return
   }
 
+  const imgAltText = altText ?? ''
   const imgWidth = widthOnly ?? width
   const imgHeight = height ?? 'auto'
   // Workaround Starlight `auto` height default style.
@@ -535,7 +543,7 @@ function handleImagesWithSize(node: Image, context: VisitorContext, type: 'asset
   if (type === 'external') {
     replaceNode(context, {
       type: 'html',
-      value: `<img src="${node.url}" alt="${altText}" width="${imgWidth}" height="${imgHeight}"${imgStyle} />`,
+      value: `<img src="${node.url}" alt="${imgAltText}" width="${imgWidth}" height="${imgHeight}"${imgStyle} />`,
     })
   } else {
     const importId = generateAssetImportId()
@@ -549,7 +557,7 @@ function handleImagesWithSize(node: Image, context: VisitorContext, type: 'asset
     replaceNode(
       context,
       createMdxNode(
-        `<Image src={${importId}} alt="${altText}" width="${imgWidth}" height="${imgHeight}"${imgStyle} />`,
+        `<Image src={${importId}} alt="${imgAltText}" width="${imgWidth}" height="${imgHeight}"${imgStyle} />`,
       ),
     )
   }
@@ -634,6 +642,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.1",
   "license": "MIT",
   "description": "Starlight plugin to publish Obsidian vaults.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",