cantip 0.1.0

package/scripts/emit-config.ts

@@ -0,0 +1,163 @@
+/**
+ * Serialize the resolved config for the running app.
+ *
+ * Emits two artifacts under the manifest dir (`app/generated`):
+ * - `config.json` — the full resolved config (theme, ui, projects). Read at
+ *   runtime via `fs` in `app/lib/config/config.server.ts`. Never imported, so it
+ *   carries server-only detail (theme CSS tokens) safely.
+ * - `site.ts` — a plain-literal module (client-safe subset) IMPORTED by the app,
+ *   so Vite bundles projects/branding/ui strings into both client and server.
+ *   This is what lets client components read projects synchronously.
+ *
+ * Per-project `landing` is defaulted here (not in `loadConfig`) because it needs
+ * the compiled doc index: when a project doesn't pin a landing URL, we use the
+ * first doc under that project as its landing page.
+ */
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { DocsConfig } from '../app/lib/config/schema.ts'
+import type { GeneratedSite, SiteProject } from '../app/lib/config/site.ts'
+
+// Mirrors `GENERAL_PROJECT_ID` in app/lib/projects.ts. Inlined (not imported) so
+// this build script never pulls in the app module, which imports the Vite-only
+// `~/generated/site` alias that doesn't resolve under the plain-Node runner.
+const GENERAL_PROJECT_ID = 'general'
+
+interface IndexEntry {
+	id: string
+}
+
+interface EmitArgs {
+	config: DocsConfig
+	manifestDir: string
+	/** The doc index (already sorted), used to derive default landing URLs. */
+	index: IndexEntry[]
+	logger: { info(m: string): void }
+}
+
+/** The overridable slot names, in the order they appear in the generated module. */
+const SLOT_NAMES = ['Home', 'DocPage', 'TopBar', 'Toc'] as const
+
+/**
+ * Render the generated `slots.ts`: import each configured override component by a
+ * path relative to the manifest dir (so Vite resolves it from the user's
+ * project), and export every slot as the override or `null` (= engine default).
+ */
+function renderSlots(components: Record<string, string | undefined>, manifestDir: string): string {
+	const imports: string[] = []
+	const exports: string[] = []
+	for (const name of SLOT_NAMES) {
+		const src = components[name]
+		if (src) {
+			// Resolve the user's path (relative to cwd) to an import specifier
+			// relative to the manifest dir; ensure it starts with './' or '../'.
+			let rel = path.relative(manifestDir, path.resolve(process.cwd(), src)).replace(/\\/g, '/')
+			if (!rel.startsWith('.')) rel = `./${rel}`
+			imports.push(`import ${name}Override from '${rel}'`)
+			exports.push(`export const ${name} = ${name}Override`)
+		} else {
+			exports.push(`export const ${name}: ComponentType<any> | null = null`)
+		}
+	}
+	return (
+		`// AUTO-GENERATED by scripts/generate-content.ts — DO NOT EDIT.\n` +
+		`import type { ComponentType } from 'react'\n` +
+		(imports.length ? imports.join('\n') + '\n' : '') +
+		`\n` +
+		exports.join('\n') +
+		`\n`
+	)
+}
+
+/** Render the resolved theme token maps into a `:root` + `.dark` CSS block. */
+function renderThemeCss(colors: { light: Record<string, string>; dark: Record<string, string> }): string {
+	const block = (selector: string, vars: Record<string, string>) => {
+		const lines = Object.entries(vars).map(([k, v]) => `\t${k}: ${v};`)
+		return `${selector} {\n${lines.join('\n')}\n}`
+	}
+	return (
+		`/* AUTO-GENERATED by scripts/generate-content.ts from docs.config.ts theme. DO NOT EDIT. */\n` +
+		`${block(':root', colors.light)}\n\n` +
+		`${block('.dark', colors.dark)}\n`
+	)
+}
+
+/** First doc id whose project (first segment) is `projectId`, or null. */
+function firstDocOfProject(index: IndexEntry[], projectId: string): string | null {
+	for (const e of index) {
+		if ((e.id.split('/')[0] ?? '') === projectId) return e.id
+	}
+	return null
+}
+
+/** First doc id that belongs to no known project (the general bucket), or null. */
+function firstGeneralDoc(index: IndexEntry[], projectIds: Set<string>): string | null {
+	for (const e of index) {
+		if (!projectIds.has(e.id.split('/')[0] ?? '')) return e.id
+	}
+	return null
+}
+
+export async function emitGeneratedConfig({ config, manifestDir, index, logger }: EmitArgs): Promise<void> {
+	const projectIds = new Set(config.projects.map((p) => p.id))
+
+	// Resolve each project's landing URL: the authored value, else its first doc.
+	const projects: SiteProject[] = config.projects.map((p) => {
+		const first = firstDocOfProject(index, p.id)
+		const landing = p.landing ?? (first ? `/${first}/` : '/')
+		return {
+			id: p.id,
+			name: p.name,
+			logo: p.logo ?? `/projects/${p.id}.svg`,
+			landing,
+			description: p.description,
+		}
+	})
+
+	const generalHasDocs = config.general.enabled && firstGeneralDoc(index, projectIds) !== null
+	const site: GeneratedSite = {
+		site: {
+			title: config.site.title,
+			description: config.site.description,
+			lang: config.site.lang,
+			favicon: config.site.favicon,
+			logo: config.site.logo,
+			defaultTheme: config.site.defaultTheme,
+		},
+		projects,
+		general: {
+			enabled: generalHasDocs,
+			id: GENERAL_PROJECT_ID,
+			name: config.general.name,
+			logo: config.general.logo,
+			description: config.general.description,
+		},
+		ui: config.ui,
+	}
+
+	// Full config (server-only) — includes resolved landings so the server agrees
+	// with the client `site.ts` view.
+	const fullConfig = { ...config, projects: config.projects.map((p, i) => ({ ...p, landing: projects[i].landing })) }
+	await fs.writeFile(path.join(manifestDir, 'config.json'), JSON.stringify(fullConfig))
+
+	// Client-safe literals module. Pretty-printed so a human can diff it.
+	const siteModule =
+		`// AUTO-GENERATED by scripts/generate-content.ts — DO NOT EDIT.\n` +
+		`import type { GeneratedSite } from '~/lib/config/site'\n\n` +
+		`export const SITE: GeneratedSite = ${JSON.stringify(site, null, '\t')}\n`
+	await fs.writeFile(path.join(manifestDir, 'site.ts'), siteModule)
+
+	// Theme CSS: the resolved theme already has defaults merged with the user's
+	// overrides, so emit the full :root/.dark token blocks. Imported AFTER
+	// tailwind.css in root.tsx, so these win; the `--sl-*` bridge in tailwind.css
+	// (which references these vars) keeps generated markdown tracking the theme.
+	await fs.writeFile(path.join(manifestDir, 'theme.generated.css'), renderThemeCss(config.theme.colors))
+
+	// Slot overrides: rewrite the generated slots module to import any user
+	// override components (by path, resolved from the user's project) and fall the
+	// rest back to null (= engine default). See app/lib/slots.tsx.
+	await fs.writeFile(path.join(manifestDir, 'slots.ts'), renderSlots(config.components, manifestDir))
+
+	logger.info(`Emitted config.json + site.ts + theme.generated.css + slots.ts (${projects.length} project(s)${generalHasDocs ? ' + general' : ''}).`)
+}

package/scripts/generate-content.ts

@@ -0,0 +1,197 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { generateObsidian } from './obsidian/generate.ts'
+import { generateCanvas } from './canvas-to-md.ts'
+import { compileDir, type CompiledDoc } from './compile.ts'
+import { buildSearchIndex } from './build-search-index.ts'
+import { buildIdToCanonicalUrl } from './canonical.ts'
+import type { Logger } from './obsidian/logger.ts'
+import { loadConfig } from '../app/lib/config/load.ts'
+import type { DocsConfig } from '../app/lib/config/schema.ts'
+import { emitGeneratedConfig } from './emit-config.ts'
+
+const logger: Logger = {
+	info: (m) => console.log(`  ${m}`),
+	warn: (m) => console.warn(`  ⚠ ${m}`),
+	error: (m) => console.error(`  ✖ ${m}`),
+}
+
+// All build artifacts live under the USER's cwd (not inside the engine package),
+// matching the runtime contract in `app/lib/content.server.ts` + `config.server.ts`.
+const CWD = process.cwd()
+const CONTENT_ROOT = path.resolve(CWD, 'content')
+const PUBLIC_ROOT = path.resolve(CWD, 'public')
+const MANIFEST_DIR = path.resolve(CWD, 'app/generated')
+const OUTPUT_ROOTS = { content: CONTENT_ROOT, public: PUBLIC_ROOT }
+
+/**
+ * Derive the ingestion work-lists from the resolved config. Each project (and the
+ * optional `general` bucket, when it has a `source`) becomes one vault; projects
+ * flagged `canvas` additionally feed the canvas pass. `output` is the project id
+ * — the first id segment of every doc it produces — except the general bucket,
+ * whose docs sit at the root (output `.`).
+ */
+function buildWorkLists(config: DocsConfig) {
+	const vaults = config.projects.map((p) => ({ vault: p.source, output: p.id, ignore: p.ignore }))
+	const canvas = config.projects
+		.filter((p) => p.canvas)
+		.map((p) => ({ vault: p.source, output: p.id }))
+
+	if (config.general.enabled && config.general.source) {
+		// General docs live at the root: output '.' writes straight into content/.
+		vaults.push({ vault: config.general.source, output: '.', ignore: config.general.ignore })
+	}
+	return { vaults, canvas }
+}
+
+/**
+ * Rewrite internal links in every doc's HTML to canonical (permalink) URLs.
+ *
+ * Wikilink hrefs are emitted by the Obsidian pass as percent-encoded file-path
+ * URLs without a trailing slash, e.g. `/krista/%D0%B3.../%D0%BA...`. We decode
+ * each href, match it against a doc id, and if that doc's canonical URL differs
+ * from its file-path URL (i.e. it has a permalink) we swap the href in place.
+ * Any anchor (#heading) is preserved. Mutates `docs[].html`; returns the count.
+ */
+function rewriteContentLinks(docs: CompiledDoc[], canonicalUrl: Map<string, string>): number {
+	let count = 0
+	for (const d of docs) {
+		d.html = d.html.replace(/href="(\/[^"#]+)(#[^"]*)?"/g, (whole, rawPath: string, anchor?: string) => {
+			// Decode and normalize to an id (no leading/trailing slash) for lookup.
+			let decoded: string
+			try {
+				decoded = decodeURIComponent(rawPath)
+			} catch {
+				return whole // malformed escape — leave untouched
+			}
+			const id = decoded.replace(/^\/+|\/+$/g, '')
+			const canonical = canonicalUrl.get(id)
+			// Only rewrite when the target is a known doc WITH a permalink (its
+			// canonical URL differs from the default file-path form).
+			if (!canonical || canonical === `/${id}/`) return whole
+			count++
+			return `href="${canonical}${anchor ?? ''}"`
+		})
+	}
+	return count
+}
+
+async function main() {
+	const start = performance.now()
+	console.log('▶ Generating content from Obsidian vaults…')
+
+	// 0. Load the user's docs.config.ts (resolved + validated) from cwd.
+	const config = await loadConfig(CWD)
+	const { vaults, canvas } = buildWorkLists(config)
+
+	// 1. Clean previous content output (asset/public cleanup is handled per-vault).
+	await fs.rm(CONTENT_ROOT, { recursive: true, force: true })
+
+	// 2. Ingest each vault → content/<output>/*.md  (+ assets to public/<output>).
+	//    Run the general bucket (output '.') first so its root-level write lands
+	//    before project subdirs (it skips per-vault cleanup to avoid wiping them).
+	const orderedVaults = [...vaults].sort((a, b) => (a.output === '.' ? -1 : b.output === '.' ? 1 : 0))
+	for (const v of orderedVaults) {
+		await generateObsidian(v, logger, OUTPUT_ROOTS)
+	}
+
+	// 3. Convert .canvas files → content/<output>/*.md
+	for (const c of canvas) {
+		await generateCanvas({ ...c, contentRoot: CONTENT_ROOT }, logger)
+	}
+
+	// 4. Compile every markdown page → HTML + headings + frontmatter
+	const docs = await compileDir(CONTENT_ROOT, logger)
+
+	// 4b. Rewrite in-content links to canonical URLs. Wikilinks are resolved to
+	//     file-path hrefs (/{id}/) during the per-vault Obsidian pass, before the
+	//     permalink map exists. Now that every doc is compiled we know which docs
+	//     have permalinks, so we rewrite any internal href pointing at such a doc
+	//     to its permalink — internal links then skip the file-path→permalink 301.
+	const canonicalUrl = buildIdToCanonicalUrl(docs)
+	const rewrites = rewriteContentLinks(docs, canonicalUrl)
+	if (rewrites > 0) {
+		logger.info(`Rewrote ${rewrites} in-content link(s) to permalinks.`)
+	}
+
+	// 5. Emit manifest. One index file (lightweight, for the sidebar/routing) and
+	//    one HTML file per doc (loaded by the route loader on demand).
+	await fs.rm(MANIFEST_DIR, { recursive: true, force: true })
+	await fs.mkdir(path.join(MANIFEST_DIR, 'docs'), { recursive: true })
+
+	const index = docs
+		.map((d) => ({
+			id: d.id,
+			title: (d.frontmatter.title as string | undefined) ?? null,
+			draft: d.frontmatter.draft === true,
+			tableOfContents: d.frontmatter.tableOfContents !== false,
+			tags: (d.frontmatter.tags as string[] | undefined) ?? [],
+			isCanvas: d.html.includes('data-canvas-mount'),
+		}))
+		.sort((a, b) => a.id.localeCompare(b.id, config.site.lang))
+
+	await fs.writeFile(path.join(MANIFEST_DIR, 'index.json'), JSON.stringify(index))
+
+	// Permalink map: a doc may pin a stable URL via `permalink` in its Obsidian
+	// frontmatter (carried through to the generated frontmatter under the same
+	// key). This URL is independent of the file name, so renames never break it.
+	// We store
+	// permalink → id; the route loader serves the doc at the permalink and
+	// redirects the file-path URL to it (the permalink is the canonical URL).
+	//
+	// Permalinks are PROJECT-SCOPED: the key is prefixed with the doc's project
+	// (the first id segment, same rule as getProjectIdForDoc). So `permalink:
+	// /abc/123` in a krista doc is served at /krista/abc/123/, and a same-named
+	// permalink in another project (krista-partners/abc/123) never collides.
+	const permalinks: Record<string, string> = {}
+	for (const d of docs) {
+		const raw = d.frontmatter.permalink
+		if (typeof raw !== 'string' || raw.trim() === '') continue
+		const rel = raw.trim().replace(/^\/+|\/+$/g, '') // normalize: no leading/trailing slashes
+		if (!rel) continue
+		const project = d.id.split('/')[0] // doc's project = first id segment
+		const key = `${project}/${rel}`
+		if (permalinks[key] && permalinks[key] !== d.id) {
+			logger.warn(`Duplicate permalink "${raw}" in project "${project}" on ${d.id} (already used by ${permalinks[key]}); keeping the first.`)
+			continue
+		}
+		permalinks[key] = d.id
+	}
+	await fs.writeFile(path.join(MANIFEST_DIR, 'permalinks.json'), JSON.stringify(permalinks))
+	if (Object.keys(permalinks).length > 0) {
+		logger.info(`Registered ${Object.keys(permalinks).length} permalink(s).`)
+	}
+
+	// One JSON per doc, mirroring the content directory structure so individual
+	// path segments stay within the filesystem's 255-byte filename limit (the
+	// Cyrillic ids percent-encode to very long single strings otherwise).
+	await Promise.all(
+		docs.map(async (d) => {
+			const outPath = path.join(MANIFEST_DIR, 'docs', `${d.id}.json`)
+			await fs.mkdir(path.dirname(outPath), { recursive: true })
+			await fs.writeFile(
+				outPath,
+				JSON.stringify({ id: d.id, frontmatter: d.frontmatter, headings: d.headings, html: d.html }),
+			)
+		}),
+	)
+
+	// 6. Build the Pagefind search index from the compiled docs → public/pagefind
+	await buildSearchIndex(docs, canonicalUrl, logger, {
+		outputPath: path.join(PUBLIC_ROOT, 'pagefind'),
+		lang: config.site.lang,
+	})
+
+	// 7. Emit the resolved config so the running app can read it without ever
+	//    importing the user's TS config: `config.json` (full, read via fs in
+	//    .server code) + `site.ts` (client-safe literals, bundled by Vite). The
+	//    index drives per-project `landing` defaults (first doc of each project).
+	await emitGeneratedConfig({ config, manifestDir: MANIFEST_DIR, index, logger })
+
+	console.log(`✔ Done: ${docs.length} pages in ${Math.round(performance.now() - start)}ms`)
+}
+
+main().catch((err) => {
+	console.error(err)
+	process.exit(1)
+})

package/scripts/obsidian/files.ts

@@ -0,0 +1,222 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { Logger } from './logger.ts'
+
+import type { ObsidianConfig } from './types.ts'
+
+import { copyFile, ensureDirectory, removeDirectory } from './fs.ts'
+import { transformMarkdownToString } from './markdown.ts'
+import { getObsidianVaultFiles, isObsidianFile, type ObsidianFrontmatter, type Vault, type VaultFile } from './obsidian.ts'
+import { getExtension, stripLeadingAndTrailingSlashes } from './path.ts'
+
+// Output roots. Assets and non-markdown files are served statically from the
+// public dir; markdown pages live under the content dir and are compiled to HTML
+// by the content-generation script. Defaults reproduce the original layout
+// (`content/` + `public/` relative to cwd); the generator passes resolved,
+// cwd-absolute roots via `OutputRoots` so the engine also works from node_modules.
+export interface OutputRoots {
+  /** Where compiled markdown lands, e.g. `<cwd>/content`. */
+  content: string
+  /** Where assets + non-markdown files land (served statically), e.g. `<cwd>/public`. */
+  public: string
+}
+
+const DEFAULT_OUTPUT_ROOTS: OutputRoots = { content: 'content', public: 'public' }
+
+const calloutTypeMap: Record<string, string> = {
+  note: 'note',
+  abstract: 'tip',
+  summary: 'tip',
+  tldr: 'tip',
+  info: 'note',
+  todo: 'note',
+  tip: 'tip',
+  hint: 'tip',
+  important: 'tip',
+  success: 'note',
+  check: 'note',
+  done: 'note',
+  question: 'caution',
+  help: 'caution',
+  faq: 'caution',
+  warning: 'caution',
+  caution: 'caution',
+  attention: 'caution',
+  failure: 'danger',
+  fail: 'danger',
+  missing: 'danger',
+  danger: 'danger',
+  error: 'danger',
+  bug: 'danger',
+  example: 'tip',
+  quote: 'note',
+  cite: 'note',
+}
+
+export function getCalloutType(obsidianCalloutType: string): string {
+  return calloutTypeMap[obsidianCalloutType] ?? 'note'
+}
+
+export function isAssetFile(filePath: string): boolean {
+  return getExtension(filePath) !== '.bmp' && isObsidianFile(filePath, 'image')
+}
+
+export async function addObsidianFiles(
+  config: ObsidianConfig,
+  vault: Vault,
+  obsidianPaths: string[],
+  logger: Logger,
+  roots: OutputRoots = DEFAULT_OUTPUT_ROOTS,
+) {
+  const outputPaths = getOutputPaths(config, roots)
+
+  // The general/no-project bucket (output '.') writes into the content/public
+  // ROOTS, intermixed with project subdirs. Cleaning those roots here would wipe
+  // sibling projects' output, so skip per-vault cleanup for it — the orchestrator
+  // clears the content root once upfront, and general's loose assets are few.
+  if (stripLeadingAndTrailingSlashes(config.output) !== '.') {
+    await cleanOutputPaths(outputPaths)
+  }
+
+  const vaultFiles = getObsidianVaultFiles(vault, obsidianPaths)
+
+  const results = await Promise.allSettled(
+    vaultFiles.map(async (vaultFile) => {
+      await (vaultFile.type === 'asset'
+        ? addAsset(outputPaths, vaultFile)
+        : vaultFile.type === 'file'
+          ? addFile(outputPaths, vaultFile)
+          : addContent(config, vault, outputPaths, vaultFiles, vaultFile))
+    }),
+  )
+
+  let didFail = false
+
+  for (const result of results) {
+    if (result.status === 'rejected') {
+      didFail = true
+      logger.error(result.reason instanceof Error ? result.reason.message : String(result.reason))
+    }
+  }
+
+  if (didFail) {
+    throw new Error('Failed to generate some pages. See the error(s) above for more information.')
+  }
+}
+
+async function addContent(
+  config: ObsidianConfig,
+  vault: Vault,
+  outputPaths: OutputPaths,
+  vaultFiles: VaultFile[],
+  vaultFile: VaultFile,
+) {
+  try {
+    const obsidianContent = await fs.readFile(vaultFile.fsPath, 'utf8')
+    const {
+      content,
+      aliases,
+      skip,
+      type,
+    } = await transformMarkdownToString(vaultFile.fsPath, obsidianContent, {
+      files: vaultFiles,
+      copyFrontmatter: config.copyFrontmatter,
+      output: config.output,
+      singleDollarTextMath: config.math.singleDollarTextMath,
+      vault,
+    })
+
+    if (skip) {
+      return
+    }
+
+    const outputPath = path.join(
+      outputPaths.content,
+      type === 'markdown' ? vaultFile.path : vaultFile.path.replace(/\.md$/, '.mdx'),
+    )
+    const outputDirPath = path.dirname(outputPath)
+
+    await ensureDirectory(outputDirPath)
+    await fs.writeFile(outputPath, content)
+
+    if (aliases) {
+      for (const alias of aliases) {
+        await addAlias(config, outputPaths, vaultFile, alias)
+      }
+    }
+  } catch (error) {
+    throwVaultFileError(error, vaultFile)
+  }
+}
+
+async function addFile(outputPaths: OutputPaths, vaultFile: VaultFile) {
+  try {
+    await copyFile(vaultFile.fsPath, path.join(outputPaths.file, vaultFile.slug))
+  } catch (error) {
+    throwVaultFileError(error, vaultFile)
+  }
+}
+
+async function addAsset(outputPaths: OutputPaths, vaultFile: VaultFile) {
+  try {
+    await copyFile(vaultFile.fsPath, path.join(outputPaths.asset, vaultFile.slug))
+  } catch (error) {
+    throwVaultFileError(error, vaultFile)
+  }
+}
+
+async function addAlias(
+  config: ObsidianConfig,
+  outputPaths: OutputPaths,
+  vaultFile: VaultFile,
+  alias: string,
+) {
+  const htmlPath = path.join(outputPaths.file, path.dirname(vaultFile.path), alias, 'index.html')
+  const htmlDirPath = path.dirname(htmlPath)
+
+  const to = path.posix.join(path.posix.sep, config.output, vaultFile.slug)
+  const from = path.posix.join(path.dirname(to), alias)
+
+  await ensureDirectory(htmlDirPath)
+
+  await fs.writeFile(
+    htmlPath,
+    `<!doctype html>
+<html lang="en">
+  <head>
+    <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>
+</html>`,
+  )
+}
+
+function getOutputPaths(config: ObsidianConfig, roots: OutputRoots): OutputPaths {
+  return {
+    asset: path.join(roots.public, config.output),
+    content: path.join(roots.content, config.output),
+    file: path.join(roots.public, config.output),
+  }
+}
+
+async function cleanOutputPaths(outputPaths: OutputPaths) {
+  await removeDirectory(outputPaths.asset)
+  await removeDirectory(outputPaths.content)
+  await removeDirectory(outputPaths.file)
+}
+
+function throwVaultFileError(error: unknown, vaultFile: VaultFile): never {
+  throw new Error(`${vaultFile.path} — ${error instanceof Error ? error.message : String(error)}`, { cause: error })
+}
+
+interface OutputPaths {
+  asset: string
+  content: string
+  file: string
+}

package/scripts/obsidian/fs.ts

@@ -0,0 +1,34 @@
+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/scripts/obsidian/generate.ts

@@ -0,0 +1,36 @@
+import { obsidianConfigSchema, type ObsidianUserConfig } from './types.ts'
+import { getObsidianPaths, getVault } from './obsidian.ts'
+import { addObsidianFiles, type OutputRoots } from './files.ts'
+import type { Logger } from './logger.ts'
+
+/**
+ * Plain-Node replacement for the Astro `obsidian()` integration. Reads an
+ * Obsidian vault, runs the remark transform pipeline over every note, and
+ * writes the resulting markdown into `content/<output>` plus copies assets
+ * and embedded files into `public/<output>`.
+ *
+ * (The Astro version wired remark/rehype plugins into Astro's markdown config
+ *  via `updateConfig`; here the full markdown -> HTML compilation happens later
+ *  in generate-content.ts, so this step only emits the transformed markdown.)
+ */
+export async function generateObsidian(userConfig: ObsidianUserConfig, logger: Logger, roots?: OutputRoots): Promise<void> {
+	const parsed = obsidianConfigSchema.safeParse(userConfig)
+	if (!parsed.success) {
+		throw new Error(`Invalid obsidian configuration:\n\n${JSON.stringify(parsed.error.format(), null, 2)}`)
+	}
+	const config = parsed.data
+
+	if (config.skipGeneration) {
+		logger.warn(`Skipping generation for '${config.output}' (skipGeneration enabled).`)
+		return
+	}
+
+	const start = performance.now()
+	logger.info(`Generating pages from Obsidian vault '${config.vault}'…`)
+
+	const vault = await getVault(config)
+	const obsidianPaths = await getObsidianPaths(vault, config.ignore)
+	await addObsidianFiles(config, vault, obsidianPaths, logger, roots)
+
+	logger.info(`Generated '${config.output}' in ${Math.round(performance.now() - start)}ms.`)
+}

package/scripts/obsidian/html.ts

@@ -0,0 +1,17 @@
+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/scripts/obsidian/logger.ts

@@ -0,0 +1,10 @@
+/**
+ * Minimal logger interface used by the content-generation pipeline.
+ * Replaces Astro's `AstroIntegrationLogger`. Satisfied by `console` or a
+ * thin wrapper (see scripts/generate-content.ts).
+ */
+export interface Logger {
+	info(message: string): void
+	warn(message: string): void
+	error(message: string): void
+}