cantip 0.1.0

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "cantip",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Config-driven Remix documentation site engine — ingest Obsidian/markdown vaults, build an SSR docs site. \"How (to)\" in Kyrgyz.",
+  "keywords": [
+    "documentation",
+    "docs",
+    "remix",
+    "obsidian",
+    "markdown",
+    "static-site",
+    "ssr",
+    "docs-site"
+  ],
+  "license": "MIT",
+  "author": "Sedokina",
+  "homepage": "https://github.com/Sedokina/cantip#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sedokina/cantip.git",
+    "directory": "packages/cantip"
+  },
+  "bugs": {
+    "url": "https://github.com/Sedokina/cantip/issues"
+  },
+  "bin": {
+    "cantip": "./cli.js"
+  },
+  "exports": {
+    "./config": {
+      "types": "./app/lib/config/schema.ts",
+      "default": "./dist/config.mjs"
+    },
+    "./vite": "./vite.config.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "app",
+    "scripts",
+    "dist",
+    "cli.js",
+    "vite.config.ts",
+    "components.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "prepublishOnly": "node build.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@headless-tree/core": "^1.7.0",
+    "@headless-tree/react": "^1.7.0",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@remix-run/dev": "^2.15.0",
+    "@remix-run/node": "^2.15.0",
+    "@remix-run/react": "^2.15.0",
+    "@remix-run/serve": "^2.15.0",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tailwindcss/vite": "^4.3.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "decode-uri-component": "^0.4.1",
+    "github-slugger": "^2.0.0",
+    "globby": "^16.2.0",
+    "hast-util-to-html": "^9.0.5",
+    "is-absolute-url": "^5.0.0",
+    "isbot": "^5.1.0",
+    "json-canvas-viewer": "^4.3.2",
+    "katex": "^0.16.11",
+    "lucide-react": "^1.17.0",
+    "mdast-util-find-and-replace": "^3.0.2",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-to-hast": "^13.2.1",
+    "nanoid": "^5.1.11",
+    "pagefind": "^1.5.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-sticky-box": "^2.0.5",
+    "rehype": "^13.0.2",
+    "rehype-katex": "^7.0.1",
+    "rehype-mermaid": "^2.1.0",
+    "rehype-stringify": "^10.0.1",
+    "remark": "^15.0.1",
+    "remark-breaks": "^4.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.1",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.0",
+    "tinyglobby": "^0.2.10",
+    "tw-animate-css": "^1.4.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "vfile": "^6.0.3",
+    "vite": "^5.4.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.1",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/build-search-index.ts

@@ -0,0 +1,129 @@
+import type { CompiledDoc } from './compile.ts'
+
+/**
+ * Build a Pagefind search index from the compiled docs and write it to
+ * `public/pagefind/` so it ships as a static asset served at `/pagefind/`.
+ *
+ * The app is SSR with no static HTML on disk (content lives as HTML strings in
+ * the per-doc manifest), so Pagefind's directory-crawling mode has nothing to
+ * index. Instead we feed each doc's stored HTML to the Node Indexing API via
+ * `addHTMLFile`, which lets Pagefind extract headings, excerpts and apply its
+ * heading-weighted ranking — far richer results than indexing plain text.
+ *
+ * `writeFiles` emits the whole Pagefind runtime here too: `pagefind.js` (search
+ * API) plus `pagefind-ui.js` / `pagefind-ui.css` (the prebuilt UI used in the
+ * top/bottom bars).
+ */
+export interface SearchIndexOptions {
+	/** Absolute output dir for the Pagefind index, e.g. `<cwd>/public/pagefind`. */
+	outputPath: string
+	/** Site language for Pagefind tokenisation/stemming (`forceLanguage`). */
+	lang: string
+}
+
+export async function buildSearchIndex(
+	docs: CompiledDoc[],
+	canonicalUrl: Map<string, string>,
+	logger: { info(m: string): void; warn(m: string): void },
+	options: SearchIndexOptions = { outputPath: 'public/pagefind', lang: 'ru' },
+): Promise<void> {
+	// Imported lazily so a missing/optional native binary only fails the search
+	// step, not the whole content generation.
+	const { createIndex } = await import('pagefind')
+
+	const { index, errors } = await createIndex({
+		// Set the default site language so tokenisation and stemming are correct.
+		// Pagefind still detects per-page `lang` if present.
+		forceLanguage: options.lang,
+	})
+	if (!index) {
+		logger.warn(`Pagefind index could not be created: ${errors.join('; ')}`)
+		return
+	}
+
+	let indexed = 0
+	let skipped = 0
+	for (const doc of docs) {
+		// Drafts are not routable; canvas pages have no prose (their "HTML" is a
+		// JSON blob in a <script> mount) — nothing useful to search.
+		if (doc.frontmatter.draft === true) {
+			skipped++
+			continue
+		}
+		if (doc.html.includes('data-canvas-mount')) {
+			skipped++
+			continue
+		}
+
+		const title =
+			(doc.frontmatter.title as string | undefined) ??
+			doc.id.split('/').pop()?.replace(/-/g, ' ') ??
+			doc.id
+
+		// Canonical URL: the doc's permalink when it has one, else its file-path
+		// URL `/{id}/`. Indexing the canonical URL means a clicked search result
+		// lands on the permalink directly (no file-path → permalink 301).
+		const url = canonicalUrl.get(doc.id) ?? `/${doc.id}/`
+
+		// Directory filters, derived from the slugified id (already matches URLs).
+		// `project` is the top-level dir (e.g. "krista") used to default-scope the
+		// search to the project the reader is currently in. `dir` is tagged with
+		// EVERY ancestor directory prefix of the page, so a filter on any directory
+		// — at any nesting depth — matches every page beneath it (WebStorm's
+		// "search in directory" behaviour). e.g. "krista/требования/заказы/x" is
+		// tagged dir: ["krista", "krista/требования", "krista/требования/заказы"].
+		//
+		// The Node API's addHTMLFile takes filters only via in-content HTML
+		// attributes (data-pagefind-filter), not a `filters` field — so we emit
+		// hidden tagging elements. Repeating the `dir` filter on several elements
+		// records it as a multi-value filter (one value per ancestor directory).
+		const segments = doc.id.split('/')
+		const project = segments[0]
+		const dirSegments = segments.slice(0, -1) // drop the file slug itself
+		const dirPrefixes = dirSegments.map((_, i) => dirSegments.slice(0, i + 1).join('/'))
+		const filterTags =
+			`<span data-pagefind-filter="project" style="display:none">${escapeHtml(project)}</span>` +
+			dirPrefixes
+				.map(
+					(d) =>
+						`<span data-pagefind-filter="dir" style="display:none">${escapeHtml(d)}</span>`,
+				)
+				.join('')
+
+		// Wrap the body so Pagefind sees a full document with a heading it can use
+		// as the result title; `data-pagefind-body` scopes indexing to this region.
+		const content = `<!DOCTYPE html><html lang="${escapeHtml(options.lang)}"><head><title>${escapeHtml(
+			title,
+		)}</title></head><body><main data-pagefind-body>${filterTags}<h1>${escapeHtml(
+			title,
+		)}</h1>${doc.html}</main></body></html>`
+
+		const { errors: fileErrors } = await index.addHTMLFile({
+			url,
+			content,
+		})
+		if (fileErrors.length) {
+			logger.warn(`Pagefind failed on ${doc.id}: ${fileErrors.join('; ')}`)
+			continue
+		}
+		indexed++
+	}
+
+	const { errors: writeErrors } = await index.writeFiles({
+		outputPath: options.outputPath,
+	})
+	if (writeErrors.length) {
+		logger.warn(`Pagefind writeFiles errors: ${writeErrors.join('; ')}`)
+	}
+
+	await index.deleteIndex()
+	logger.info(`Pagefind: indexed ${indexed} pages (skipped ${skipped}) → ${options.outputPath}`)
+}
+
+function escapeHtml(s: string): string {
+	return s
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+}

package/scripts/canonical.ts

@@ -0,0 +1,34 @@
+import type { CompiledDoc } from './compile.ts'
+
+/**
+ * Canonical-URL resolution shared by every place that emits a link to a doc
+ * (in-content wikilinks, the sidebar, the search index). A doc's canonical URL
+ * is its `permalink` (project-scoped, set in frontmatter) when it has one, else
+ * its file-path URL `/{id}/`. Linking to the canonical URL means internal links
+ * skip the file-path → permalink 301 redirect.
+ */
+
+/** Project a doc belongs to: its first id segment (mirrors getProjectIdForDoc). */
+function projectOf(id: string): string {
+	return id.split('/')[0] ?? ''
+}
+
+/**
+ * Map every doc id to its canonical URL. Docs with a `permalink` frontmatter
+ * field get the project-scoped permalink URL; all others map to `/{id}/`.
+ */
+export function buildIdToCanonicalUrl(docs: CompiledDoc[]): Map<string, string> {
+	const map = new Map<string, string>()
+	for (const d of docs) {
+		const raw = d.frontmatter.permalink
+		if (typeof raw === 'string' && raw.trim() !== '') {
+			const rel = raw.trim().replace(/^\/+|\/+$/g, '')
+			if (rel) {
+				map.set(d.id, `/${projectOf(d.id)}/${rel}/`)
+				continue
+			}
+		}
+		map.set(d.id, `/${d.id}/`)
+	}
+	return map
+}

package/scripts/canvas-to-md.ts

@@ -0,0 +1,73 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { glob } from 'tinyglobby';
+
+import type { Logger } from './obsidian/logger.ts';
+
+export interface CanvasToMdOptions {
+	/** Absolute or cwd-relative path to the Obsidian vault. */
+	vault: string;
+	/** Output section name (e.g. 'krista'); files are written under `content/<output>`. */
+	output: string;
+	/** Directory that `content/<output>` lives under. Defaults to 'content'. */
+	contentRoot?: string;
+}
+
+function escapeYamlString(s: string): string {
+	if (/[:"'#\[\]{}&*!|>%@`]/.test(s) || s.includes('\n')) {
+		return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+	}
+	return s;
+}
+
+async function generateCanvasFile(
+	vaultDir: string,
+	outDir: string,
+	relPath: string,
+	log: (msg: string) => void,
+): Promise<void> {
+	const absPath = path.join(vaultDir, relPath);
+	const contents = await fs.readFile(absPath, 'utf-8');
+
+	let canvasObj: unknown;
+	try {
+		canvasObj = JSON.parse(contents);
+	} catch (err) {
+		log(`Invalid JSON in ${relPath}: ${(err as Error).message}`);
+		return;
+	}
+
+	const title = path.basename(relPath, '.canvas');
+	const safeJson = JSON.stringify(canvasObj).replace(/</g, '\\u003c');
+
+	const md = [
+		'---',
+		`title: ${escapeYamlString(title)}`,
+		'tableOfContents: false',
+		'---',
+		'',
+		`<div class="canvas-container not-content" data-canvas-mount><script type="application/json">${safeJson}</script></div>`,
+		'',
+	].join('\n');
+
+	const mdRelPath = relPath.replace(/\.canvas$/, '.md');
+	const outPath = path.join(outDir, mdRelPath);
+	await fs.mkdir(path.dirname(outPath), { recursive: true });
+	await fs.writeFile(outPath, md, 'utf-8');
+}
+
+/**
+ * Convert every `.canvas` file in a vault to a markdown page containing a
+ * client-mountable canvas container. Plain Node — no Astro integration hooks.
+ */
+export async function generateCanvas(options: CanvasToMdOptions, logger: Logger): Promise<void> {
+	const { vault, output, contentRoot = 'content' } = options;
+	const vaultDir = path.resolve(vault);
+	const outDir = path.resolve(contentRoot, output);
+
+	const entries = await glob('**/[^_]*.canvas', { cwd: vaultDir });
+	await Promise.all(entries.map((relPath) => generateCanvasFile(vaultDir, outDir, relPath, (m) => logger.info(m))));
+	if (entries.length > 0) {
+		logger.info(`Generated ${entries.length} canvas page(s) for '${output}'`);
+	}
+}

package/scripts/compile.ts

@@ -0,0 +1,242 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkGfm from 'remark-gfm'
+import remarkBreaks from 'remark-breaks'
+import remarkMath from 'remark-math'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkRehype from 'remark-rehype'
+import rehypeKatex from 'rehype-katex'
+import rehypeStringify from 'rehype-stringify'
+import { visit } from 'unist-util-visit'
+import { slug as slugify } from 'github-slugger'
+import yaml from 'yaml'
+import { slugifyObsidianPath } from './obsidian/obsidian.ts'
+import type { Root as MdastRoot } from 'mdast'
+import type { Root as HastRoot, Element } from 'hast'
+
+export interface Heading {
+	depth: number
+	slug: string
+	text: string
+}
+
+export interface CompiledDoc {
+	/** Route id, e.g. "krista/глоссарий/коллекция" (no leading slash, no extension). */
+	id: string
+	frontmatter: Record<string, unknown>
+	headings: Heading[]
+	html: string
+}
+
+function extractFrontmatter(tree: MdastRoot): Record<string, unknown> {
+	for (const node of tree.children) {
+		if (node.type === 'yaml') {
+			try {
+				const parsed = yaml.parse((node as { value: string }).value)
+				return parsed && typeof parsed === 'object' ? parsed : {}
+			} catch {
+				return {}
+			}
+		}
+	}
+	return {}
+}
+
+function nodeText(node: Element): string {
+	let out = ''
+	visit(node, 'text', (t: { value: string }) => {
+		out += t.value
+	})
+	return out
+}
+
+/**
+ * rehype plugin: assign slug ids to headings (matching Astro/github-slugger
+ * behaviour) and collect them into `file.data.headings` for the TOC.
+ */
+function rehypeHeadings() {
+	return (tree: HastRoot, file: { data: Record<string, unknown> }) => {
+		const headings: Heading[] = []
+		const seen = new Map<string, number>()
+		visit(tree, 'element', (node: Element) => {
+			const m = /^h([1-6])$/.exec(node.tagName)
+			if (!m) return
+			const depth = Number(m[1])
+			const text = nodeText(node).trim()
+			let id = slugify(text)
+			// de-duplicate ids the way github-slugger does within a doc
+			if (seen.has(id)) {
+				const n = seen.get(id)! + 1
+				seen.set(id, n)
+				id = `${id}-${n}`
+			} else {
+				seen.set(id, 0)
+			}
+			node.properties = node.properties ?? {}
+			if (!node.properties.id) node.properties.id = id
+			headings.push({ depth, slug: String(node.properties.id), text })
+		})
+		file.data.headings = headings
+	}
+}
+
+/**
+ * rehype plugin: hoist `has-blank-before` from a `<code>` up to its `<pre>`.
+ *
+ * `remarkBlankLineGaps` attaches the class via mdast `hProperties`, which for a
+ * fenced code block lands on the inner `<code>` element — but the block-level
+ * box (and the `margin-block: 0` reset it must override) lives on the wrapping
+ * `<pre>`. A class on `<code>` therefore produces no gap. Move it to the `<pre>`
+ * so the marker sits on the element CSS actually keys the gap on.
+ */
+function rehypeHoistBlankBeforeToPre() {
+	return (tree: HastRoot) => {
+		visit(tree, 'element', (node: Element) => {
+			if (node.tagName !== 'pre') return
+			const code = node.children.find(
+				(c): c is Element => c.type === 'element' && c.tagName === 'code',
+			)
+			if (!code) return
+			const codeCls = code.properties?.className
+			if (!Array.isArray(codeCls) || !codeCls.includes('has-blank-before')) return
+			// Drop the marker from <code> and add it to <pre>.
+			const remaining = codeCls.filter((c) => c !== 'has-blank-before')
+			if (remaining.length > 0) code.properties!.className = remaining
+			else delete code.properties!.className
+			node.properties = node.properties ?? {}
+			const preCls = node.properties.className
+			node.properties.className = Array.isArray(preCls)
+				? [...preCls, 'has-blank-before']
+				: ['has-blank-before']
+		})
+	}
+}
+
+/**
+ * remark plugin: attach `.has-blank-before` to every block the author separated
+ * from its previous sibling with a blank line. Blank-line separation is the only
+ * thing that earns a vertical gap; the gap itself lives entirely in CSS, keyed on
+ * `.has-blank-before`.
+ *
+ * This plugin does NOT read source positions — it can't. The obsidian generator
+ * round-trips the document through remark-stringify, which renormalises
+ * blank-line spacing throughout (it drifts in 86% of files), so positions on the
+ * markdown we compile here no longer reflect what the author wrote. Instead the
+ * generator records the author's gaps at the source — where positions are
+ * pristine — by inserting a `<!--blank-gap-->` comment (see BLANK_GAP_MARKER in
+ * `scripts/obsidian/remark.ts`) before each gapped block. Here we simply honour
+ * those markers: the block following a marker gets the class, and the marker is
+ * stripped so it never reaches the HTML. Markers before raw `html` blocks aren't
+ * emitted (callouts/canvas bring their own margins), so none are read for them.
+ *
+ * The class is attached through mdast `data.hProperties.className` so that
+ * remark-rehype renders it onto the resulting element.
+ */
+const BLANK_GAP_MARKER = '<!--blank-gap-->'
+
+function remarkBlankLineGaps() {
+	type Parent = { children?: BlockNode[] }
+	type BlockNode = {
+		type: string
+		value?: string
+		data?: { hProperties?: { className?: string[] } }
+		children?: BlockNode[]
+	}
+	const isGapMarker = (n: BlockNode | undefined) =>
+		n?.type === 'html' && n.value?.trim() === BLANK_GAP_MARKER
+	function walk(parent: Parent) {
+		const children = parent.children
+		if (!children) return
+		// Strip gap markers, remembering which block each preceded so we can tag it
+		// without leaving the comment behind. Iterate backwards so splices are safe.
+		const gapped = new Set<BlockNode>()
+		for (let i = children.length - 1; i >= 0; i--) {
+			if (isGapMarker(children[i])) {
+				const next = children[i + 1]
+				if (next) gapped.add(next)
+				children.splice(i, 1)
+			}
+		}
+		for (const node of children) {
+			if (gapped.has(node)) {
+				node.data ??= {}
+				node.data.hProperties ??= {}
+				const cls = node.data.hProperties.className ?? []
+				cls.push('has-blank-before')
+				node.data.hProperties.className = cls
+			}
+			walk(node)
+		}
+	}
+	return (tree: MdastRoot) => {
+		walk(tree as unknown as Parent)
+	}
+}
+
+const processor = unified()
+	.use(remarkParse)
+	.use(remarkFrontmatter)
+	.use(remarkGfm)
+	// Obsidian renders a single newline as a line break (a "hard break"); the
+	// vault was authored against that behaviour (e.g. multi-line blockquotes
+	// without trailing spaces). Default CommonMark collapses single newlines to
+	// spaces — remark-breaks restores the Obsidian/GitHub line-break semantics.
+	.use(remarkBreaks)
+	// Mark blocks preceded by a blank line so CSS can apply the inter-block gap
+	// ONLY there (see `.has-blank-before` in app.css), instead of a blanket
+	// adjacent-sibling margin. Must run BEFORE remarkRehype (needs mdast
+	// positions) and after remarkBreaks (which doesn't add/remove blocks).
+	.use(remarkBlankLineGaps)
+	.use(remarkMath, { singleDollarTextMath: true })
+	// allowDangerousHtml: the generated markdown contains raw HTML (callouts,
+	// <img>, canvas containers) produced by the obsidian remark pipeline.
+	.use(remarkRehype, { allowDangerousHtml: true })
+	.use(rehypeKatex)
+	// remarkBlankLineGaps puts the gap marker on the inner <code>; move it up to
+	// the <pre> so the inter-block gap actually applies (see plugin doc above).
+	.use(rehypeHoistBlankBeforeToPre)
+	.use(rehypeHeadings)
+	.use(rehypeStringify, { allowDangerousHtml: true })
+
+/** Compile a single markdown string to HTML + headings + frontmatter. */
+export async function compileMarkdown(markdown: string): Promise<Omit<CompiledDoc, 'id'>> {
+	const mdast = processor.parse(markdown) as MdastRoot
+	const frontmatter = extractFrontmatter(mdast)
+	const file = await processor.process(markdown)
+	return {
+		frontmatter,
+		headings: (file.data.headings as Heading[]) ?? [],
+		html: String(file),
+	}
+}
+
+/** Walk a content directory and compile every .md file into the manifest. */
+export async function compileDir(contentRoot: string, logger: { info(m: string): void }): Promise<CompiledDoc[]> {
+	const docs: CompiledDoc[] = []
+
+	async function walk(dir: string): Promise<void> {
+		const entries = await fs.readdir(dir, { withFileTypes: true })
+		await Promise.all(
+			entries.map(async (entry) => {
+				const full = path.join(dir, entry.name)
+				if (entry.isDirectory()) {
+					await walk(full)
+				} else if (entry.isFile() && entry.name.endsWith('.md')) {
+					const raw = await fs.readFile(full, 'utf8')
+					const compiled = await compileMarkdown(raw)
+					const rel = path.relative(contentRoot, full).replace(/\\/g, '/').replace(/\.md$/, '')
+					// Slugify the id with the same logic used to generate internal link
+					// hrefs (lowercase, slugified per segment) so routes match wikilinks.
+					const id = slugifyObsidianPath(rel)
+					docs.push({ id, ...compiled })
+				}
+			}),
+		)
+	}
+
+	await walk(contentRoot)
+	logger.info(`Compiled ${docs.length} markdown page(s) to HTML.`)
+	return docs
+}