starlight-obsidian 0.1.1

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,36 @@
+<div align="center">
+  <h1>starlight-obsidian 📔</h1>
+  <p>Starlight plugin to publish Obsidian vaults.</p>
+</div>
+
+<div align="center">
+  <a href="https://github.com/HiDeoo/starlight-obsidian/actions/workflows/integration.yml">
+    <img alt="Integration Status" src="https://github.com/HiDeoo/starlight-obsidian/actions/workflows/integration.yml/badge.svg" />
+  </a>
+  <a href="https://github.com/HiDeoo/starlight-obsidian/blob/main/LICENSE">
+    <img alt="License" src="https://badgen.net/github/license/HiDeoo/starlight-obsidian" />
+  </a>
+  <br />
+</div>
+
+## Getting Started
+
+Want to get started immediately? Check out the [getting started guide](https://starlight-obsidian.vercel.app/getting-started/).
+
+## Features
+
+A [Starlight](https://starlight.astro.build) plugin to publish [Obsidian](https://obsidian.md) vaults to a Starlight website.
+
+Check out the [demo](https://starlight-obsidian.vercel.app/demo/hello/) for a preview of the generated pages.
+
+> **Warning**
+>
+> The Starlight Obsidian plugin is in early development. If you find something that's not working, [open an issue](https://github.com/HiDeoo/starlight-obsidian/issues/new/choose) on GitHub.
+>
+> You should also always check that the rendered pages are correct and only include the content you want to publish before publishing your website.
+
+## License
+
+Licensed under the MIT License, Copyright © HiDeoo.
+
+See [LICENSE](https://github.com/HiDeoo/starlight-obsidian/blob/main/LICENSE) for more information.

package/components/Tags.astro

@@ -0,0 +1,36 @@
+---
+interface Props {
+  tags: string[]
+}
+
+const { tags } = Astro.props
+---
+
+<div>
+  <ul>
+    {
+      tags.map((tag) => (
+        <li>
+          <span class="sl-obs-tag">{tag}</span>
+        </li>
+      ))
+    }
+  </ul>
+</div>
+
+<style>
+  ul {
+    display: inline;
+    padding: 0;
+  }
+
+  li {
+    display: inline-block;
+  }
+
+  li .sl-obs-tag {
+    margin-inline-end: 0.375rem;
+    margin-bottom: 0.25rem;
+    overflow-wrap: anywhere;
+  }
+</style>

package/components/Twitter.astro

@@ -0,0 +1,11 @@
+---
+import { Tweet } from '@astro-community/astro-embed-twitter'
+
+interface Props {
+  id: string
+}
+
+const { id } = Astro.props
+---
+
+<Tweet {id} />

package/components/Youtube.astro

@@ -0,0 +1,11 @@
+---
+import { YouTube } from '@astro-community/astro-embed-youtube'
+
+interface Props {
+  id: string
+}
+
+const { id } = Astro.props
+---
+
+<YouTube {id} />

package/index.ts

@@ -0,0 +1,125 @@
+import type { StarlightPlugin, StarlightUserConfig } from '@astrojs/starlight/types'
+import { z } from 'astro/zod'
+
+import { starlightObsidianIntegration } from './libs/integration'
+import { getObsidianPaths, getVault } from './libs/obsidian'
+import { throwUserError } from './libs/plugin'
+import { addObsidianFiles, getSidebarFromConfig, getSidebarGroupPlaceholder } from './libs/starlight'
+
+const starlightObsidianConfigSchema = z.object({
+  /**
+   * The name of the Obsidian vault configuration folder if different from the default one.
+   *
+   * @default '.obsidian'
+   * @see https://help.obsidian.md/Files+and+folders/Configuration+folder
+   */
+  configFolder: z.string().startsWith('.').default('.obsidian'),
+  /**
+   * A list of glob patterns to ignore when generating the Obsidian vault pages.
+   * This option can be used to ignore files or folders.
+   *
+   * @default []
+   * @see https://github.com/mrmlnc/fast-glob#basic-syntax
+   * @see https://help.obsidian.md/Files+and+folders/Accepted+file+formats
+   */
+  ignore: z.array(z.string()).default([]),
+  /**
+   * The name of the output directory containing the generated Obsidian vault pages relative to the `src/content/docs/`
+   * directory.
+   *
+   * @default 'notes'
+   */
+  output: z.string().default('notes'),
+  /**
+   * The generated vault pages sidebar group configuration.
+   */
+  sidebar: z
+    .object({
+      /**
+       * Whether the generated vault pages root sidebar group should be collapsed by default.
+       *
+       * @default false
+       */
+      collapsed: z.boolean().default(false),
+      /**
+       * Whether the sidebar groups of your vault nested folders should be collapsed by default.
+       *
+       * Defaults to the value of the `collapsed` option.
+       */
+      collapsedFolders: z.boolean().optional(),
+      /**
+       * The generated vault pages sidebar group label.
+       *
+       * @default 'Notes'
+       */
+      label: z.string().default('Notes'),
+    })
+    .default({}),
+  /**
+   * The absolute or relative path to the Obsidian vault to publish.
+   */
+  vault: z.string(),
+})
+
+export const obsidianSidebarGroup = getSidebarGroupPlaceholder()
+
+export default function starlightObsidianPlugin(userConfig: StarlightObsidianUserConfig): StarlightPlugin {
+  const parsedConfig = starlightObsidianConfigSchema.safeParse(userConfig)
+
+  if (!parsedConfig.success) {
+    throwUserError(
+      `The provided plugin configuration is invalid.\n${parsedConfig.error.issues.map((issue) => issue.message).join('\n')}`,
+    )
+  }
+
+  const config = parsedConfig.data
+
+  return {
+    name: 'starlight-obsidian-plugin',
+    hooks: {
+      async setup({ addIntegration, command, config: starlightConfig, logger, updateConfig }) {
+        if (command !== 'build' && command !== 'dev') {
+          return
+        }
+
+        const updatedStarlightConfig: Partial<StarlightUserConfig> = {
+          customCss: [...(starlightConfig.customCss ?? []), 'starlight-obsidian/styles'],
+          sidebar: getSidebarFromConfig(config, starlightConfig.sidebar),
+        }
+
+        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')
+        } else {
+          updatedStarlightConfig.components = {
+            PageTitle: 'starlight-obsidian/overrides/PageTitle.astro',
+          }
+        }
+
+        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 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.')
+        }
+
+        addIntegration(starlightObsidianIntegration())
+        updateConfig(updatedStarlightConfig)
+      },
+    },
+  }
+}
+
+export type StarlightObsidianUserConfig = z.input<typeof starlightObsidianConfigSchema>
+export type StarlightObsidianConfig = z.output<typeof starlightObsidianConfigSchema>

package/libs/fs.ts

@@ -0,0 +1,37 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+export async function isDirectory(path: string) {
+  try {
+    const stats = await fs.stat(path)
+
+    return stats.isDirectory()
+  } catch {
+    return false
+  }
+}
+
+export async function isFile(path: string) {
+  try {
+    const stats = await fs.stat(path)
+
+    return stats.isFile()
+  } catch {
+    return false
+  }
+}
+
+export function ensureDirectory(path: string) {
+  return fs.mkdir(path, { recursive: true })
+}
+
+export function removeDirectory(path: string) {
+  return fs.rm(path, { force: true, recursive: true })
+}
+
+export async function copyFile(sourcePath: string, destinationPath: string) {
+  const dirPath = path.dirname(destinationPath)
+
+  await ensureDirectory(dirPath)
+  return fs.copyFile(sourcePath, destinationPath)
+}

package/libs/html.ts

@@ -0,0 +1,18 @@
+import { rehype } from 'rehype'
+import rehypeMermaid from 'rehype-mermaid'
+
+const processor = rehype()
+  .data('settings', {
+    fragment: true,
+    closeSelfClosing: true,
+  })
+  .use(rehypeMermaid, {
+    dark: true,
+    strategy: 'img-svg',
+  })
+
+export async function transformHtmlToString(html: string) {
+  const file = await processor.process(html)
+
+  return String(file)
+}

package/libs/integration.ts

@@ -0,0 +1,21 @@
+import type { AstroIntegration } from 'astro'
+import rehypeKatex from 'rehype-katex'
+import remarkMath from 'remark-math'
+
+import { rehypeStarlightObsidian } from './rehype'
+
+export function starlightObsidianIntegration(): AstroIntegration {
+  return {
+    name: 'starlight-obsidian-integration',
+    hooks: {
+      'astro:config:setup': ({ updateConfig }) => {
+        updateConfig({
+          markdown: {
+            rehypePlugins: [rehypeStarlightObsidian, rehypeKatex],
+            remarkPlugins: [remarkMath],
+          },
+        })
+      },
+    },
+  }
+}

package/libs/markdown.ts

@@ -0,0 +1,43 @@
+import { remark } from 'remark'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkGfm from 'remark-gfm'
+import remarkMath from 'remark-math'
+import { VFile } from 'vfile'
+
+import { remarkStarlightObsidian, type TransformContext } from './remark'
+
+const processor = remark().use(remarkGfm).use(remarkMath).use(remarkFrontmatter).use(remarkStarlightObsidian)
+
+export async function transformMarkdownToString(
+  filePath: string,
+  markdown: string,
+  context: TransformContext,
+): Promise<TransformResult> {
+  const file = await processor.process(getVFile(filePath, markdown, context))
+
+  return {
+    aliases: file.data.aliases,
+    content: String(file),
+    skip: file.data.skip === true,
+    type: file.data.isMdx === true ? 'mdx' : 'markdown',
+  }
+}
+
+export function transformMarkdownToAST(filePath: string, markdown: string, context: TransformContext) {
+  return processor.parse(getVFile(filePath, markdown, context))
+}
+
+function getVFile(filePath: string, markdown: string, context: TransformContext) {
+  return new VFile({
+    data: { ...context },
+    path: filePath,
+    value: markdown,
+  })
+}
+
+interface TransformResult {
+  aliases: string[] | undefined
+  content: string
+  skip: boolean
+  type: 'markdown' | 'mdx'
+}

package/libs/obsidian.ts

@@ -0,0 +1,225 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { z } from 'astro/zod'
+import { slug } from 'github-slugger'
+import { globby } from 'globby'
+import yaml from 'yaml'
+
+import type { StarlightObsidianConfig } from '..'
+
+import { isDirectory, isFile } from './fs'
+import { getExtension, isAnchor, slugifyPath, stripExtension } from './path'
+import { throwUserError } from './plugin'
+import { isAssetFile } from './starlight'
+
+const obsidianAppConfigSchema = z.object({
+  newLinkFormat: z.union([z.literal('absolute'), z.literal('relative'), z.literal('shortest')]).default('shortest'),
+  useMarkdownLinks: z.boolean().default(false),
+})
+
+const obsidianFrontmatterSchema = z.object({
+  aliases: z
+    .array(z.string())
+    .optional()
+    .transform((aliases) => aliases?.map((alias) => slug(alias))),
+  cover: z.string().optional(),
+  description: z.string().optional(),
+  image: z.string().optional(),
+  permalink: z.string().optional(),
+  publish: z
+    .union([z.boolean(), z.literal('true'), z.literal('false')])
+    .optional()
+    .transform((publish) => publish === undefined || publish === 'true' || publish === true),
+  tags: z.array(z.string()).optional(),
+})
+
+const imageFileFormats = new Set(['.avif', '.bmp', '.gif', '.jpeg', '.jpg', '.png', '.svg', '.webp'])
+const audioFileFormats = new Set(['.flac', '.m4a', '.mp3', '.wav', '.ogg', '.wav', '.3gp'])
+const videoFileFormats = new Set(['.mkv', '.mov', '.mp4', '.ogv', '.webm'])
+const otherFileFormats = new Set(['.pdf'])
+
+const fileFormats = new Set([...imageFileFormats, ...audioFileFormats, ...videoFileFormats, ...otherFileFormats])
+
+export async function getVault(config: StarlightObsidianConfig): Promise<Vault> {
+  const vaultPath = path.resolve(config.vault)
+
+  if (!(await isDirectory(vaultPath))) {
+    throwUserError('The provided vault path is not a directory.')
+  }
+
+  if (!(await isVaultDirectory(config, vaultPath))) {
+    throwUserError('The provided vault path is not a valid Obsidian vault directory.')
+  }
+
+  const options = await getVaultOptions(config, vaultPath)
+
+  return {
+    options,
+    path: vaultPath,
+  }
+}
+
+export function getObsidianPaths(vault: Vault, ignore: StarlightObsidianConfig['ignore'] = []) {
+  return globby(['**/*.md', ...[...fileFormats].map((fileFormat) => `**/*${fileFormat}`)], {
+    absolute: true,
+    cwd: vault.path,
+    ignore,
+  })
+}
+
+export function getObsidianVaultFiles(vault: Vault, obsidianPaths: string[]): VaultFile[] {
+  const allFileNames = obsidianPaths.map((obsidianPath) => path.basename(obsidianPath))
+
+  return obsidianPaths.map((obsidianPath, index) => {
+    const baseFileName = allFileNames[index] as string
+    let fileName = baseFileName
+
+    const type = isAssetFile(fileName) ? 'asset' : isObsidianFile(fileName) ? 'file' : 'content'
+
+    if (type === 'asset') {
+      fileName = slugifyPath(fileName)
+    }
+
+    const filePath = getObsidianRelativePath(vault, obsidianPath)
+    const slug = slugifyObsidianPath(filePath)
+
+    return createVaultFile({
+      fileName,
+      fsPath: obsidianPath,
+      path: type === 'asset' ? slug : filePath,
+      slug,
+      stem: stripExtension(fileName),
+      type,
+      uniqueFileName: allFileNames.filter((currentFileName) => currentFileName === baseFileName).length === 1,
+    })
+  })
+}
+
+export function getObsidianRelativePath(vault: Vault, obsidianPath: string) {
+  return obsidianPath.replace(vault.path, '')
+}
+
+export function slugifyObsidianPath(obsidianPath: string) {
+  const segments = obsidianPath.split('/')
+
+  return segments
+    .map((segment, index) => {
+      const isLastSegment = index === segments.length - 1
+
+      if (!isLastSegment) {
+        return slug(decodeURIComponent(segment))
+      } else if (isObsidianFile(segment) && !isAssetFile(segment)) {
+        return decodeURIComponent(segment)
+      } else if (isAssetFile(segment)) {
+        return `${slug(decodeURIComponent(stripExtension(segment)))}${getExtension(segment)}`
+      }
+
+      return slug(decodeURIComponent(stripExtension(segment)))
+    })
+    .join('/')
+}
+
+export function slugifyObsidianAnchor(obsidianAnchor: string) {
+  if (obsidianAnchor.length === 0) {
+    return ''
+  }
+
+  let anchor = isAnchor(obsidianAnchor) ? obsidianAnchor.slice(1) : obsidianAnchor
+
+  if (isObsidianBlockAnchor(anchor)) {
+    anchor = anchor.replace('^', 'block-')
+  }
+
+  return `#${slug(decodeURIComponent(anchor))}`
+}
+
+export function isObsidianBlockAnchor(anchor: string) {
+  return anchor.startsWith('#^') || anchor.startsWith('^')
+}
+
+export function isObsidianFile(filePath: string, type?: 'image' | 'audio' | 'video' | 'other') {
+  const formats: Set<string> =
+    type === undefined
+      ? fileFormats
+      : type === 'image'
+        ? imageFileFormats
+        : type === 'audio'
+          ? audioFileFormats
+          : type === 'video'
+            ? videoFileFormats
+            : otherFileFormats
+
+  return formats.has(getExtension(filePath))
+}
+
+export function parseObsidianFrontmatter(content: string): ObsidianFrontmatter | undefined {
+  try {
+    return obsidianFrontmatterSchema.parse(yaml.parse(content))
+  } catch {
+    return
+  }
+}
+
+export function createVaultFile(baseVaultFile: BaseVaultFile) {
+  return {
+    ...baseVaultFile,
+    isEqualFileName(otherFileName: string) {
+      return (isAssetFile(otherFileName) ? slugifyPath(otherFileName) : otherFileName) === this.fileName
+    },
+    isEqualStem(otherStem: string) {
+      return (isAssetFile(otherStem) ? slugifyPath(otherStem) : otherStem) === this.stem
+    },
+  }
+}
+
+async function isVaultDirectory(config: StarlightObsidianConfig, vaultPath: string) {
+  const configPath = path.join(vaultPath, config.configFolder)
+
+  return (await isDirectory(configPath)) && (await isFile(path.join(configPath, 'app.json')))
+}
+
+async function getVaultOptions(config: StarlightObsidianConfig, vaultPath: string): Promise<VaultOptions> {
+  const appConfigPath = path.join(vaultPath, config.configFolder, 'app.json')
+
+  try {
+    const appConfigData = await fs.readFile(appConfigPath, 'utf8')
+    const appConfig = obsidianAppConfigSchema.parse(JSON.parse(appConfigData))
+
+    return {
+      linkFormat: appConfig.newLinkFormat,
+      linkSyntax: appConfig.useMarkdownLinks ? 'markdown' : 'wikilink',
+    }
+  } catch (error) {
+    throw new Error('Failed to read Obsidian vault app configuration.', { cause: error })
+  }
+}
+
+export interface Vault {
+  options: VaultOptions
+  path: string
+}
+
+interface VaultOptions {
+  linkFormat: 'absolute' | 'relative' | 'shortest'
+  linkSyntax: 'markdown' | 'wikilink'
+}
+
+interface BaseVaultFile {
+  fileName: string
+  fsPath: string
+  // The path is relative to the vault root.
+  path: string
+  slug: string
+  // This represent the file name without the extension.
+  stem: string
+  type: 'asset' | 'content' | 'file'
+  uniqueFileName: boolean
+}
+
+export interface VaultFile extends BaseVaultFile {
+  isEqualFileName(otherFileName: string): boolean
+  isEqualStem(otherStem: string): boolean
+}
+
+export type ObsidianFrontmatter = z.output<typeof obsidianFrontmatterSchema>

package/libs/path.ts

@@ -0,0 +1,39 @@
+import path from 'node:path'
+
+import { slug } from 'github-slugger'
+
+export function getExtension(filePath: string) {
+  return path.parse(filePath).ext
+}
+
+export function stripExtension(filePath: string) {
+  return path.parse(filePath).name
+}
+
+export function extractPathAndAnchor(filePathAndAnchor: string): [string, string | undefined] {
+  const [filePath, fileAnchor] = filePathAndAnchor.split('#', 2)
+
+  return [filePath as string, fileAnchor]
+}
+
+export function isAnchor(filePath: string): filePath is `#${string}` {
+  return filePath.startsWith('#')
+}
+
+export function slugifyPath(filePath: string) {
+  const segments = filePath.split('/')
+
+  return segments
+    .map((segment, index) => {
+      const isLastSegment = index === segments.length - 1
+
+      if (!isLastSegment) {
+        return slug(segment)
+      }
+
+      const parsedPath = path.parse(segment)
+
+      return `${slug(parsedPath.name)}${parsedPath.ext}`
+    })
+    .join('/')
+}

package/libs/plugin.ts

@@ -0,0 +1,8 @@
+import { AstroError } from 'astro/errors'
+
+export function throwUserError(message: string): never {
+  throw new AstroError(
+    message,
+    `See the error report above for more informations.\n\nIf you believe this is a bug, please file an issue at https://github.com/HiDeoo/starlight-obsidian/issues/new/choose`,
+  )
+}