Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
new file mode 100644
index 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.ts
index 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-onl
writeFileSync(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.ts
index 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.ts
index 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.ts
index 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;
}
/**