@effected/markdown 0.2.5 → 0.4.0

package/Frontmatter.js

@@ -69,22 +69,43 @@ var FrontmatterEncodeError = class extends Schema.TaggedErrorClass()("Frontmatte
 	}
 };
 /**
+* Why a frontmatter decoder found no capture on a document.
+*
+* @remarks
+* `"absent"` — the source genuinely has no frontmatter block.
+* `"captureDisabled"` — the source opens with a well-formed frontmatter
+* block, but the document carries no capture node: it was parsed without
+* `frontmatter: true` (the toggle defaults off), so spec-correct CommonMark
+* read the fences as ordinary content.
+*
+* @public
+*/
+const FrontmatterMissingReason = Schema.Literals(["absent", "captureDisabled"]);
+/**
 * Indicates that a document handed to a frontmatter decoder carries no
 * frontmatter capture.
 *
 * @remarks
-* Raised when the document genuinely has no frontmatter block — including
-* when it has one in the source but was parsed with the capture toggle off
-* (`MarkdownParseOptions.frontmatter` defaults to `false`). Cause-free: there
-* is nothing to diagnose beyond the absence itself. Consumers wanting
-* optional semantics can `Effect.catchTag("FrontmatterMissingError", ...)`
-* to a default.
+* `reason` distinguishes the two ways this happens: `"absent"` when the
+* source genuinely has no frontmatter block, `"captureDisabled"` when the
+* source opens with one but the document was parsed with the capture toggle
+* off (`MarkdownParseOptions.frontmatter` defaults to `false`) — the fix
+* there is parsing with `frontmatter: true`, not editing the document. The
+* discriminant is computed from the same structural signal
+* `MarkdownDocument.hasFrontmatterBlock` exposes, so the error and the
+* accessor can never disagree.
+*
+* Cause-free: there is nothing to diagnose beyond the absence itself.
+* Consumers wanting optional semantics can
+* `Effect.catchTag("FrontmatterMissingError", ...)` to a default.
 *
 * @public
 */
-var FrontmatterMissingError = class extends Schema.TaggedErrorClass()("FrontmatterMissingError", {}) {
+var FrontmatterMissingError = class extends Schema.TaggedErrorClass()("FrontmatterMissingError", { 
+/** Why there is no capture: no block at all, or capture left off. */
+reason: FrontmatterMissingReason }) {
 	get message() {
-		return "the document has no frontmatter capture; was it parsed with `frontmatter: true`?";
+		return this.reason === "captureDisabled" ? "the source opens with a frontmatter block, but it was not captured; parse with `frontmatter: true`" : "the document has no frontmatter block";
 	}
 };
 /**
@@ -157,7 +178,8 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 	* The decoder reads the document's frontmatter capture (parse with
 	* `frontmatter: true` — the toggle defaults off), decodes its raw value
 	* through the codec, then validates the data against `schema`. Each stage
-	* fails typed: no capture is {@link FrontmatterMissingError}, a
+	* fails typed: no capture is {@link FrontmatterMissingError} (its `reason`
+	* says whether the block is genuinely absent or capture was left off), a
 	* wrong-format codec is {@link FrontmatterFormatMismatchError}, unparseable
 	* content is {@link FrontmatterDecodeError}, and schema-invalid data is
 	* {@link FrontmatterValidationError} carrying the structured issue.
@@ -178,7 +200,7 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 	static schema(schema, codec) {
 		return (document) => {
 			const node = document.frontmatter;
-			return node === void 0 ? Effect.fail(new FrontmatterMissingError()) : codec.decode(node).pipe(Effect.flatMap((data) => Schema.decodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new FrontmatterValidationError({ issue: error.issue }))))));
+			return node === void 0 ? Effect.fail(new FrontmatterMissingError({ reason: document.hasFrontmatterBlock ? "captureDisabled" : "absent" })) : codec.decode(node).pipe(Effect.flatMap((data) => Schema.decodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new FrontmatterValidationError({ issue: error.issue }))))));
 		};
 	}
 	/**
@@ -269,4 +291,4 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 };
 
 //#endregion
-export { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterValidationError, MarkdownFrontmatter };
+export { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterValidationError, MarkdownFrontmatter };

package/Markdown.js

@@ -28,7 +28,9 @@ const MarkdownDialect = Schema.Literals(["commonmark", "gfm"]);
 * spec-conformant reading must hold unless a consumer opts in. Enabled, the
 * engine captures `---`/`+++`/`---json` blocks at offset 0 into a raw
 * `Frontmatter` head node — decoding it is the frontmatter codec modules'
-* job.
+* job. Parsed with the toggle off, such a document reports no frontmatter —
+* `MarkdownDocument.hasFrontmatterBlock` tells "no block in the source"
+* apart from "parsed with capture off".
 *
 * @public
 */
@@ -181,10 +183,14 @@ var Markdown = class Markdown {
 	* @remarks
 	* Canonical serialization: fidelity fields (marker characters, fence
 	* style, heading spelling) win when present; documented canonical
-	* defaults apply when absent. The output re-parses to a render-equivalent
-	* document — the corpus-pinned contract — but is not a byte-level
-	* round-trip of any original source; surgical editing goes through the
-	* offset-splice edit layer instead.
+	* defaults apply when absent. One default surprises: a language-less
+	* `Code` node with no explicit `fenceChar` serializes as an
+	* **indented** code block — set `fenceChar` (or a `lang`) on the node for
+	* a fence, or normalize afterward with
+	* `MarkdownFormattingOptions.codeBlockStyle: "fenced"`. The output
+	* re-parses to a render-equivalent document — the corpus-pinned
+	* contract — but is not a byte-level round-trip of any original source;
+	* surgical editing goes through the offset-splice edit layer instead.
 	*
 	* Failure is rare by design, symmetric with parse: only a hardening-guard
 	* trip on a tree nesting past the depth cap fails, and only synthesized

package/MarkdownDocument.js

@@ -1,11 +1,87 @@
 import { MarkdownRange } from "./MarkdownEdit.js";
 import { Definition, Root } from "./MarkdownNode.js";
+import { preprocessLines } from "./internal/preprocess.js";
 import { normalizeLabelText } from "./internal/references.js";
+import { scanFrontmatter } from "./internal/blocks/frontmatter.js";
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
 import { parsePassResult } from "./Markdown.js";
 import { Effect, Result, Schema } from "effect";
 
 //#region src/MarkdownDocument.ts
+/**
+* A heading-delimited span from {@link MarkdownDocument.sections}: the
+* heading, its depth, the source `range` the section occupies and the
+* root-level blocks that follow the heading inside it.
+*
+* @remarks
+* A section runs from its heading's start offset to the start of the next
+* root-level heading of equal or shallower depth, or to the end of the
+* source. Deeper headings nest inside, so a parent section's `range` and
+* `children` include its subsections — the list is flat, in document order,
+* with `depth` carrying the hierarchy.
+*
+* Instances come from {@link MarkdownDocument.sections} and the two finders;
+* there is no reason to construct one directly.
+*
+* @public
+*/
+var DocumentSection = class {
+	/** The heading that opens the section. */
+	heading;
+	/** The heading's depth, and the section's. */
+	depth;
+	/** The whole section including its heading — spliceable by `MarkdownEdit`. */
+	range;
+	/** The root-level blocks after the heading, subsections included. */
+	children;
+	/**
+	* The heading's plain-text content.
+	*
+	* @remarks
+	* The same derivation as {@link DocumentHeading.text}: text and inline-code
+	* values concatenated, image `alt` where present, a hard break as one space,
+	* nothing for raw HTML or footnote references. So `## **1.2.3**` reads
+	* `1.2.3`.
+	*/
+	text;
+	/**
+	* The section WITHOUT its heading: from the heading's end offset to the
+	* section's end.
+	*
+	* @remarks
+	* This is the span a "give me the release notes under this version" reader
+	* wants, and the one that is fiddly to derive by hand.
+	*/
+	bodyRange;
+	/** The document source these ranges index into. */
+	#documentSource;
+	constructor(options) {
+		this.heading = options.heading;
+		this.depth = options.depth;
+		this.range = options.range;
+		this.children = options.children;
+		this.text = options.text;
+		this.bodyRange = options.bodyRange;
+		this.#documentSource = options.documentSource;
+	}
+	/** The section's source text, heading included. */
+	get source() {
+		return this.#documentSource.slice(this.range.offset, this.range.offset + this.range.length);
+	}
+	/**
+	* The section's source text without its heading.
+	*
+	* @remarks
+	* **Untrimmed, deliberately.** It is exactly the bytes {@link
+	* DocumentSection.bodyRange} describes, so the string and the offsets can
+	* never disagree — a package that publishes a span's offsets and then hands
+	* back a different span is lying about it. Callers that want the tidy form
+	* write `.body.trim()`, visibly.
+	*/
+	get body() {
+		return this.#documentSource.slice(this.bodyRange.offset, this.bodyRange.offset + this.bodyRange.length);
+	}
+};
 const walkTree = (node, depth, visit) => {
 	if (depth > 256) throw new Error(`NestingDepthExceeded: limit ${256} exceeded while walking the document tree`);
 	visit(node);
@@ -90,13 +166,38 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	* only ever sit at the head of `root.children` (the capture fires at most
 	* once, at offset 0), so the tree is the single source of truth and the
 	* accessor can never disagree with it. `undefined` covers both a document
-	* with no frontmatter block and one parsed with the capture toggle off.
+	* with no frontmatter block and one parsed with the capture toggle off —
+	* {@link MarkdownDocument.hasFrontmatterBlock} tells the two apart.
 	*/
 	get frontmatter() {
 		const head = this.root.children[0];
 		return head !== void 0 && head.type === "frontmatter" ? head : void 0;
 	}
 	/**
+	* Whether the source opens with a well-formed frontmatter block —
+	* regardless of how the document was parsed.
+	*
+	* @remarks
+	* The structural signal that disambiguates the `frontmatter` accessor's
+	* `undefined`: capture is opt-in (`MarkdownParseOptions.frontmatter`
+	* defaults off), so a document whose source visibly starts with `---` can
+	* still carry no capture node — spec-correct CommonMark reads the fences as
+	* a thematic break plus content. `frontmatter === undefined` with
+	* `hasFrontmatterBlock === true` means exactly "parsed with capture off";
+	* with `false` it means the source genuinely has no block.
+	*
+	* Derived, not stored: the getter runs the **same** pre-scan the parser
+	* runs when capture is enabled (the closed fence grammar — `---` yaml,
+	* `+++` toml, `---json` json; an unclosed fence is not frontmatter), so it
+	* is `true` exactly when parsing this source with `frontmatter: true`
+	* would produce a capture node, and the two can never drift. Like the
+	* other navigation accessors it recomputes per access — bind it once when
+	* checking repeatedly.
+	*/
+	get hasFrontmatterBlock() {
+		return scanFrontmatter(preprocessLines(this.source), this.source) !== null;
+	}
+	/**
 	* Every heading in the document, in document order, wherever it sits —
 	* including headings nested inside blockquotes and list items.
 	*
@@ -145,19 +246,68 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 				}
 			}
 			const start = block.position.start.offset;
-			sections.push({
+			const bodyStart = block.position.end.offset;
+			sections.push(new DocumentSection({
 				heading: block,
 				depth: block.depth,
 				range: MarkdownRange.make({
 					offset: start,
 					length: boundary - start
 				}),
-				children: blocks.slice(index + 1, end).filter((child) => child.type !== "frontmatter")
-			});
+				children: blocks.slice(index + 1, end).filter((child) => child.type !== "frontmatter"),
+				text: phrasingText(block.children),
+				bodyRange: MarkdownRange.make({
+					offset: bodyStart,
+					length: Math.max(0, boundary - bodyStart)
+				}),
+				documentSource: this.source
+			}));
 		}
 		return sections;
 	}
 	/**
+	* The first section in document order, optionally restricted by heading
+	* depth.
+	*
+	* @remarks
+	* `firstSection({ depth: 2 })` is "the newest entry" for a changelog whose
+	* releases are H2s under an H1 title. Like the other navigation accessors
+	* this recomputes {@link MarkdownDocument.sections}; a caller scanning one
+	* document repeatedly should bind `document.sections` once instead.
+	*
+	* @param options - Depth restriction.
+	* @returns The first matching section, or `undefined`.
+	*/
+	firstSection(options) {
+		const depth = options?.depth;
+		return this.sections.find((section) => depth === void 0 || section.depth === depth);
+	}
+	/**
+	* The first section whose heading matches, in document order.
+	*
+	* @remarks
+	* A **string matches the trimmed heading text exactly** — never a substring.
+	* That is a deliberate refusal of the obvious convenience: `"1.2.3"` would
+	* otherwise match a `## 1.2.30` heading, and in a changelog (where `1.2.30`
+	* sorts newer and therefore sits *earlier*) that silently publishes the
+	* wrong release. A `RegExp` is tested against the same trimmed text, and its
+	* `lastIndex` is reset first so a `/g/` pattern cannot skip sections. A
+	* predicate receives the raw {@link DocumentSection.text} plus the section
+	* itself and decides freely.
+	*
+	* @param match - A string, a RegExp, or a predicate.
+	* @param options - Depth restriction, applied before matching.
+	* @returns The first matching section, or `undefined`.
+	*/
+	sectionByHeading(match, options) {
+		const depth = options?.depth;
+		const matches = typeof match === "string" ? (section) => section.text.trim() === match : match instanceof RegExp ? (section) => {
+			match.lastIndex = 0;
+			return match.test(section.text.trim());
+		} : (section) => match(section.text, section);
+		return this.sections.find((section) => (depth === void 0 || section.depth === depth) && matches(section));
+	}
+	/**
 	* Every link-bearing node in the document, in document order: links,
 	* images, definitions, and the reference forms resolved through the
 	* definition index.
@@ -245,4 +395,4 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 };
 
 //#endregion
-export { MarkdownDocument };
+export { DocumentSection, MarkdownDocument };

package/MarkdownFormat.js

@@ -5,6 +5,19 @@ import { Effect, Result, Schema } from "effect";
 
 //#region src/MarkdownFormat.ts
 /**
+* The two ways CommonMark spells a code block: `fenced` (a backtick or tilde
+* fence) and `indented` (four-space indentation).
+*
+* @remarks
+* A formatting target for {@link MarkdownFormattingOptions}, not a node
+* fidelity field: on a {@link Code} node the two spellings are told apart by
+* the presence or absence of `fenceChar`/`fenceLength`, and a language-less
+* node with neither serializes as an **indented** block by default.
+*
+* @public
+*/
+const CodeBlockStyle = Schema.Literals(["fenced", "indented"]);
+/**
 * Options controlling formatting: which concrete-syntax markers to normalize,
 * plus the parse knobs (`dialect`, `frontmatter`) the formatter parses the
 * source with (same defaults as `Markdown.parse`). Every marker option is
@@ -12,7 +25,25 @@ import { Effect, Result, Schema } from "effect";
 *
 * Day-one scope is marker normalization only — heading style, bullet
 * character, emphasis/strong marker, fence character, thematic-break
-* character. Content is never rewritten, rewrapped or reflowed.
+* character, code-block style. Content is never rewritten, rewrapped or
+* reflowed.
+*
+* @remarks
+* `codeBlockStyle` is the opt-in that converts between the two code-block
+* spellings for **language-less** blocks (a block with a `lang` has no
+* indented spelling and is never touched). It exists because the default
+* surprises: absent this option, a language-less code block keeps its
+* spelling — and a language-less {@link Code} node with no explicit
+* `fenceChar` **serializes as an indented block** through
+* `Markdown.stringify`. `"fenced"` rewrites indented blocks to fences (the
+* fence character follows `fenceChar` when also set, backtick otherwise);
+* `"indented"` rewrites language-less fences to indented form where provably
+* safe. Like every other option, hazardous conversions are skipped, never
+* attempted: both directions apply to root-level, flush-left blocks only,
+* and the `"indented"` direction additionally skips blocks whose indented
+* spelling would lazily continue a paragraph, be absorbed into a preceding
+* list or footnote definition, merge with an adjacent code block, or fail
+* representability (empty, or blank first/last lines).
 *
 * @public
 */
@@ -23,7 +54,8 @@ var MarkdownFormattingOptions = class extends Schema.Class("MarkdownFormattingOp
 	bulletChar: Schema.optionalKey(BulletChar),
 	emphasisChar: Schema.optionalKey(EmphasisChar),
 	fenceChar: Schema.optionalKey(FenceChar),
-	thematicBreakChar: Schema.optionalKey(ThematicBreakChar)
+	thematicBreakChar: Schema.optionalKey(ThematicBreakChar),
+	codeBlockStyle: Schema.optionalKey(CodeBlockStyle)
 }) {};
 /**
 * Error codes `MarkdownFormat.modify` can fail with.
@@ -193,6 +225,51 @@ const formatFence = (source, emit, node, target) => {
 	while (end - closeLength > start + openLength && source[end - closeLength - 1] === fidelity) closeLength++;
 	if (closeLength >= 3) emit.push(node, end - closeLength, closeLength, target.repeat(newLength));
 };
+/** A line that is empty or holds only spaces and tabs. */
+const BLANK_LINE = /^[ \t]*$/;
+/** Whether a sibling is a code block with no info string (either spelling). */
+const isLanguagelessCode = (node) => node.type === "code" && node.lang === void 0 && node.meta === void 0;
+/**
+* Convert a language-less code block toward the requested style. Returns
+* whether a whole-block conversion edit was emitted, so the caller can keep
+* `formatFence` off a span this conversion already rewrote.
+*
+* Both directions are whole-block rewrites, so both are restricted to
+* root-level, flush-left blocks — a container's continuation-line prefix
+* (`> `, list indentation) is not reproducible by a single splice. The
+* indented direction carries the re-parse hazards an indented block is
+* subject to and skips each one: it cannot follow a non-blank line (lazy
+* paragraph continuation), a list or footnote definition absorbs it as item
+* continuation, an adjacent language-less code block would merge with it
+* across the blank line, and an empty value or one with blank first/last
+* lines (or interior whitespace-only lines, which blankness would erase) has
+* no indented spelling at all.
+*/
+const formatCodeBlockStyle = (source, emit, node, parent, siblings, index, target, fenceChar) => {
+	if (node.lang !== void 0 || node.meta !== void 0) return false;
+	if (parent === void 0 || parent.type !== "root") return false;
+	const { start, end } = spanOf(node);
+	if (lineStartOf(source, start) !== start) return false;
+	const value = node.value.endsWith("\n") ? node.value.slice(0, -1) : node.value;
+	if (target === "fenced") {
+		if (node.fenceChar !== void 0) return false;
+		const char = fenceChar ?? "`";
+		const fence = char.repeat(Math.max(3, longestRun(value, char) + 1));
+		emit.push(node, start, end - start, `${fence}\n${value}\n${fence}`);
+		return true;
+	}
+	if (node.fenceChar === void 0) return false;
+	const lines = value === "" ? [] : value.split("\n");
+	if (lines.length === 0 || BLANK_LINE.test(lines[0]) || BLANK_LINE.test(lines[lines.length - 1])) return false;
+	if (lines.some((line) => line !== "" && BLANK_LINE.test(line))) return false;
+	if (!previousLineBlank(source, start)) return false;
+	const previous = index > 0 ? siblings[index - 1] : void 0;
+	const next = index + 1 < siblings.length ? siblings[index + 1] : void 0;
+	if (previous !== void 0 && (previous.type === "list" || previous.type === "footnoteDefinition")) return false;
+	if (previous !== void 0 && isLanguagelessCode(previous) || next !== void 0 && isLanguagelessCode(next)) return false;
+	emit.push(node, start, end - start, lines.map((line) => line === "" ? "" : `    ${line}`).join("\n"));
+	return true;
+};
 const FLOW_TYPES = /* @__PURE__ */ new Set([
 	"blockquote",
 	"code",
@@ -279,12 +356,18 @@ var MarkdownFormat = class MarkdownFormat {
 	/**
 	* Compute marker-normalization edits per the requested
 	* {@link MarkdownFormattingOptions}: heading style, bullet character,
-	* emphasis/strong marker, fence character and thematic-break character,
-	* each only where the node's concrete syntax differs from the target and
-	* the rewrite is provably safe. Content is never touched. `range`
-	* restricts edits to the nodes intersecting it (the owning-node
-	* intersection posture, matching toml). Non-mutating — apply with
-	* `MarkdownEdit.applyAll` (or use {@link MarkdownFormat.formatToString}).
+	* emphasis/strong marker, fence character, thematic-break character and
+	* code-block style, each only where the node's concrete syntax differs
+	* from the target and the rewrite is provably safe. Content is never
+	* touched. `range` restricts edits to the nodes intersecting it (the
+	* owning-node intersection posture, matching toml). Non-mutating — apply
+	* with `MarkdownEdit.applyAll` (or use
+	* {@link MarkdownFormat.formatToString}).
+	*
+	* Note the code-block default: absent `codeBlockStyle`, a language-less
+	* code block keeps whichever spelling it has — `fenceChar` alone
+	* normalizes existing fences and deliberately leaves indented blocks
+	* indented.
 	*/
 	static format(text, range, options) {
 		const parsed = Markdown.parseResult(text, MarkdownParseOptions.make({
@@ -293,12 +376,14 @@ var MarkdownFormat = class MarkdownFormat {
 		}));
 		if (Result.isFailure(parsed)) return [];
 		const emit = new FormatEmitter(text);
-		walk(parsed.success, void 0, [], 0, (node, _parent, siblings, index) => {
+		walk(parsed.success, void 0, [], 0, (node, parent, siblings, index) => {
 			if (options?.thematicBreakChar !== void 0 && node.type === "thematicBreak") formatThematicBreak(text, emit, node, options.thematicBreakChar);
 			if (options?.headingStyle !== void 0 && node.type === "heading") formatHeading(text, emit, node, options.headingStyle);
 			if (options?.bulletChar !== void 0 && node.type === "list") formatList(text, emit, node, siblings, index, options.bulletChar);
 			if (options?.emphasisChar !== void 0 && isEmphasisLike(node)) formatEmphasis(text, emit, node, siblings, index, options.emphasisChar);
-			if (options?.fenceChar !== void 0 && node.type === "code") formatFence(text, emit, node, options.fenceChar);
+			if (node.type === "code") {
+				if (!(options?.codeBlockStyle !== void 0 && formatCodeBlockStyle(text, emit, node, parent, siblings, index, options.codeBlockStyle, options.fenceChar)) && options?.fenceChar !== void 0) formatFence(text, emit, node, options.fenceChar);
+			}
 		});
 		return (range === void 0 ? emit.edits : emit.edits.filter((edit) => Math.max(edit.nodeStart, range.offset) <= Math.min(edit.nodeEnd, range.offset + range.length))).map((edit) => MarkdownEdit.make({
 			offset: edit.offset,
@@ -377,4 +462,4 @@ var MarkdownFormat = class MarkdownFormat {
 };
 
 //#endregion
-export { MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode };
+export { CodeBlockStyle, MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode };

package/MarkdownNode.js

@@ -347,6 +347,12 @@ var ThematicBreak = class extends Schema.Class("ThematicBreak")({
 * for fenced blocks and **absent for indented blocks** — their absence is how
 * the two are told apart on the way back out.
 *
+* A consequence worth knowing before it surprises: a language-less `Code`
+* node with no explicit `fenceChar` **serializes as an indented block**
+* through `Markdown.stringify`. To get a fence, set `fenceChar` on the node
+* (or a `lang`, which forces one), or format the emitted source with
+* `MarkdownFormattingOptions.codeBlockStyle: "fenced"`.
+*
 * @public
 */
 var Code = class extends Schema.Class("Code")({

package/README.md

@@ -106,7 +106,7 @@ Effect.runPromise(program).then(console.log);
 
 `find` walks the tree in document pre-order and returns the document's own node, so the match feeds `modify` by identity. Replacements are literal strings or node fragments, and both render through the canonical stringifier, so a modified document re-parses cleanly by construction — you cannot splice in raw markdown that reopens a fence or breaks a table.
 
-`MarkdownFormat.format` handles the other half: conservative marker normalization, never content rewriting. It converts heading style, bullet character, emphasis marker, fence character and thematic-break character, and skips any conversion that would not be safe rather than attempting it cleverly:
+`MarkdownFormat.format` handles the other half: conservative marker normalization, never content rewriting. It converts heading style, bullet character, emphasis marker, fence character, thematic-break character and code-block style, and skips any conversion that would not be safe rather than attempting it cleverly:
 
 ```ts
 import { MarkdownFormat, MarkdownFormattingOptions } from "@effected/markdown";
@@ -136,6 +136,8 @@ console.log(MarkdownFormat.format(source, undefined, options));
 
 `format` is pure and total, and the edits are non-mutating data — hand them to `MarkdownEdit.applyAll`, or send them to an editor as a text-edit payload.
 
+`codeBlockStyle` is the option to know about before you hit its default: absent it, a language-less code block keeps whichever spelling it already has, and a language-less `Code` node with no `fenceChar` serializes as an *indented* block. `"fenced"` rewrites indented blocks to fences, `"indented"` goes the other way where the result provably re-parses the same, and both directions apply to root-level flush-left blocks only. A block with a language has no indented spelling and is never touched.
+
 ## Frontmatter
 
 Frontmatter capture is opt-in, because enabling it changes how a document opening with `---` parses: CommonMark reads `---\ntitle: x\n---` as a thematic break and a setext heading, and that spec-conformant reading holds unless you ask for something else. Turn it on and compose your schema with a codec for typed gray-matter parity:
@@ -166,6 +168,8 @@ Effect.runPromise(program).then(console.log);
 
 Each stage fails typed and separately: no capture is a `FrontmatterMissingError` (catch the tag for optional semantics), a codec handed the wrong fence is a `FrontmatterFormatMismatchError`, unparseable content is a `FrontmatterDecodeError` carrying the format package's own positioned failure structurally, and schema-invalid data is a `FrontmatterValidationError` carrying the structured issue tree rather than a stringified rendering.
 
+Because capture is opt-in, "there is no frontmatter" has two meanings, and `FrontmatterMissingError.reason` tells them apart: `"absent"` when the source genuinely has no block, `"captureDisabled"` when it opens with one but was parsed with the toggle off — where the fix is a parse option, not a document edit. `MarkdownDocument.hasFrontmatterBlock` answers the same question directly, by re-running the parser's own pre-scan, so the accessor and the error can never disagree.
+
 The three codecs — `YamlFrontmatter` (`---`), `TomlFrontmatter` (`+++`) and `JsonFrontmatter` (`---json`) — are free-standing named exports, one module each, deliberately never collected into a namespace object. Naming one codec is what pulls in its format engine, so a JSON-frontmatter consumer never pays for the yaml parser.
 
 Frontmatter blocks can also describe their own schema. `SchemaResolver.classify` sorts a `$schema` value into a tagged union — `ByUrl`, `ByPath`, `Inline` and `ByName` — and `SchemaResolver.fromRegistry` resolves `ByName` declarations like `skill@2.1.0` against schemas you register. URLs, paths and inline documents are carried as data and never fetched: this is a pure package and it performs no IO.
@@ -192,7 +196,33 @@ Effect.runPromise(program).then(console.log);
 // [ "./CHANGELOG.md", "https://example.com/docs" ]
 ```
 
-`headings` lists every heading wherever it sits, including inside blockquotes and list items. `sections` are delimited by root-level headings only, and each section's range spans its subsections, so the edit layer can splice a whole section out in one edit.
+`headings` lists every heading wherever it sits, including inside blockquotes and list items. `sections` are delimited by root-level headings only, and each section's range spans its subsections, so the edit layer can splice a whole section out in one edit. `firstSection` and `sectionByHeading` find one `DocumentSection` without scanning `sections` yourself — the second matches on an exact trimmed heading string, a `RegExp`, or a predicate, and both accept `{ depth }` to restrict to one heading level:
+
+```ts
+import { MarkdownDocument } from "@effected/markdown";
+import { Effect } from "effect";
+
+const source = `# Changelog
+
+## 1.2.3
+
+Fixed a bug.
+
+## 1.2.2
+
+Initial release.
+`;
+
+const program = Effect.gen(function* () {
+  const doc = yield* MarkdownDocument.parse(source);
+  return doc.sectionByHeading("1.2.3", { depth: 2 })?.body.trim();
+});
+
+Effect.runPromise(program).then(console.log);
+// Fixed a bug.
+```
+
+`DocumentSection.body` is the section without its heading, and it is deliberately untrimmed — exactly the bytes `bodyRange` describes — so callers write `.body.trim()` when they want the tidy form.
 
 For anything the accessors do not cover, `find` and `findAll` walk the whole tree in document pre-order. A string selector matches the node's `type` and narrows the result — `doc.findAll("heading")` is `ReadonlyArray<Heading>`, `doc.find("table")` is `Table | undefined` — and a type-guard predicate narrows the same way. The nodes come back by identity, so `doc.findAll("heading")[1]` addresses the second heading for `MarkdownFormat.modify` without raw child indexing.
 
@@ -234,13 +264,13 @@ if (Result.isSuccess(parsed)) {
 ## Features
 
 - `Markdown` — `parse`/`stringify` as `Effect`s with typed `MarkdownParseError`/`MarkdownStringifyError` channels, the pure `parseResult`/`stringifyResult` twins for synchronous callers, and the `MarkdownFromString` two-way codec.
-- `MarkdownDocument` — source, tree, diagnostics and the link-definition index, plus the derived `headings`, `sections` and `links` accessors, the `find`/`findAll` tree queries over type-narrowed selectors, and the `frontmatter` capture.
+- `MarkdownDocument` — source, tree, diagnostics and the link-definition index, plus the derived `headings`, `sections` and `links` accessors, the `firstSection`/`sectionByHeading` finders over a `DocumentSection` (heading, depth, range, body), the `find`/`findAll` tree queries over type-narrowed selectors, and the `frontmatter` capture with `hasFrontmatterBlock` to tell an absent block from an uncaptured one.
 - The mdast-shaped node classes — the CommonMark types plus GFM's `delete`, `table`, `tableRow`, `tableCell`, `footnoteDefinition`, `footnoteReference` and task-list `checked`, each carrying unist positions with byte offsets and this package's fidelity fields. `position` defaults to the zero-width synthetic sentinel, so a replacement fragment constructs in one line — `Text.make({ value: "shipped" })`.
 - `MarkdownEdit` / `MarkdownRange` (with `applyAll`) — the non-mutating text-edit vocabulary, field-identical to `@effected/jsonc`'s, `@effected/yaml`'s and `@effected/toml`'s.
 - `MarkdownFormat` — `format`/`formatToString` compute conservative marker-normalization edits; `modify`/`modifyToString` replace a node by identity through the canonical stringifier.
 - `MarkdownVisitor` — walk a parsed tree as a lazy `Stream` of `Enter`/`Exit` events with child-index paths and depth.
 - `Mdast` — `toMdast` projects to plain mdast JSON; `fromMdast`/`fromMdastResult` admit a foreign mdast tree with validation.
-- `MarkdownFrontmatter.schema` plus the `YamlFrontmatter`, `TomlFrontmatter` and `JsonFrontmatter` codecs — typed frontmatter decoding over optional per-format peers, with four separately catchable failure modes.
+- `MarkdownFrontmatter.schema` plus the `YamlFrontmatter`, `TomlFrontmatter` and `JsonFrontmatter` codecs — typed frontmatter decoding over optional per-format peers, with four separately catchable failure modes and a `FrontmatterMissingReason` on the absent one.
 - `SchemaResolver` — classify a frontmatter `$schema` declaration into `ByUrl`/`ByPath`/`Inline`/`ByName` and resolve names against a registry, with no IO and no dependencies.
 - `MarkdownDiagnostic` — the structured diagnostic (`code`, `message`, `offset`, `length`, `line`, `character`) every typed error carries, shaped identically to the sibling packages'.
 

package/index.d.ts

@@ -388,6 +388,12 @@ declare const Code_base: Schema.Class<Code, Schema.Struct<{
  * for fenced blocks and **absent for indented blocks** — their absence is how
  * the two are told apart on the way back out.
  *
+ * A consequence worth knowing before it surprises: a language-less `Code`
+ * node with no explicit `fenceChar` **serializes as an indented block**
+ * through `Markdown.stringify`. To get a fence, set `fenceChar` on the node
+ * (or a `lang`, which forces one), or format the emitted source with
+ * `MarkdownFormattingOptions.codeBlockStyle: "fenced"`.
+ *
  * @public
  */
 declare class Code extends Code_base {}
@@ -808,7 +814,9 @@ declare const MarkdownParseOptions_base: Schema.Class<MarkdownParseOptions, Sche
  * spec-conformant reading must hold unless a consumer opts in. Enabled, the
  * engine captures `---`/`+++`/`---json` blocks at offset 0 into a raw
  * `Frontmatter` head node — decoding it is the frontmatter codec modules'
- * job.
+ * job. Parsed with the toggle off, such a document reports no frontmatter —
+ * `MarkdownDocument.hasFrontmatterBlock` tells "no block in the source"
+ * apart from "parsed with capture off".
  *
  * @public
  */
@@ -917,10 +925,14 @@ declare class Markdown {
    * @remarks
    * Canonical serialization: fidelity fields (marker characters, fence
    * style, heading spelling) win when present; documented canonical
-   * defaults apply when absent. The output re-parses to a render-equivalent
-   * document — the corpus-pinned contract — but is not a byte-level
-   * round-trip of any original source; surgical editing goes through the
-   * offset-splice edit layer instead.
+   * defaults apply when absent. One default surprises: a language-less
+   * `Code` node with no explicit `fenceChar` serializes as an
+   * **indented** code block — set `fenceChar` (or a `lang`) on the node for
+   * a fence, or normalize afterward with
+   * `MarkdownFormattingOptions.codeBlockStyle: "fenced"`. The output
+   * re-parses to a render-equivalent document — the corpus-pinned
+   * contract — but is not a byte-level round-trip of any original source;
+   * surgical editing goes through the offset-splice edit layer instead.
    *
    * Failure is rare by design, symmetric with parse: only a hardening-guard
    * trip on a tree nesting past the depth cap fails, and only synthesized
@@ -1049,14 +1061,88 @@ interface DocumentHeading {
  * `children` include its subsections — the list is flat, in document order,
  * with `depth` carrying the hierarchy.
  *
+ * Instances come from {@link MarkdownDocument.sections} and the two finders;
+ * there is no reason to construct one directly.
+ *
  * @public
  */
-interface DocumentSection {
+declare class DocumentSection {
+  #private;
+  /** The heading that opens the section. */
   readonly heading: Heading;
+  /** The heading's depth, and the section's. */
   readonly depth: HeadingDepth;
+  /** The whole section including its heading — spliceable by `MarkdownEdit`. */
   readonly range: MarkdownRange;
+  /** The root-level blocks after the heading, subsections included. */
   readonly children: ReadonlyArray<FlowContent>;
+  /**
+   * The heading's plain-text content.
+   *
+   * @remarks
+   * The same derivation as {@link DocumentHeading.text}: text and inline-code
+   * values concatenated, image `alt` where present, a hard break as one space,
+   * nothing for raw HTML or footnote references. So `## **1.2.3**` reads
+   * `1.2.3`.
+   */
+  readonly text: string;
+  /**
+   * The section WITHOUT its heading: from the heading's end offset to the
+   * section's end.
+   *
+   * @remarks
+   * This is the span a "give me the release notes under this version" reader
+   * wants, and the one that is fiddly to derive by hand.
+   */
+  readonly bodyRange: MarkdownRange;
+  constructor(options: {
+    readonly heading: Heading;
+    readonly depth: HeadingDepth;
+    readonly range: MarkdownRange;
+    readonly children: ReadonlyArray<FlowContent>;
+    readonly text: string;
+    readonly bodyRange: MarkdownRange;
+    readonly documentSource: string;
+  });
+  /** The section's source text, heading included. */
+  get source(): string;
+  /**
+   * The section's source text without its heading.
+   *
+   * @remarks
+   * **Untrimmed, deliberately.** It is exactly the bytes {@link
+   * DocumentSection.bodyRange} describes, so the string and the offsets can
+   * never disagree — a package that publishes a span's offsets and then hands
+   * back a different span is lying about it. Callers that want the tidy form
+   * write `.body.trim()`, visibly.
+   */
+  get body(): string;
+}
+/**
+ * Narrowing options for {@link MarkdownDocument.firstSection} and
+ * {@link MarkdownDocument.sectionByHeading}.
+ *
+ * @public
+ */
+interface SectionQueryOptions {
+  /**
+   * Restrict to sections opened by a heading of exactly this depth.
+   *
+   * @remarks
+   * Equality, not a maximum: `{ depth: 2 }` is "the H2 sections", which is the
+   * changelog idiom. A depth *range* is a different question and belongs in a
+   * predicate.
+   */
+  readonly depth?: HeadingDepth;
 }
+/**
+ * How {@link MarkdownDocument.sectionByHeading} decides a section matches: an
+ * exact trimmed-text string, a `RegExp`, or a predicate over the text and the
+ * section.
+ *
+ * @public
+ */
+type SectionHeadingMatch = string | RegExp | ((text: string, section: DocumentSection) => boolean);
 /**
  * The node types {@link MarkdownDocument.links} collects: the nodes that
  * carry an outbound URL themselves ({@link Link}, {@link Image},
@@ -1128,9 +1214,32 @@ declare class MarkdownDocument extends MarkdownDocument_base {
    * only ever sit at the head of `root.children` (the capture fires at most
    * once, at offset 0), so the tree is the single source of truth and the
    * accessor can never disagree with it. `undefined` covers both a document
-   * with no frontmatter block and one parsed with the capture toggle off.
+   * with no frontmatter block and one parsed with the capture toggle off —
+   * {@link MarkdownDocument.hasFrontmatterBlock} tells the two apart.
    */
   get frontmatter(): Frontmatter | undefined;
+  /**
+   * Whether the source opens with a well-formed frontmatter block —
+   * regardless of how the document was parsed.
+   *
+   * @remarks
+   * The structural signal that disambiguates the `frontmatter` accessor's
+   * `undefined`: capture is opt-in (`MarkdownParseOptions.frontmatter`
+   * defaults off), so a document whose source visibly starts with `---` can
+   * still carry no capture node — spec-correct CommonMark reads the fences as
+   * a thematic break plus content. `frontmatter === undefined` with
+   * `hasFrontmatterBlock === true` means exactly "parsed with capture off";
+   * with `false` it means the source genuinely has no block.
+   *
+   * Derived, not stored: the getter runs the **same** pre-scan the parser
+   * runs when capture is enabled (the closed fence grammar — `---` yaml,
+   * `+++` toml, `---json` json; an unclosed fence is not frontmatter), so it
+   * is `true` exactly when parsing this source with `frontmatter: true`
+   * would produce a capture node, and the two can never drift. Like the
+   * other navigation accessors it recomputes per access — bind it once when
+   * checking repeatedly.
+   */
+  get hasFrontmatterBlock(): boolean;
   /**
    * Every heading in the document, in document order, wherever it sits —
    * including headings nested inside blockquotes and list items.
@@ -1154,6 +1263,38 @@ declare class MarkdownDocument extends MarkdownDocument_base {
    * boundary heading's start, or to the end of the source.
    */
   get sections(): ReadonlyArray<DocumentSection>;
+  /**
+   * The first section in document order, optionally restricted by heading
+   * depth.
+   *
+   * @remarks
+   * `firstSection({ depth: 2 })` is "the newest entry" for a changelog whose
+   * releases are H2s under an H1 title. Like the other navigation accessors
+   * this recomputes {@link MarkdownDocument.sections}; a caller scanning one
+   * document repeatedly should bind `document.sections` once instead.
+   *
+   * @param options - Depth restriction.
+   * @returns The first matching section, or `undefined`.
+   */
+  firstSection(options?: SectionQueryOptions): DocumentSection | undefined;
+  /**
+   * The first section whose heading matches, in document order.
+   *
+   * @remarks
+   * A **string matches the trimmed heading text exactly** — never a substring.
+   * That is a deliberate refusal of the obvious convenience: `"1.2.3"` would
+   * otherwise match a `## 1.2.30` heading, and in a changelog (where `1.2.30`
+   * sorts newer and therefore sits *earlier*) that silently publishes the
+   * wrong release. A `RegExp` is tested against the same trimmed text, and its
+   * `lastIndex` is reset first so a `/g/` pattern cannot skip sections. A
+   * predicate receives the raw {@link DocumentSection.text} plus the section
+   * itself and decides freely.
+   *
+   * @param match - A string, a RegExp, or a predicate.
+   * @param options - Depth restriction, applied before matching.
+   * @returns The first matching section, or `undefined`.
+   */
+  sectionByHeading(match: SectionHeadingMatch, options?: SectionQueryOptions): DocumentSection | undefined;
   /**
    * Every link-bearing node in the document, in document order: links,
    * images, definitions, and the reference forms resolved through the
@@ -1335,18 +1476,46 @@ interface FrontmatterCodec {
   /** Serialize data into a frontmatter body, without fences. */
   readonly encode: (data: unknown) => Effect.Effect<string, FrontmatterEncodeError>;
 }
-declare const FrontmatterMissingError_base: Schema.Class<FrontmatterMissingError, Schema.TaggedStruct<"FrontmatterMissingError", {}>, import("effect/Cause").YieldableError>;
+/**
+ * Why a frontmatter decoder found no capture on a document.
+ *
+ * @remarks
+ * `"absent"` — the source genuinely has no frontmatter block.
+ * `"captureDisabled"` — the source opens with a well-formed frontmatter
+ * block, but the document carries no capture node: it was parsed without
+ * `frontmatter: true` (the toggle defaults off), so spec-correct CommonMark
+ * read the fences as ordinary content.
+ *
+ * @public
+ */
+declare const FrontmatterMissingReason: Schema.Literals<readonly ["absent", "captureDisabled"]>;
+/**
+ * Why a frontmatter decoder found no capture on a document.
+ *
+ * @public
+ */
+type FrontmatterMissingReason = typeof FrontmatterMissingReason.Type;
+declare const FrontmatterMissingError_base: Schema.Class<FrontmatterMissingError, Schema.TaggedStruct<"FrontmatterMissingError", {
+  /** Why there is no capture: no block at all, or capture left off. */
+  readonly reason: Schema.Literals<readonly ["absent", "captureDisabled"]>;
+}>, import("effect/Cause").YieldableError>;
 /**
  * Indicates that a document handed to a frontmatter decoder carries no
  * frontmatter capture.
  *
  * @remarks
- * Raised when the document genuinely has no frontmatter block — including
- * when it has one in the source but was parsed with the capture toggle off
- * (`MarkdownParseOptions.frontmatter` defaults to `false`). Cause-free: there
- * is nothing to diagnose beyond the absence itself. Consumers wanting
- * optional semantics can `Effect.catchTag("FrontmatterMissingError", ...)`
- * to a default.
+ * `reason` distinguishes the two ways this happens: `"absent"` when the
+ * source genuinely has no frontmatter block, `"captureDisabled"` when the
+ * source opens with one but the document was parsed with the capture toggle
+ * off (`MarkdownParseOptions.frontmatter` defaults to `false`) — the fix
+ * there is parsing with `frontmatter: true`, not editing the document. The
+ * discriminant is computed from the same structural signal
+ * `MarkdownDocument.hasFrontmatterBlock` exposes, so the error and the
+ * accessor can never disagree.
+ *
+ * Cause-free: there is nothing to diagnose beyond the absence itself.
+ * Consumers wanting optional semantics can
+ * `Effect.catchTag("FrontmatterMissingError", ...)` to a default.
  *
  * @public
  */
@@ -1410,7 +1579,8 @@ declare class MarkdownFrontmatter {
    * The decoder reads the document's frontmatter capture (parse with
    * `frontmatter: true` — the toggle defaults off), decodes its raw value
    * through the codec, then validates the data against `schema`. Each stage
-   * fails typed: no capture is {@link FrontmatterMissingError}, a
+   * fails typed: no capture is {@link FrontmatterMissingError} (its `reason`
+   * says whether the block is genuinely absent or capture was left off), a
    * wrong-format codec is {@link FrontmatterFormatMismatchError}, unparseable
    * content is {@link FrontmatterDecodeError}, and schema-invalid data is
    * {@link FrontmatterValidationError} carrying the structured issue.
@@ -1760,6 +1930,25 @@ type MarkdownRangeLike = MarkdownRange | {
   readonly offset: number;
   readonly length: number;
 };
+/**
+ * The two ways CommonMark spells a code block: `fenced` (a backtick or tilde
+ * fence) and `indented` (four-space indentation).
+ *
+ * @remarks
+ * A formatting target for {@link MarkdownFormattingOptions}, not a node
+ * fidelity field: on a {@link Code} node the two spellings are told apart by
+ * the presence or absence of `fenceChar`/`fenceLength`, and a language-less
+ * node with neither serializes as an **indented** block by default.
+ *
+ * @public
+ */
+declare const CodeBlockStyle: Schema.Literals<readonly ["fenced", "indented"]>;
+/**
+ * The union of all code-block-style string literals.
+ *
+ * @public
+ */
+type CodeBlockStyle = typeof CodeBlockStyle.Type;
 declare const MarkdownFormattingOptions_base: Schema.Class<MarkdownFormattingOptions, Schema.Struct<{
   readonly dialect: Schema.optionalKey<Schema.Literals<readonly ["commonmark", "gfm"]>>;
   readonly frontmatter: Schema.optionalKey<Schema.Boolean>;
@@ -1768,6 +1957,7 @@ declare const MarkdownFormattingOptions_base: Schema.Class<MarkdownFormattingOpt
   readonly emphasisChar: Schema.optionalKey<Schema.Literals<readonly ["*", "_"]>>;
   readonly fenceChar: Schema.optionalKey<Schema.Literals<readonly ["`", "~"]>>;
   readonly thematicBreakChar: Schema.optionalKey<Schema.Literals<readonly ["-", "_", "*"]>>;
+  readonly codeBlockStyle: Schema.optionalKey<Schema.Literals<readonly ["fenced", "indented"]>>;
 }>, {}>;
 /**
  * Options controlling formatting: which concrete-syntax markers to normalize,
@@ -1777,7 +1967,25 @@ declare const MarkdownFormattingOptions_base: Schema.Class<MarkdownFormattingOpt
  *
  * Day-one scope is marker normalization only — heading style, bullet
  * character, emphasis/strong marker, fence character, thematic-break
- * character. Content is never rewritten, rewrapped or reflowed.
+ * character, code-block style. Content is never rewritten, rewrapped or
+ * reflowed.
+ *
+ * @remarks
+ * `codeBlockStyle` is the opt-in that converts between the two code-block
+ * spellings for **language-less** blocks (a block with a `lang` has no
+ * indented spelling and is never touched). It exists because the default
+ * surprises: absent this option, a language-less code block keeps its
+ * spelling — and a language-less {@link Code} node with no explicit
+ * `fenceChar` **serializes as an indented block** through
+ * `Markdown.stringify`. `"fenced"` rewrites indented blocks to fences (the
+ * fence character follows `fenceChar` when also set, backtick otherwise);
+ * `"indented"` rewrites language-less fences to indented form where provably
+ * safe. Like every other option, hazardous conversions are skipped, never
+ * attempted: both directions apply to root-level, flush-left blocks only,
+ * and the `"indented"` direction additionally skips blocks whose indented
+ * spelling would lazily continue a paragraph, be absorbed into a preceding
+ * list or footnote definition, merge with an adjacent code block, or fail
+ * representability (empty, or blank first/last lines).
  *
  * @public
  */
@@ -1835,12 +2043,18 @@ declare class MarkdownFormat {
   /**
    * Compute marker-normalization edits per the requested
    * {@link MarkdownFormattingOptions}: heading style, bullet character,
-   * emphasis/strong marker, fence character and thematic-break character,
-   * each only where the node's concrete syntax differs from the target and
-   * the rewrite is provably safe. Content is never touched. `range`
-   * restricts edits to the nodes intersecting it (the owning-node
-   * intersection posture, matching toml). Non-mutating — apply with
-   * `MarkdownEdit.applyAll` (or use {@link MarkdownFormat.formatToString}).
+   * emphasis/strong marker, fence character, thematic-break character and
+   * code-block style, each only where the node's concrete syntax differs
+   * from the target and the rewrite is provably safe. Content is never
+   * touched. `range` restricts edits to the nodes intersecting it (the
+   * owning-node intersection posture, matching toml). Non-mutating — apply
+   * with `MarkdownEdit.applyAll` (or use
+   * {@link MarkdownFormat.formatToString}).
+   *
+   * Note the code-block default: absent `codeBlockStyle`, a language-less
+   * code block keeps whichever spelling it has — `fenceChar` alone
+   * normalizes existing fences and deliberately leaves indented blocks
+   * indented.
    */
   static format(text: string, range?: MarkdownRangeLike, options?: MarkdownFormattingOptions): ReadonlyArray<MarkdownEdit>;
   /**
@@ -2186,5 +2400,5 @@ declare const TomlFrontmatter: FrontmatterCodec;
  */
 declare const YamlFrontmatter: FrontmatterCodec;
 //#endregion
-export { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, type DocumentHeading, type DocumentLink, type DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, type FrontmatterCodec, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, type FrontmatterResolveError, type FrontmatterSchemaError, type FrontmatterSchemaResolver, FrontmatterValidationError, type FrontmatterWriteError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, type LinkBearingNode, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, type MarkdownNodeOfType, type MarkdownNodeType, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, type MarkdownPath, MarkdownRange, type MarkdownRangeLike, type MarkdownSegment, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, type MdastNode, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
+export { Blockquote, Break, BreakStyle, BulletChar, Code, CodeBlockStyle, Definition, Delete, type DocumentHeading, type DocumentLink, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, type FrontmatterCodec, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, type FrontmatterResolveError, type FrontmatterSchemaError, type FrontmatterSchemaResolver, FrontmatterValidationError, type FrontmatterWriteError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, type LinkBearingNode, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, type MarkdownNodeOfType, type MarkdownNodeType, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, type MarkdownPath, MarkdownRange, type MarkdownRangeLike, type MarkdownSegment, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, type MdastNode, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, type SectionHeadingMatch, type SectionQueryOptions, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,15 +1,15 @@
 import { MarkdownEdit, MarkdownRange } from "./MarkdownEdit.js";
 import { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterFormat, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, MarkdownNode, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar } from "./MarkdownNode.js";
-import { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterValidationError, MarkdownFrontmatter } from "./Frontmatter.js";
+import { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterValidationError, MarkdownFrontmatter } from "./Frontmatter.js";
 import { SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError } from "./FrontmatterResolver.js";
 import { JsonFrontmatter } from "./JsonFrontmatter.js";
 import { MarkdownDiagnostic, MarkdownParseErrorCode } from "./MarkdownDiagnostic.js";
 import { Markdown, MarkdownDialect, MarkdownParseError, MarkdownParseOptions, MarkdownStringifyError } from "./Markdown.js";
-import { MarkdownDocument } from "./MarkdownDocument.js";
-import { MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode } from "./MarkdownFormat.js";
+import { DocumentSection, MarkdownDocument } from "./MarkdownDocument.js";
+import { CodeBlockStyle, MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode } from "./MarkdownFormat.js";
 import { MarkdownVisitor, MarkdownVisitorEvent } from "./MarkdownVisitor.js";
 import { Mdast, MdastDecodeError } from "./Mdast.js";
 import { TomlFrontmatter } from "./TomlFrontmatter.js";
 import { YamlFrontmatter } from "./YamlFrontmatter.js";
 
-export { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterValidationError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, MarkdownRange, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
+export { Blockquote, Break, BreakStyle, BulletChar, Code, CodeBlockStyle, Definition, Delete, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterValidationError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, MarkdownRange, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/markdown",
-	"version": "0.2.5",
+	"version": "0.4.0",
 	"private": false,
 	"description": "CommonMark and GFM markdown parse, edit and transform schemas for Effect",
 	"keywords": [