structured-context 0.11.0 → 0.13.0

package/dist/plugins/markdown/index.js

@@ -2,6 +2,7 @@ import { statSync } from 'node:fs';
 import { PLUGIN_PREFIX } from '../util';
 import { readSpaceDirectory, readSpaceOnAPage } from './read-space';
 import { renderBullets } from './render-bullets';
+import { renderMarkdownDirectory } from './render-directory';
 import { templateSync } from './template-sync';
 const TYPE_INFERENCE_CONFIG_SCHEMA = {
     type: 'object',
@@ -36,10 +37,15 @@ export const markdownPlugin = {
     parse,
     templateSync,
     render: {
-        formats: [{ name: 'bullets', description: 'Indented bullet list' }],
-        render(_context, graph, { format }) {
+        formats: [
+            { name: 'bullets', description: 'Indented bullet list' },
+            { name: 'directory', description: 'Markdown space directory with one file per node' },
+        ],
+        render(context, graph, { format, data }) {
             if (format === 'bullets')
                 return renderBullets(graph);
+            if (format === 'directory')
+                return renderMarkdownDirectory(context, graph, { format, data });
             throw new Error(`Unknown markdown render format: "${format}"`);
         },
     },

package/dist/plugins/markdown/parse-embedded.d.ts

@@ -8,6 +8,8 @@ type StackEntry = {
     nodeType: string;
     /** Preferred wikilink key used when this heading acts as a parent. */
     refTarget: string;
+    /** Node whose section this heading opens; absent for untyped placeholders and the page's own entry. */
+    node?: BaseNode;
 };
 /** Detect a bare wikilink `[[...]]` and return the inner target, or undefined. */
 export declare function isWikilink(text: string): string | undefined;
@@ -74,11 +76,17 @@ export interface ExtractEmbeddedOptions {
      * Example: { "record_type": "type" } renames `record_type` to `type` in extracted data.
      */
     fieldMap?: Record<string, string>;
+    /** File path of the containing document, for populating node.source. */
+    file?: string;
+    /** Line offset of the body within the source file (e.g. frontmatter lines). */
+    lineOffset?: number;
 }
 export interface ExtractEmbeddedResult {
     nodes: BaseNode[];
     preambleNodeCount: number;
     terminatedHeadings: string[];
+    preambleContent?: string;
+    preambleFields?: Record<string, unknown>;
 }
 /**
  * Extract space nodes from markdown body text.

package/dist/plugins/markdown/parse-embedded.js

@@ -1,10 +1,9 @@
-import { load as yamlLoad } from 'js-yaml';
 import { toString as mdastToString } from 'mdast-util-to-string';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
 import { extractLinksFromAstNode } from './extract-content-links';
-import { applyFieldMap, coerceDates } from './util';
+import { applyFieldMap, parseYaml } from './util';
 /** Type values that identify a space_on_a_page container (not themselves space nodes). */
 export const ON_A_PAGE_TYPES = ['ost_on_a_page', 'space_on_a_page'];
 const DEFAULT_STATUS = 'identified';
@@ -141,16 +140,91 @@ export function defaultNodeType(stack, hierarchy) {
     }
     return hierarchy[idx + 1];
 }
-function appendContent(node, text) {
-    if (!text)
+/** Start and end offsets of an mdast node. Throws when the parser gave no position. */
+function offsetsOf(node) {
+    const start = node.position?.start.offset;
+    const end = node.position?.end.offset;
+    if (start === undefined || end === undefined) {
+        throw new Error(`Markdown ${node.type} node has no source position; cannot slice its content`);
+    }
+    return { start, end };
+}
+function addRange(claims, node, start, end) {
+    if (end <= start)
         return;
-    const existing = node.schemaData.content;
-    node.schemaData.content = existing ? `${existing}\n${text}` : text;
+    const ranges = claims.ranges.get(node) ?? [];
+    const last = ranges[ranges.length - 1];
+    if (last && last.end === start)
+        last.end = end;
+    else
+        ranges.push({ start, end });
+    claims.ranges.set(node, ranges);
+}
+/**
+ * Give a node a block of source, plus the blank lines between `from` and the block's `start`.
+ * Those lines are skipped when a consumed block just before already kept its own.
+ */
+function claim(claims, node, from, start, end) {
+    addRange(claims, node, claims.gapKept.delete(node) ? start : from, end);
+}
+/**
+ * Take a block out of a node's content (it was consumed as a node, field or other syntax).
+ * The blank lines before it stay, so the content on either side does not run together.
+ */
+function consume(claims, node, from, start) {
+    addRange(claims, node, claims.gapKept.delete(node) ? start : from, start);
+    claims.gapKept.add(node);
+}
+/** Sets each node's content from its claimed source. Leading blank lines and trailing whitespace are dropped. */
+function applyClaims(claims, body) {
+    for (const [node, ranges] of claims.ranges) {
+        let content = ranges
+            .map((r) => body.slice(r.start, r.end))
+            .join('')
+            .replace(/^(?:[ \t]*\r?\n)+/, '')
+            .trimEnd();
+        const indent = claims.contentIndent.get(node);
+        if (indent) {
+            const strip = new RegExp(`^[ \\t]{1,${indent}}`);
+            content = content
+                .split(/(?<=\n)/)
+                .map((line) => line.replace(strip, ''))
+                .join('');
+        }
+        if (!content)
+            continue;
+        node.schemaData.content = content;
+        node.content = content;
+    }
+}
+/** Source lines (with terminators) of a range, as absolute offsets. */
+function sourceLines(body, range) {
+    const lines = [];
+    const re = /[^\n]*\n|[^\n]+$/g;
+    const text = body.slice(range.start, range.end);
+    for (const m of text.matchAll(re)) {
+        lines.push({
+            start: range.start + m.index,
+            end: range.start + m.index + m[0].length,
+            text: m[0].replace(/\r?\n$/, ''),
+        });
+    }
+    return lines;
+}
+/** Whether a line holds only inline fields: bracketed `[key:: value]` pieces, or one `key:: value`. */
+function isFieldOnlyLine(line) {
+    const { cleanText, fields } = extractBracketedFields(line);
+    const hasBracketed = Object.keys(fields).length > 0;
+    if (cleanText === '')
+        return hasBracketed;
+    return /^[a-zA-Z][a-zA-Z0-9_-]*:: *.*$/.test(cleanText);
 }
-function processListItem(item, parentRef, contentTarget, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, parentFieldAppend, activeNodeFieldAppend) {
+function processListItem(item, parentRef, contentTarget, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, parentFieldAppend, activeNodeFieldAppend, file, lineOffset, walk) {
+    const itemEnd = offsetsOf(item).end;
     const firstPara = item.children.find((c) => c.type === 'paragraph');
     if (!firstPara) {
-        appendContent(contentTarget, `- ${mdastToString(item)}`);
+        claim(walk.claims, contentTarget, walk.pos, offsetsOf(item).start, itemEnd);
+        walk.pos = itemEnd;
         return;
     }
     const rawText = mdastToString(firstPara);
@@ -159,11 +233,15 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
     if (wikiTarget) {
         const linkRef = `[[${wikiTarget}]]`;
         if (parentFieldAppend) {
+            consume(walk.claims, contentTarget, walk.pos, offsetsOf(item).start);
             appendParentField(parentFieldAppend.node, parentFieldAppend.field, linkRef);
+            walk.pos = itemEnd;
             return;
         }
         if (activeNodeFieldAppend) {
+            consume(walk.claims, contentTarget, walk.pos, offsetsOf(item).start);
             appendParentField(activeNodeFieldAppend.node, activeNodeFieldAppend.field, linkRef);
+            walk.pos = itemEnd;
             return;
         }
         // No field append context — fall through to node creation or content append
@@ -185,6 +263,11 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
             schemaData.parent = parentRef;
         if (summary)
             schemaData.summary = summary;
+        const line = item.position?.start.line ? item.position.start.line + (lineOffset ?? 0) : undefined;
+        const column = item.position?.start.column;
+        const source = file
+            ? { file, ...(line !== undefined ? { line } : {}), ...(column !== undefined ? { column } : {}) }
+            : undefined;
         const linkTargets = buildLinkTargets(title);
         const newNode = {
             label: makeLabel(title),
@@ -192,24 +275,39 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
             schemaData,
             linkTargets,
             type,
+            ...(schemaData.content !== undefined ? { content: schemaData.content } : {}),
             contentLinks: [],
+            ...(source ? { source } : {}),
         };
         nodes.push(newNode);
+        const contentColumn = firstPara.position?.start.column;
+        if (contentColumn !== undefined)
+            walk.claims.contentIndent.set(newNode, contentColumn - 1);
         if (parentFieldAppend) {
             appendParentField(parentFieldAppend.node, parentFieldAppend.field, `[[${linkTargets[0] ?? title}]]`);
         }
         const nestedParentRef = `[[${linkTargets[0] ?? title}]]`;
+        consume(walk.claims, contentTarget, walk.pos, offsetsOf(item).start);
+        walk.pos = offsetsOf(firstPara).end;
         for (const child of item.children) {
+            if (child === firstPara)
+                continue;
             if (child.type === 'list') {
                 for (const subItem of child.children) {
-                    processListItem(subItem, nestedParentRef, newNode, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType);
+                    processListItem(subItem, nestedParentRef, newNode, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, undefined, undefined, file, lineOffset, walk);
                 }
             }
+            else {
+                const { start, end } = offsetsOf(child);
+                claim(walk.claims, newNode, walk.pos, start, end);
+                walk.pos = end;
+            }
         }
     }
     else {
-        appendContent(contentTarget, `- ${rawText}`);
+        claim(walk.claims, contentTarget, walk.pos, offsetsOf(item).start, itemEnd);
     }
+    walk.pos = itemEnd;
 }
 /**
  * Extract space nodes from markdown body text.
@@ -240,7 +338,7 @@ export function extractEmbeddedNodes(body, options) {
     const stack = !isOnAPageMode && pageTitle !== undefined
         ? [{ depth: 0, title: pageTitle, nodeType: pageType, refTarget: pageTitle }]
         : [];
-    let parseState = 'preamble';
+    let parseState = isOnAPageMode ? 'preamble' : 'active';
     let preambleNodeCount = 0;
     const terminatedHeadings = [];
     /**
@@ -409,7 +507,32 @@ export function extractEmbeddedNodes(body, options) {
     }
     let grouping = null;
     let activeNode = rootNode;
+    const claims = { ranges: new Map(), gapKept: new Set(), contentIndent: new Map() };
+    /** End of the previous top-level block; a block's span starts here so the blank lines before it stay with it. */
+    let prevEnd = 0;
     for (const child of tree.children) {
+        const { start: blockStart, end: blockEnd } = offsetsOf(child);
+        const spanStart = prevEnd;
+        prevEnd = blockEnd;
+        /** Give a node this block as source content, minus any `removed` ranges inside it. */
+        const claimBlock = (node, removed = []) => {
+            let from = blockStart;
+            let first = true;
+            for (const gap of removed) {
+                if (first)
+                    claim(claims, node, spanStart, blockStart, gap.start);
+                else
+                    addRange(claims, node, from, gap.start);
+                first = false;
+                from = gap.end;
+            }
+            if (first)
+                claim(claims, node, spanStart, blockStart, blockEnd);
+            else
+                addRange(claims, node, from, blockEnd);
+        };
+        /** Take this whole block out of a node's content, keeping the blank lines before it. */
+        const consumeBlock = (node) => consume(claims, node, spanStart, blockStart);
         if (parseState === 'done') {
             if (child.type === 'heading') {
                 const rawTitle = mdastToString(child);
@@ -427,8 +550,11 @@ export function extractEmbeddedNodes(body, options) {
         if (child.type === 'heading') {
             const heading = child;
             const depth = heading.depth;
-            if (depth > 5)
+            if (depth > 5) {
+                if (parseState === 'active')
+                    claimBlock(activeNode);
                 continue;
+            }
             parseState = 'active';
             const rawText = mdastToString(heading);
             const { cleanText: afterBracketed, fields: rawInlineFields } = extractBracketedFields(rawText);
@@ -446,6 +572,10 @@ export function extractEmbeddedNodes(body, options) {
                 stack.push({ depth, title, nodeType: '', refTarget: title });
                 // Discard any pending grouping (untyped heading has no implied type)
                 grouping = null;
+                // An untyped heading is part of the body of the nearest enclosing node. Popping above removed every
+                // node at the same or a higher level, so those sections end here; deeper nodes' sections continue.
+                activeNode = stack.findLast((entry) => entry.node)?.node ?? rootNode;
+                claimBlock(activeNode);
                 continue;
             }
             if (isOnAPageMode && stack.length > 0) {
@@ -467,6 +597,11 @@ export function extractEmbeddedNodes(body, options) {
             };
             if (parentRef)
                 schemaData.parent = parentRef;
+            const line = heading.position?.start.line ? heading.position.start.line + (options.lineOffset ?? 0) : undefined;
+            const column = heading.position?.start.column;
+            const source = options.file
+                ? { file: options.file, ...(line !== undefined ? { line } : {}), ...(column !== undefined ? { column } : {}) }
+                : undefined;
             const linkTargets = buildHeadingLinkTargets(rawText, title, anchor);
             const headingNode = {
                 label: makeLabel(title),
@@ -474,11 +609,13 @@ export function extractEmbeddedNodes(body, options) {
                 schemaData,
                 linkTargets,
                 type,
+                ...(schemaData.content !== undefined ? { content: schemaData.content } : {}),
                 contentLinks: [],
+                ...(source ? { source } : {}),
             };
             // Push to stack BEFORE resolving semantic parent — stack[-2] is the correct parent.
             const refTarget = linkTargets[0] ?? title;
-            stack.push({ depth, title, nodeType: type, refTarget });
+            stack.push({ depth, title, nodeType: type, refTarget, node: headingNode });
             // If this match came from a relationship/hierarchy and no explicit type was given,
             // create a grouping — delay adding the node until we see the following content.
             // Discard any previous grouping (not flushed — original agnostic-parse behaviour).
@@ -516,14 +653,16 @@ export function extractEmbeddedNodes(body, options) {
                 const activeNodeFieldAppendArg = isParentLevelMatch && semanticParent.node
                     ? { node: semanticParent.node, field: definition.field }
                     : undefined;
+                const walk = { claims, pos: spanStart };
                 for (const item of list.children) {
-                    processListItem(item, isParentSide ? undefined : semanticParent.ref, grouping.headingNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, definition.type, parentFieldAppendArg, activeNodeFieldAppendArg);
+                    processListItem(item, isParentSide ? undefined : semanticParent.ref, grouping.headingNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, definition.type, parentFieldAppendArg, activeNodeFieldAppendArg, options.file, options.lineOffset, walk);
                 }
                 grouping = null;
             }
             else {
+                const walk = { claims, pos: spanStart };
                 for (const item of list.children) {
-                    processListItem(item, parentRef, activeNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap);
+                    processListItem(item, parentRef, activeNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, undefined, undefined, undefined, options.file, options.lineOffset, walk);
                 }
             }
         }
@@ -605,6 +744,15 @@ export function extractEmbeddedNodes(body, options) {
                                 schemaData[mappedColName] = cellContent;
                             }
                         }
+                        const line = row.position?.start.line ? row.position.start.line + (options.lineOffset ?? 0) : undefined;
+                        const column = row.position?.start.column;
+                        const source = options.file
+                            ? {
+                                file: options.file,
+                                ...(line !== undefined ? { line } : {}),
+                                ...(column !== undefined ? { column } : {}),
+                            }
+                            : undefined;
                         const linkTargets = buildListItemLinkTargets(title);
                         const rowNode = {
                             label: makeLabel(title),
@@ -613,6 +761,7 @@ export function extractEmbeddedNodes(body, options) {
                             linkTargets,
                             type: rowTypeStr,
                             contentLinks: [],
+                            ...(source ? { source } : {}),
                         };
                         nodes.push(rowNode);
                         if (tableParentFieldAppend) {
@@ -622,7 +771,7 @@ export function extractEmbeddedNodes(body, options) {
                     grouping = null;
                 }
                 else {
-                    appendContent(activeNode, mdastToString(child));
+                    claimBlock(activeNode);
                 }
             }
         }
@@ -636,37 +785,59 @@ export function extractEmbeddedNodes(body, options) {
             if (child.type === 'paragraph') {
                 const rawText = mdastToString(child);
                 const { cleanText: afterBracketed, fields: bracketedFields } = extractBracketedFields(rawText);
-                const { remainingText, fields: unbracketedFields } = extractUnbracketedFields(afterBracketed);
+                const { fields: unbracketedFields } = extractUnbracketedFields(afterBracketed);
                 const allFields = applyFieldMap({ ...unbracketedFields, ...bracketedFields }, fieldMap);
                 if ('type' in allFields) {
                     throw new Error(`Type override via paragraph field is not supported at "${activeNode.schemaData.title ?? activeNode.label}". ` +
                         `Put [type:: ${allFields.type}] directly in the heading text.`);
                 }
                 Object.assign(activeNode.schemaData, allFields);
-                if (remainingText)
-                    appendContent(activeNode, remainingText);
+                // Lines holding only fields are consumed as fields; any other line, including prose that mentions a field, is content.
+                const lines = sourceLines(body, { start: blockStart, end: blockEnd });
+                const fieldLines = lines.filter((l) => isFieldOnlyLine(l.text));
+                if (fieldLines.length === lines.length) {
+                    consumeBlock(activeNode);
+                }
+                else {
+                    // Each field line goes with its terminator; a last line without one takes the preceding line break instead.
+                    claimBlock(activeNode, fieldLines.map((l) => {
+                        if (/\n$/.test(body.slice(l.start, l.end)))
+                            return { start: l.start, end: l.end };
+                        return { start: l.start - (body[l.start - 2] === '\r' ? 2 : 1), end: l.end };
+                    }));
+                }
                 activeNode.contentLinks ??= [];
                 activeNode.contentLinks.push(...extractLinksFromAstNode(child));
             }
             else if (child.type === 'code' && child.lang?.trim() === 'yaml') {
                 const code = child;
-                const parsed = yamlLoad(code.value);
+                const parsed = parseYaml(code.value);
                 if (parsed && !Array.isArray(parsed) && typeof parsed === 'object') {
-                    Object.assign(activeNode.schemaData, coerceDates(applyFieldMap(parsed, fieldMap)));
+                    Object.assign(activeNode.schemaData, applyFieldMap(parsed, fieldMap));
+                    consumeBlock(activeNode);
                 }
                 else if (Array.isArray(parsed)) {
                     throw new Error(`YAML block must be an object at "${activeNode.label}".`);
                 }
                 else {
-                    appendContent(activeNode, code.value);
+                    claimBlock(activeNode);
                 }
             }
             else {
-                appendContent(activeNode, mdastToString(child));
+                claimBlock(activeNode);
                 activeNode.contentLinks ??= [];
                 activeNode.contentLinks.push(...extractLinksFromAstNode(child));
             }
         }
     }
-    return { nodes, preambleNodeCount, terminatedHeadings };
+    applyClaims(claims, body);
+    const preambleContent = rootNode.schemaData.content;
+    const { type: _rootType, content: _rootContent, ...preambleFields } = rootNode.schemaData;
+    return {
+        nodes,
+        preambleNodeCount,
+        terminatedHeadings,
+        preambleContent,
+        preambleFields: Object.keys(preambleFields).length > 0 ? preambleFields : undefined,
+    };
 }

package/dist/plugins/markdown/read-space.js

@@ -5,12 +5,12 @@ import matter from 'gray-matter';
 import { extractSchemaTypeNames } from '../../schema/schema';
 import { extractLinksFromBody, extractLinksFromFrontmatter, getEdgeFieldNames } from './extract-content-links';
 import { extractEmbeddedNodes, ON_A_PAGE_TYPES } from './parse-embedded';
-import { applyFieldMap, coerceDates, inferTypeFromPath } from './util';
+import { applyFieldMap, inferTypeFromPath, MATTER_OPTIONS } from './util';
 export function readSpaceOnAPage(context) {
     const { space, resolvedSchemaPath, schema: { metadata }, } = context;
     const filePath = resolve(space.path);
     const raw = readFileSync(filePath, 'utf-8');
-    const { data: frontmatter, content: body } = matter(raw);
+    const { data: frontmatter, content: body } = matter(raw, MATTER_OPTIONS);
     const pageType = frontmatter.type;
     if (pageType !== undefined && !ON_A_PAGE_TYPES.includes(pageType)) {
         throw new Error(`Expected a space_on_a_page file but got type "${pageType}" in ${filePath}. ` +
@@ -21,10 +21,15 @@ export function readSpaceOnAPage(context) {
         throw new Error(`Schema at ${resolvedSchemaPath} must define "$metadata.hierarchy.levels" to read a space_on_a_page file.`);
     }
     const pageTitle = basename(filePath, '.md');
+    const fmMatch = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+    const lineOffset = fmMatch ? (fmMatch[0].match(/\n/g) || []).length : 0;
+    const fileName = basename(filePath);
     const { nodes, preambleNodeCount, terminatedHeadings } = extractEmbeddedNodes(body, {
         pageTitle,
         pageType: 'space_on_a_page',
         metadata,
+        file: fileName,
+        lineOffset,
     });
     const parseIssues = terminatedHeadings.map((heading) => ({
         file: heading,
@@ -55,32 +60,38 @@ export async function readSpaceDirectory(context, options) {
         const content = readFileSync(join(directory, file), 'utf-8');
         let parsed;
         try {
-            parsed = matter(content);
+            parsed = matter(content, MATTER_OPTIONS);
         }
         catch (err) {
-            // gray-matter caches parsed YAML and has a known bug where a caught exception
-            // corrupts its internal cache, causing subsequent parses to silently return {}.
-            // Clear the cache after any parse error to avoid stale state.
-            // See: https://github.com/jonschlinkert/gray-matter/issues/166
-            matter.clearCache();
+            const yamlErr = err;
+            const line = yamlErr.mark ? yamlErr.mark.line + 1 : undefined;
+            const column = yamlErr.mark ? yamlErr.mark.column + 1 : undefined;
             parseIssues.push({
                 file,
                 severity: 'error',
                 type: 'parse',
                 message: err instanceof Error ? err.message : String(err),
+                ...(line !== undefined ? { line } : {}),
+                ...(column !== undefined ? { column } : {}),
             });
             continue;
         }
         if (!parsed.data || Object.keys(parsed.data).length === 0) {
-            parseIssues.push({ file, severity: 'warning', type: 'no-type', message: 'No front-matter or type specified' });
+            parseIssues.push({
+                file,
+                severity: 'warning',
+                type: 'no-type',
+                message: 'No front-matter or type specified',
+                line: 1,
+            });
             continue;
         }
-        const data = coerceDates(applyFieldMap(parsed.data, fieldMap));
+        const data = applyFieldMap(parsed.data, fieldMap);
         if (!data.type && typeInferenceCfg && knownTypes) {
             data.type = inferTypeFromPath(file, typeInferenceCfg, knownTypes, context.schema.metadata.typeAliases);
         }
         if (!data.type) {
-            parseIssues.push({ file, severity: 'warning', type: 'no-type' });
+            parseIssues.push({ file, severity: 'warning', type: 'no-type', line: 1 });
             continue;
         }
         if (ON_A_PAGE_TYPES.includes(data.type) && !options?.includeOnAPageFiles) {
@@ -89,21 +100,35 @@ export async function readSpaceDirectory(context, options) {
         const pageType = data.type;
         const fileBase = basename(file, '.md');
         const title = data.title ?? fileBase;
-        nodes.push({
+        const fmMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+        const lineOffset = fmMatch ? (fmMatch[0].match(/\n/g) || []).length : 0;
+        const pageNode = {
             label: file,
             title,
             schemaData: { title, ...data },
             linkTargets: [title, fileBase],
             type: pageType,
+            source: { file, line: 1 },
+            ...(data.content !== undefined ? { content: data.content } : {}),
             contentLinks: [...extractLinksFromFrontmatter(data, edgeFields), ...extractLinksFromBody(parsed.content)],
-        });
+        };
         if (!ON_A_PAGE_TYPES.includes(pageType)) {
-            const { nodes: embedded, terminatedHeadings } = extractEmbeddedNodes(parsed.content, {
+            const { nodes: embedded, preambleContent, preambleFields, terminatedHeadings, } = extractEmbeddedNodes(parsed.content, {
                 pageTitle: fileBase,
                 pageType,
                 metadata,
                 fieldMap,
+                file,
+                lineOffset,
             });
+            if (preambleFields) {
+                Object.assign(pageNode.schemaData, preambleFields);
+            }
+            if (preambleContent) {
+                pageNode.schemaData.content = preambleContent;
+                pageNode.content = preambleContent;
+            }
+            nodes.push(pageNode);
             nodes.push(...embedded);
             for (const heading of terminatedHeadings) {
                 parseIssues.push({
@@ -114,6 +139,9 @@ export async function readSpaceDirectory(context, options) {
                 });
             }
         }
+        else {
+            nodes.push(pageNode);
+        }
     }
     return { nodes, parseIssues, diagnostics: { kind: 'directory' } };
 }

package/dist/plugins/markdown/render-directory.d.ts

@@ -0,0 +1,11 @@
+import type { SpaceGraph } from '../../space-graph';
+import type { PluginContext, RenderMultiFileOutput, RenderOptions } from '../util';
+/**
+ * Sanitize a node title into a valid filesystem filename.
+ * Strips Obsidian/OS forbidden characters: \ / : * ? " < > | # ^ [ ]
+ */
+export declare function sanitizeFilename(title: string): string;
+/**
+ * Render a space graph as a markdown directory with one file per node.
+ */
+export declare function renderMarkdownDirectory(context: PluginContext, graph: SpaceGraph, options: RenderOptions): RenderMultiFileOutput;