Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(open-knowledge): fall back to the first H1 for a doc title (#3119)
tim-inkeepfed480ad582b
diff --git a/.changeset/h1-title-fallback.md b/.changeset/h1-title-fallback.mdnew file mode 100644index 000000000..481f72bfa--- /dev/null+++ b/.changeset/h1-title-fallback.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++A document with no `title:` in its frontmatter now takes its title from the first `# heading` in the body, falling back to the path only when there is no heading either. Agent-facing listings (`exec cat`, `exec ls`, the "most recent" line on a directory) were showing raw paths for files that plainly announce their own title on line one, which is the normal shape for vaults, imported notes, and simple logs. `/api/pages` and workspace search already resolved titles this way, so this brings the enrichment surface in line with the rest of the app, down to the details: a `title:` is trimmed, and a blank or whitespace-only one now counts as no title and falls through to the heading rather than showing as an empty label.diff --git a/packages/server/src/content/enrichment.test.ts b/packages/server/src/content/enrichment.test.tsindex facf82d3d..74dcf26bb 100644--- a/packages/server/src/content/enrichment.test.ts+++ b/packages/server/src/content/enrichment.test.ts@@ -1,4 +1,4 @@-import { mkdirSync, writeFileSync } from 'node:fs';+import { mkdirSync, utimesSync, writeFileSync } from 'node:fs';import { mkdtemp, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';import { resolve } from 'node:path';@@ -70,6 +70,26 @@ describe('enrichPath — slim (multi-path) shape', () => {expect(meta.tags).toEqual([]);});+ test('falls back to the first H1 when frontmatter carries no title', async () => {+ const project = await bootstrapProject();+ const contentDir = resolve(project, 'content');+ mkdirSync(contentDir, { recursive: true });+ // No frontmatter at all — the common vault / imported-note shape.+ writeFileSync(resolve(contentDir, 'someday.md'), '# Someday / Open Loops\n\nBody\n');+ // Frontmatter present but titleless: the heading still wins over the path.+ writeFileSync(resolve(contentDir, 'loops.md'), '---\ntags:\n - inbox\n---\n\n# Open Loops\n');+ // An explicit title always outranks the heading.+ writeFileSync(resolve(contentDir, 'auth.md'), '---\ntitle: Auth\n---\n\n# Ignore me\n');++ const someday = await enrichPath('content/someday.md', { projectDir: project });+ const loops = await enrichPath('content/loops.md', { projectDir: project });+ const auth = await enrichPath('content/auth.md', { projectDir: project });++ expect(someday.title).toBe('Someday / Open Loops');+ expect(loops.title).toBe('Open Loops');+ expect(auth.title).toBe('Auth');+ });+test('frontmatter under trailing-whitespace fences still enriches title/description/tags', async () => {// `--- ` / `---\t` fence lines are in-tolerance keystrokes away from// canonical fences; enrichment must keep recognizing the FM block@@ -155,7 +175,8 @@ describe('enrichPath — folder frontmatter does NOT cascade into docs (self-onl);const meta = await enrichPath('specs/foo.md', { projectDir: project });- expect(meta.title).toBeUndefined();+ // The doc's own `# foo` heading, never the folder's `title: Specs`.+ expect(meta.title).toBe('foo');expect(meta.description).toBeUndefined();expect(meta.tags).toEqual([]);expect(meta.frontmatter).toEqual({});@@ -188,7 +209,8 @@ describe('enrichPath — folder frontmatter does NOT cascade into docs (self-onlwriteFileSync(resolve(project, '.ok/frontmatter.yml'), 'title: Root Default\ntags:\n - kb\n');const meta = await enrichPath('top.md', { projectDir: project });- expect(meta.title).toBeUndefined();+ // The doc's own `# top` heading, never the root folder's `title: Root Default`.+ expect(meta.title).toBe('top');expect(meta.tags).toEqual([]);expect(meta.frontmatter).toEqual({});});@@ -445,3 +467,78 @@ describe('parseCommentThreads', () => {expect(parseCommentThreads({ threads: [] })).toEqual([]);});});++describe('the title ladder reads the same on every surface', () => {+ // `extractPageTitle` (used by /api/pages + search) trims the scalar and treats+ // a blank one as absent. Enrichment has to agree, or the heading fallback+ // closes the cross-surface split for missing titles and leaves it open for+ // blank ones.++ test('a blank or whitespace-only `title:` falls through to the H1, not over it', async () => {+ const project = await bootstrapProject();+ const contentDir = resolve(project, 'content');+ mkdirSync(contentDir, { recursive: true });+ writeFileSync(resolve(contentDir, 'empty.md'), '---\ntitle: ""\n---\n\n# Real Title\n');+ writeFileSync(resolve(contentDir, 'spaces.md'), '---\ntitle: " "\n---\n\n# Also Real\n');+ // Nothing to fall through TO: blank title, no heading -> path, never ''.+ writeFileSync(resolve(contentDir, 'bare.md'), '---\ntitle: ""\n---\n\nBody only\n');++ expect((await enrichPath('content/empty.md', { projectDir: project })).title).toBe(+ 'Real Title',+ );+ expect((await enrichPath('content/spaces.md', { projectDir: project })).title).toBe(+ 'Also Real',+ );+ expect((await enrichPath('content/bare.md', { projectDir: project })).title).toBeUndefined();+ });++ test('a padded `title:` is trimmed, matching extractPageTitle', async () => {+ const project = await bootstrapProject();+ const contentDir = resolve(project, 'content');+ mkdirSync(contentDir, { recursive: true });+ writeFileSync(resolve(contentDir, 'padded.md'), '---\ntitle: " Foo "\n---\n\n# Heading\n');++ expect((await enrichPath('content/padded.md', { projectDir: project })).title).toBe('Foo');+ });++ test('enrichDirectory mostRecentMd walks the SAME ladder', async () => {+ // This branch had no title coverage at all, so the heading fallback could be+ // deleted here without a red test.+ const project = await bootstrapProject();+ const dir = resolve(project, 'notes');+ mkdirSync(dir, { recursive: true });++ // `mostRecent` is chosen by mtime, and consecutive writes can land on the+ // same timestamp where the filesystem's granularity is coarser than the gap+ // between them — which is why relying on write order passed on macOS and+ // failed on CI. Stamp each file explicitly so "most recent" is decided by+ // the test rather than by clock resolution.+ let tick = 1_700_000_000;+ const writeNewest = (name: string, body: string): void => {+ const p = resolve(dir, name);+ writeFileSync(p, body);+ tick += 60;+ const t = new Date(tick * 1000);+ utimesSync(p, t, t);+ };++ writeNewest('a.md', '# From The Heading\n');+ const headingOnly = await enrichDirectory('notes', { projectDir: project });+ expect(headingOnly.mostRecentMd?.title).toBe('From The Heading');++ // An explicit title outranks the heading.+ writeNewest('b.md', '---\ntitle: Explicit\n---\n\n# Ignored\n');+ const titled = await enrichDirectory('notes', { projectDir: project });+ expect(titled.mostRecentMd?.title).toBe('Explicit');++ // Blank title falls through to the heading here too.+ writeNewest('c.md', '---\ntitle: " "\n---\n\n# Blank Falls Through\n');+ const blank = await enrichDirectory('notes', { projectDir: project });+ expect(blank.mostRecentMd?.title).toBe('Blank Falls Through');++ // Neither title nor heading: the basename is the last rung.+ writeNewest('d.md', 'just a body\n');+ const bare = await enrichDirectory('notes', { projectDir: project });+ expect(bare.mostRecentMd?.title).toBe('d.md');+ });+});diff --git a/packages/server/src/content/enrichment.ts b/packages/server/src/content/enrichment.tsindex f8789dbdc..0092e5d41 100644--- a/packages/server/src/content/enrichment.ts+++ b/packages/server/src/content/enrichment.ts@@ -20,10 +20,12 @@ import {type FrontmatterSchemaMapping,OK_DIR,parseFrontmatterRecord,+ stripFrontmatter,} from '@inkeep/open-knowledge-core';import { getLogger } from '../logger.ts';import { resolveWithinRoot } from '../mcp/tools/path-safety.ts';import { httpGet } from '../mcp/tools/shared.ts';+import { extractFirstHeading } from '../page-identity.ts';import { readFolderFrontmatter } from './nested-folder-rules.ts';import { type GitCommit, type ProjectHistorySource, readProjectGitLog } from './project-log.ts';import { type HistorySource, readShadowLog, type ShadowCommit } from './shadow-log.ts';@@ -197,10 +199,15 @@ export interface EnrichedMeta {/** Project-root-relative path. */path: string;/**- * Well-known typed fields lifted from the merged frontmatter for- * backward compat with consumers that pre-date arbitrary-key support- * (search highlighting, sidebar, exec). Mirrors the same scalars that- * also appear in `frontmatter` below.+ * Well-known typed fields for backward compat with consumers that pre-date+ * arbitrary-key support (search highlighting, sidebar, exec).+ *+ * `description` and `tags` mirror the same scalars that appear in+ * `frontmatter` below. `title` does NOT: it is the resolved title, so a doc+ * with no usable `title:` reports its first `# heading` instead, and a+ * `title:` that is present reports trimmed. It stays `undefined` when there+ * is neither, so a caller can apply its own last rung (`exec` uses the path).+ * Read `frontmatter.title` for what the file literally declared.*/title?: string;description?: string;@@ -405,13 +412,27 @@ export function pathToDocName(relPath: string): string {*/const fmReadWarnedPaths = new Set<string>();-async function readFrontmatter(absPath: string): Promise<Record<string, unknown> | null> {+/**+ * Frontmatter plus the body's first `# heading`, read in one pass. The heading+ * is the title fallback for the many files that carry no `title:` — vaults,+ * imported notes, plain logs. Same ladder `extractPageTitle` gives `/api/pages`+ * and workspace search, so one document reads the same everywhere.+ */+interface FileHead {+ frontmatter: Record<string, unknown>;+ firstHeading: string | undefined;+}++async function readFrontmatter(absPath: string): Promise<FileHead | null> {try {const content = await readFile(absPath, 'utf-8');// Raw record on purpose (not `parseFrontmatterYaml`): the open-shape// merge must see every key/value the file declared, verbatim.const fm = parseFrontmatterRecord(content);- return fm ?? {};+ return {+ frontmatter: fm ?? {},+ firstHeading: extractFirstHeading(stripFrontmatter(content).body),+ };} catch (err) {// ENOENT is expected (caller is enriching paths from a stale listing or a// dir that contains non-md children). All other read errors — EMFILE@@ -663,6 +684,33 @@ async function fetchForwardLinks(return entries;}+/**+ * The frontmatter-title-then-first-heading rungs of the title ladder, matching+ * `extractPageTitle`'s scalar semantics so one document reads the same on every+ * surface. A `title:` is trimmed, and a blank or whitespace-only one is not a+ * title at all: it falls through to the heading, exactly as+ * `extractFrontmatterScalar`'s `value || null` does for `/api/pages` and search.+ * Without the trim these two ladders disagree on `title: " Foo "`, and without+ * the blank check they disagree on `title: ""` — the same cross-surface split+ * the heading fallback exists to close, just for a narrower input class.+ *+ * Quotes need no unwrapping here (unlike the raw-line reader): this `fm` came+ * from `parseFrontmatterRecord`, so YAML already resolved the scalar.+ *+ * Callers append their own last rung — the path for a document, the basename+ * for a directory's most-recent entry — so the precedence above it is decided+ * once.+ */+function ownTitle(+ fm: Record<string, unknown> | null | undefined,+ firstHeading: string | undefined,+): string | undefined {+ const raw = fm?.title;+ if (typeof raw !== 'string') return firstHeading;+ const trimmed = raw.trim();+ return trimmed === '' ? firstHeading : trimmed;+}+/*** Lift the typed well-known fields from a doc's OWN frontmatter. A doc's* effective frontmatter equals its on-disk YAML — there is no folder-cascade@@ -673,14 +721,17 @@ async function fetchForwardLinks(* - `title` / `description` / `tags` — typed lifts of the well-known three* for backward-compat consumers (search, sidebar, exec)*/-function liftOwnFrontmatter(fileFm: Record<string, unknown> | null): {+function liftOwnFrontmatter(+ fileFm: Record<string, unknown> | null,+ firstHeading?: string,+): {title?: string;description?: string;tags: string[];frontmatter: Record<string, unknown>;} {const fm = fileFm ?? {};- const title = typeof fm.title === 'string' ? fm.title : undefined;+ const title = ownTitle(fm, firstHeading);const description = typeof fm.description === 'string' ? fm.description : undefined;const tags = Array.isArray(fm.tags)? (fm.tags as unknown[]).filter((t): t is string => typeof t === 'string')@@ -717,8 +768,8 @@ export async function enrichPath(applicableSchemas.length > 0 ? { schemas_applicable: applicableSchemas } : {};if (!rich) {- const fm = await fmPromise;- const lifted = liftOwnFrontmatter(fm);+ const head = await fmPromise;+ const lifted = liftOwnFrontmatter(head?.frontmatter ?? null, head?.firstHeading);return {path: relPath,title: lifted.title,@@ -744,7 +795,7 @@ export async function enrichPath(}// Rich mode — fan out all six data sources in parallel.- const [fm, backlinks, forwardLinks, shadow, project, comments] = await Promise.all([+ const [head, backlinks, forwardLinks, shadow, project, comments] = await Promise.all([fmPromise,fetchBacklinks(deps.serverUrl, pathToDocName(relPath)).catch(() => null),fetchForwardLinks(deps.serverUrl, pathToDocName(relPath)).catch(() => null),@@ -759,7 +810,7 @@ export async function enrichPath(fetchComments(deps.serverUrl, pathToDocName(relPath)).catch(() => null),]);- const lifted = liftOwnFrontmatter(fm);+ const lifted = liftOwnFrontmatter(head?.frontmatter ?? null, head?.firstHeading);return {path: relPath,title: lifted.title,@@ -873,11 +924,11 @@ export async function enrichDirectory(let mostRecentMd: DirectoryMeta['mostRecentMd'];if (scan.mostRecent) {- const fm = await readFrontmatter(scan.mostRecent.absPath);- const fmTitle = typeof fm?.title === 'string' ? fm.title : undefined;+ const head = await readFrontmatter(scan.mostRecent.absPath);mostRecentMd = {path: scan.mostRecent.relPath,- title: fmTitle ?? basename(scan.mostRecent.relPath),+ // Same ladder as a document's own title; only the last rung differs.+ title: ownTitle(head?.frontmatter, head?.firstHeading) ?? basename(scan.mostRecent.relPath),updatedAt: new Date(scan.mostRecent.mtimeMs).toISOString(),};}diff --git a/packages/server/src/page-identity.test.ts b/packages/server/src/page-identity.test.tsindex e37adaf16..7423dd616 100644--- a/packages/server/src/page-identity.test.ts+++ b/packages/server/src/page-identity.test.ts@@ -1,5 +1,6 @@import { describe, expect, test } from 'vitest';import {+ extractFirstHeading,extractPageAliases,extractPageIcon,extractPageIdentity,@@ -274,3 +275,36 @@ describe('extractPageIcon', () => {expect(extractPageIcon(content)).toBeUndefined();});});++describe('extractFirstHeading', () => {+ // Split out of `extractPageTitle` so enrichment can answer `undefined` for+ // "no heading" instead of the filename. It is now a second public entry+ // point, so its contract is pinned here rather than only through the ladder.+ // Takes a body with frontmatter ALREADY stripped.++ test('returns the H1 text', () => {+ expect(extractFirstHeading('# Someday / Open Loops\n\nBody\n')).toBe('Someday / Open Loops');+ });++ test('returns undefined with no heading, so callers can pick their own last rung', () => {+ expect(extractFirstHeading('just a body\n')).toBeUndefined();+ });++ test('an H2 is not a title', () => {+ expect(extractFirstHeading('## Section\n\nBody\n')).toBeUndefined();+ });++ test('trims, matching the frontmatter scalar reader', () => {+ expect(extractFirstHeading('# Padded Title \n')).toBe('Padded Title');+ });++ test('finds an H1 that is not the first line', () => {+ // The `m` flag is what makes this work; dropping it would silently narrow+ // the fallback to documents whose very first line is the heading.+ expect(extractFirstHeading('intro paragraph\n\n# Real Title\n')).toBe('Real Title');+ });++ test('takes the FIRST H1 when several exist', () => {+ expect(extractFirstHeading('# One\n\n# Two\n')).toBe('One');+ });+});diff --git a/packages/server/src/page-identity.ts b/packages/server/src/page-identity.tsindex 7e624aa9a..7c9147c49 100644--- a/packages/server/src/page-identity.ts+++ b/packages/server/src/page-identity.ts@@ -133,12 +133,18 @@ export function extractPageTitle(content: string, filename: string): string {const title = extractFrontmatterScalar(frontmatter, 'title');if (title) return title;- const headingMatch = body.match(/^# (.+)$/m);- if (headingMatch) {- return headingMatch[1].trim();- }+ return extractFirstHeading(body) ?? filename;+}- return filename;+/**+ * The `# heading` half of `extractPageTitle`'s ladder, on its own, for callers+ * whose "no title" answer is `undefined` rather than the filename — enrichment+ * leaves `title` unset so `exec` can fall back to the path itself. Takes a body+ * with frontmatter already stripped.+ */+export function extractFirstHeading(body: string): string | undefined {+ const headingMatch = body.match(/^# (.+)$/m);+ return headingMatch ? headingMatch[1].trim() : undefined;}/**