@remigius42/morg 0.4.0 → 0.5.0

package/README.md

@@ -2,7 +2,8 @@
 
 Copyright 2026 [Andreas Remigius Schmidt](https://github.com/remigius42)
 
-[![Version](https://img.shields.io/github/v/tag/remigius42/morg?label=version)](https://github.com/remigius42/morg/blob/main/CHANGELOG.md)
+[![npm](https://img.shields.io/npm/v/%40remigius42%2Fmorg?label=npm)](https://www.npmjs.com/package/@remigius42/morg)
+[![Changelog](https://img.shields.io/github/v/tag/remigius42/morg?label=changelog)](https://github.com/remigius42/morg/blob/main/CHANGELOG.md)
 [![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE)
 [![CI](https://github.com/remigius42/morg/actions/workflows/ci.yml/badge.svg)](https://github.com/remigius42/morg/actions/workflows/ci.yml)
 ![Node](https://img.shields.io/badge/node-%3E%3D20-lightgrey.svg)
@@ -15,9 +16,9 @@ Bidirectional **Markdown ↔ Org-mode** converter, built on the
 [uniorg](https://github.com/rasendubi/uniorg) for Org).
 
 morg treats Org as a canonical plain-text format and Markdown (Obsidian,
-generic) as the interop surface. Dialect conventions — such as
-[Logseq](https://docs.logseq.com/)'s `heading::` properties and outline nesting
-— are supported via presets.
+generic) as the interop surface. Dialect conventions, such as
+[Logseq](https://docs.logseq.com/)'s `heading::` properties and outline
+nesting, are supported via presets.
 
 ## Round-trip convergence
 
@@ -50,7 +51,7 @@ color schemes.
 ### Web UI
 
 Try morg without installing anything at
-[morg.binarypoetry.ch](https://morg.binarypoetry.ch) — all conversion
+[morg.binarypoetry.ch](https://morg.binarypoetry.ch). All conversion
 happens in your browser, nothing is uploaded (see [ADR
 0003](docs/adr/0003-client-side-web-ui-on-github-pages.md)). The
 chrome-less embed page (`/embed.html`, optionally with
@@ -67,13 +68,13 @@ addEventListener("message", event => {
 })
 ```
 
-Give the frame at least 768px of width if you can — below that the
+Give the frame at least 768px of width if you can; below that the
 input and output stack, which doubles its height. `allow="clipboard-write"`
 lets the Copy button use the clipboard rather than falling back to
 selecting the output.
 
 Besides pasting, a file can be opened with the picker or dropped
-anywhere on the page — a `.toml` lands in the config panel, a document
+anywhere on the page: a `.toml` lands in the config panel, a document
 in the input, and the conversion direction follows the extension. Drop
 both at once and each goes where it belongs; an overlay names what is
 accepted while a drag is in flight, and anything that turns out not to
@@ -100,7 +101,11 @@ npm install --global @remigius42/morg
 ```
 
 ```bash
-# Formats inferred from file extensions
+# Every flag, with examples; also shown for a bare `morg`
+morg --help
+
+# Formats inferred from file extensions; --from and --to take a format
+# name (markdown or org), not a path
 morg --input notes.md --output notes.org
 
 # stdin/stdout with explicit format
@@ -120,8 +125,8 @@ morg --input notes.md --output notes.org --silent
 morg --input notes.md --output notes.org --record-style
 
 # Normalize to canonical form (same format in and out); this
-# canonicalizes — the one-time reformat a first conversion would
-# apply anyway (ADR 0001) — it is not a style formatter like prettier
+# canonicalizes (the one-time reformat a first conversion would apply
+# anyway, ADR 0001); it is not a style formatter like prettier
 morg normalize --input notes.org --output notes.org
 ```
 
@@ -138,8 +143,8 @@ preset = "logseq"
 emphasis = "_" # align with prettier
 ```
 
-The full reference — all sections and compatibility snippets for
-prettier and mdformat — is in
+The full reference, covering all sections and compatibility snippets
+for prettier and mdformat, is in
 [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 
 ### Library
@@ -167,26 +172,26 @@ const logseqOrg = convertMarkdownToOrg(markdown, { preset: logseq() })
 Options (flags accept `boolean` or a per-construct `Record<string, boolean>`):
 
 - `convertMarkdownToOrg(md, { preserveMdisms, interpretHtml, recordStyle,
-preset })` —
+preset })`:
   `preserveMdisms` default `true`; `interpretHtml` (default `false`,
   CLI `--interpret-html`) interprets the HTML vocabulary morg itself
   emits under `useHtml` (bare `<u>`, `<sup>`, `<sub>`, `<dl>`) as
-  native Org constructs — the inverse of `useHtml`: with both enabled
+  native Org constructs, the inverse of `useHtml`: with both enabled
   the round trip is lossless, with `interpretHtml` alone it converges
   away from HTML (cleanup mode); other HTML preserves as usual;
   `recordStyle` (default `false`, CLI `--record-style`) records the
   document-level markdown style as a `#+MORG_MARKDOWN_STYLE:` keyword so the
   round trip restores it (ADR 0004)
 - `convertOrgToMarkdown(org, { preserveOrgisms, useHtml, taskCheckboxes,
-preset })` — `preserveOrgisms` default `true`; `useHtml` (default
+preset })`: `preserveOrgisms` default `true`; `useHtml` (default
   `false`) renders org-only markup as raw HTML (`<u>`, `<sup>`, `<sub>`,
   `<dl>`) instead of keeping it verbatim; `taskCheckboxes` (default
   `false`, CLI `--task-checkboxes`) is a lossy export mode that maps
   bare `TODO`/`DONE` leaf headlines to GFM task items (`- [ ]` /
-  `- [x]`) — headings become list items and do not restore on the
+  `- [x]`); headings become list items and do not restore on the
   return trip; anything with priority, tags or content keeps its
   heading and reports via `onWarning`
-- `logseq({ nestUnderHeadings })` — default `true`; content following a
+- `logseq({ nestUnderHeadings })`: default `true`; content following a
   heading nests as child blocks of that heading: paragraphs become child
   headlines one level deeper (in Logseq org every outline block is a
   headline), other constructs stay in the preceding block's body. The
@@ -199,22 +204,23 @@ preset })` — `preserveOrgisms` default `true`; `useHtml` (default
   fuzzy links `[[page][label]]`, block refs `[label](((uuid)))` ↔
   `[[((uuid))][label]]`, and `^^highlight^^` markup survives verbatim
   (it would otherwise re-parse as superscripts).
-- `obsidian()` — wikilinks `[[Page]]` / `[[Page|alias]]` ↔ org fuzzy links
+- `obsidian()`: wikilinks `[[Page]]` / `[[Page|alias]]` ↔ org fuzzy links
 
 - `normalizeMarkdown(md, { preset })` / `normalizeOrg(org, { preset })`
-  (CLI: `morg normalize`) — one full round trip to morg's canonical
+  (CLI: `morg normalize`): one full round trip to morg's canonical
   form, a fixed point. Canonicalization, not styling: org-isms and
   md-isms are rewritten exactly as a conversion would rewrite them.
-  Normalize with the same preset/config you will convert with —
+  Normalize with the same preset/config you will convert with, since
   convergence is per-config (ADR 0002).
 
 - `markdownStyle: { bullet, emphasis, strong, fence, rule, ruleRepetition }`
   (on `convertOrgToMarkdown` and `normalizeMarkdown`; CLI `--bullet`,
   `--emphasis`, `--strong`, `--fence`, `--rule`, `--rule-repetition`)
-  — Markdown output style knobs. Defaults match prettier except emphasis (`*italic*`);
-  `--emphasis _` aligns fully with prettier. Canonical form is
+  are Markdown output style knobs. Defaults match prettier except
+  emphasis (`*italic*`); `--emphasis _` aligns fully with prettier.
+  Canonical form is
   per-config (ADR 0001): round trips must use the same style. Note
-  CommonMark/GFM prescribe no style — these defaults are morg's
+  CommonMark/GFM prescribe no style; these defaults are morg's
   canonical choices, not a standard.
 
 Both convert functions also accept `onWarning: message => …`, called for
@@ -233,8 +239,8 @@ org → md:  uniorg-parse → preset extraction → uniorg→mdast (core) → re
 ```
 
 Formatting is controlled by shaping the AST (e.g. inserting newline text nodes),
-not by custom stringifier handlers — the default, battle-tested stringifiers do
-the rendering.
+not by custom stringifier handlers. The default, battle-tested
+stringifiers do the rendering.
 
 Project vocabulary lives in [CONTEXT.md](CONTEXT.md); design decisions in
 [docs/adr/](docs/adr/).
@@ -245,14 +251,14 @@ The core conversion surface is feature-complete and validated against
 real-world Logseq org vaults (edge cases found there live on as
 anonymized fixtures, e.g. `tests/fixtures/logseq-vault.org`); the
 client-side [Web UI](https://morg.binarypoetry.ch) is deployed from
-`main`. The npm package is `@remigius42/morg` — the bare `morg` name is
-taken — and pushing a `v*` tag publishes it. Most of the code is
+`main`. The npm package is `@remigius42/morg`, since the bare `morg`
+name is taken, and pushing a `v*` tag publishes it. Most of the code is
 written with an AI coding agent under human direction, test-first and
-CI-gated — see
+CI-gated. See
 the [contributing guide](CONTRIBUTING.md#development-process).
 
-How each construct maps — including deliberate normalizations and
-documented drops — is covered in the
+How each construct maps, including deliberate normalizations and
+documented drops, is covered in the
 [mapping reference](docs/mappings.md). Notable changes are tracked in
 the [changelog](CHANGELOG.md).
 

package/dist/cli/args.d.ts

@@ -1,5 +1,7 @@
 export interface CliArgs {
     normalize: boolean;
+    help: boolean;
+    version: boolean;
     fromFormat: string | undefined;
     toFormat: string | undefined;
     inputFile: string | undefined;

package/dist/cli/args.js

@@ -1,4 +1,5 @@
 import { CliError } from "./error.js";
+import { FLAGS_BY_NAME } from "./flags.js";
 export function parseArgs(args) {
     // `morg normalize` canonicalizes in place of converting: same format
     // in and out, one full round trip (see ADR 0001)
@@ -8,6 +9,8 @@ export function parseArgs(args) {
     }
     const parsed = {
         normalize,
+        help: false,
+        version: false,
         fromFormat: undefined,
         toFormat: undefined,
         inputFile: undefined,
@@ -23,35 +26,12 @@ export function parseArgs(args) {
     parseFlags(parsed, args);
     return parsed;
 }
-const VALUE_FLAGS = new Set([
-    "--config",
-    "--bullet",
-    "--emphasis",
-    "--strong",
-    "--fence",
-    "--rule",
-    "--rule-repetition",
-    "--from",
-    "--to",
-    "--input",
-    "--output",
-    "--preset"
-]);
-const BOOLEAN_FLAGS = new Map([
-    ["-s", "silent"],
-    ["--silent", "silent"],
-    ["--task-checkboxes", "taskCheckboxes"],
-    ["--interpret-html", "interpretHtml"],
-    ["--record-style", "recordStyle"]
-]);
 // a following flag means the value was forgotten; a lone `-` is a legitimate
 // bullet or rule character, so only recognized flag tokens disqualify
 function takeValue(args, index) {
     const flag = args[index];
     const value = args[index + 1];
-    if (value === undefined ||
-        VALUE_FLAGS.has(value) ||
-        BOOLEAN_FLAGS.has(value)) {
+    if (value === undefined || FLAGS_BY_NAME.has(value)) {
         throw new CliError(`${flag} requires a value`);
     }
     return value;
@@ -59,47 +39,29 @@ function takeValue(args, index) {
 function parseFlags(parsed, args) {
     for (let i = 0; i < args.length; i++) {
         const arg = args[i] ?? "";
-        // boolean flags take an optional `true`/`false`; bare means true
-        const option = BOOLEAN_FLAGS.get(arg);
-        if (option) {
-            const value = args[i + 1];
-            if (value === "true" || value === "false") {
-                i++;
-            }
-            parsed[option] = value !== "false";
-            continue;
+        const spec = FLAGS_BY_NAME.get(arg);
+        if (!spec) {
+            throw new CliError(`Unknown argument: ${arg}`);
         }
-        switch (arg) {
-            case "--config":
-                parsed.configPath = takeValue(args, i++);
-                break;
-            case "--bullet":
-            case "--emphasis":
-            case "--strong":
-            case "--fence":
-            case "--rule":
-                parsed.markdownStyle[arg.slice(2)] = takeValue(args, i++);
-                break;
-            case "--rule-repetition":
-                parsed.markdownStyle.ruleRepetition = takeValue(args, i++);
+        switch (spec.kind) {
+            case "boolean": {
+                // boolean flags take an optional `true`/`false`; bare means true
+                const value = args[i + 1];
+                if (value === "true" || value === "false") {
+                    i++;
+                }
+                parsed[spec.key] = value !== "false";
                 break;
-            case "--from":
-                parsed.fromFormat = takeValue(args, i++);
-                break;
-            case "--to":
-                parsed.toFormat = takeValue(args, i++);
-                break;
-            case "--input":
-                parsed.inputFile = takeValue(args, i++);
+            }
+            case "info":
+                parsed[spec.key] = true;
                 break;
-            case "--output":
-                parsed.outputFile = takeValue(args, i++);
+            case "string":
+                parsed[spec.key] = takeValue(args, i++);
                 break;
-            case "--preset":
-                parsed.presetName = takeValue(args, i++);
+            case "style":
+                parsed.markdownStyle[spec.key] = takeValue(args, i++);
                 break;
-            default:
-                throw new CliError(`Unknown argument: ${arg}`);
         }
     }
 }

package/dist/cli/error.js

@@ -1,4 +1,4 @@
 // user-facing CLI failure; the executable entry maps it to stderr and
-// exit code 1 — helpers throw instead of exiting so they stay testable
+// exit code 1; helpers throw instead of exiting so they stay testable
 export class CliError extends Error {
 }

package/dist/cli/flags.d.ts

@@ -0,0 +1,27 @@
+type StringOption = "fromFormat" | "toFormat" | "inputFile" | "outputFile" | "presetName" | "configPath";
+type BooleanOption = "silent" | "taskCheckboxes" | "interpretHtml" | "recordStyle";
+type InfoOption = "help" | "version";
+export type FlagSpec = ({
+    names: string[];
+    arg: string;
+    description: string;
+} & ({
+    kind: "string";
+    key: StringOption;
+} | {
+    kind: "style";
+    key: string;
+})) | ({
+    names: string[];
+    arg?: undefined;
+    description: string;
+} & ({
+    kind: "boolean";
+    key: BooleanOption;
+} | {
+    kind: "info";
+    key: InfoOption;
+}));
+export declare const FLAGS: FlagSpec[];
+export declare const FLAGS_BY_NAME: Map<string, FlagSpec>;
+export {};

package/dist/cli/flags.js

@@ -0,0 +1,127 @@
+// the single source of truth for the CLI surface: the parser dispatches on
+// these entries and the help text is rendered from them, so a flag cannot
+// exist undocumented or be documented without existing
+// declaration order is the order the help text lists them in
+export const FLAGS = [
+    {
+        names: ["--from"],
+        arg: "<format>",
+        description: "Source format: markdown or org",
+        kind: "string",
+        key: "fromFormat"
+    },
+    {
+        names: ["--to"],
+        arg: "<format>",
+        description: "Target format: markdown or org",
+        kind: "string",
+        key: "toFormat"
+    },
+    {
+        names: ["--input"],
+        arg: "<file>",
+        description: "Read from a file instead of stdin",
+        kind: "string",
+        key: "inputFile"
+    },
+    {
+        names: ["--output"],
+        arg: "<file>",
+        description: "Write to a file instead of stdout",
+        kind: "string",
+        key: "outputFile"
+    },
+    {
+        names: ["--preset"],
+        arg: "<name>",
+        description: "Apply an editor preset, for example logseq",
+        kind: "string",
+        key: "presetName"
+    },
+    {
+        names: ["--config"],
+        arg: "<file>",
+        description: "Read settings from a TOML file",
+        kind: "string",
+        key: "configPath"
+    },
+    {
+        names: ["-s", "--silent"],
+        description: "Suppress warnings about dropped constructs",
+        kind: "boolean",
+        key: "silent"
+    },
+    {
+        names: ["--task-checkboxes"],
+        description: "Render Org TODO keywords as Markdown checkboxes",
+        kind: "boolean",
+        key: "taskCheckboxes"
+    },
+    {
+        names: ["--interpret-html"],
+        description: "Convert inline HTML instead of passing it through",
+        kind: "boolean",
+        key: "interpretHtml"
+    },
+    {
+        names: ["--record-style"],
+        description: "Record the detected Markdown style as front matter",
+        kind: "boolean",
+        key: "recordStyle"
+    },
+    {
+        names: ["-h", "--help"],
+        description: "Show this help",
+        kind: "info",
+        key: "help"
+    },
+    {
+        names: ["--version"],
+        description: "Show the version",
+        kind: "info",
+        key: "version"
+    },
+    {
+        names: ["--bullet"],
+        arg: "<char>",
+        description: "List bullet character",
+        kind: "style",
+        key: "bullet"
+    },
+    {
+        names: ["--emphasis"],
+        arg: "<char>",
+        description: "Emphasis marker",
+        kind: "style",
+        key: "emphasis"
+    },
+    {
+        names: ["--strong"],
+        arg: "<char>",
+        description: "Strong emphasis marker",
+        kind: "style",
+        key: "strong"
+    },
+    {
+        names: ["--fence"],
+        arg: "<char>",
+        description: "Code fence character",
+        kind: "style",
+        key: "fence"
+    },
+    {
+        names: ["--rule"],
+        arg: "<char>",
+        description: "Thematic break character",
+        kind: "style",
+        key: "rule"
+    },
+    {
+        names: ["--rule-repetition"],
+        arg: "<n>",
+        description: "Thematic break character count",
+        kind: "style",
+        key: "ruleRepetition"
+    }
+];
+export const FLAGS_BY_NAME = new Map(FLAGS.flatMap(spec => spec.names.map(name => [name, spec])));

package/dist/cli/formats.js

@@ -1,5 +1,5 @@
 import { CliError } from "./error.js";
-import { formatFromFileName } from "../fileNames.js";
+import { formatFromFileName, splitFileName } from "../fileNames.js";
 export function inferFormats(cli) {
     let { fromFormat, toFormat } = cli;
     // Infer formats from file extensions first
@@ -27,14 +27,28 @@ function inferMissingFormat(normalize, fromFormat, toFormat) {
     }
     return [fromFormat, toFormat];
 }
+// --from and --to read like the file pair they usually accompany, so a file
+// name given to one is the likely mistake behind an unsupported format
+function fileNameHint(flag, value) {
+    if (splitFileName(value).extension === "") {
+        return "";
+    }
+    const fileFlag = flag === "--from" ? "--input" : "--output";
+    return `\n${flag} takes a format name; for a file use ${fileFlag} ${value}.`;
+}
 export function validateFormats(fromFormat, toFormat, normalize) {
     if (!fromFormat || !toFormat) {
         throw new CliError("Error: Could not determine conversion formats.\n" +
             "Please specify --from and --to, or provide input/output files with .md or .org extensions.");
     }
-    if (!["markdown", "org"].includes(fromFormat) ||
-        !["markdown", "org"].includes(toFormat)) {
-        throw new CliError(`Error: Unsupported format. Supported formats are 'markdown' and 'org'.`);
+    for (const [flag, value] of [
+        ["--from", fromFormat],
+        ["--to", toFormat]
+    ]) {
+        if (!["markdown", "org"].includes(value)) {
+            throw new CliError(`Error: Unsupported format '${value}'. Supported formats are ` +
+                `'markdown' and 'org'.${fileNameHint(flag, value)}`);
+        }
     }
     if (!normalize && fromFormat === toFormat) {
         throw new CliError("Error: Source and target formats cannot be the same.");

package/dist/cli/help.d.ts

@@ -0,0 +1 @@
+export declare const HELP_TEXT: string;

package/dist/cli/help.js

@@ -0,0 +1,28 @@
+import { FLAGS } from "./flags.js";
+const signature = (spec) => spec.arg ? `${spec.names.join(", ")} ${spec.arg}` : spec.names.join(", ");
+// one column width across both sections, so the descriptions line up
+const DESCRIPTION_COLUMN = Math.max(...FLAGS.map(spec => signature(spec).length)) + 2;
+const section = (specs) => specs
+    .map(spec => `  ${signature(spec).padEnd(DESCRIPTION_COLUMN)}${spec.description}`)
+    .join("\n");
+export const HELP_TEXT = `Usage: morg [normalize] [options]
+
+Convert between Markdown and Org-mode. Reads stdin and writes stdout
+unless --input/--output are given; formats are inferred from the .md and
+.org file extensions, so --from/--to are only needed for stdin or stdout.
+
+Commands:
+  ${"normalize".padEnd(DESCRIPTION_COLUMN)}Round-trip a document through the other format
+  ${"".padEnd(DESCRIPTION_COLUMN)}and back, canonicalizing it in its own format
+
+Options:
+${section(FLAGS.filter(spec => spec.kind !== "style"))}
+
+Markdown style:
+${section(FLAGS.filter(spec => spec.kind === "style"))}
+
+Examples:
+  morg --input notes.md --output notes.org
+  morg --from markdown < notes.md > notes.org
+  morg normalize --input notes.org --output notes.org
+`;

package/dist/cli.js

@@ -6,6 +6,13 @@ import { resolvePreset } from "./cli/presets.js";
 import { inferFormats, validateFormats } from "./cli/formats.js";
 import { convert } from "./cli/conversion.js";
 import { CliError } from "./cli/error.js";
+import { HELP_TEXT } from "./cli/help.js";
+// both src/cli.ts and the built dist/cli.js sit one level below the package
+// root, so the manifest is at the same relative path either way
+function packageVersion() {
+    const manifest = fs.readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    return JSON.parse(manifest).version;
+}
 async function readInput(inputFile) {
     if (inputFile) {
         return fs.readFileSync(inputFile, "utf8");
@@ -23,7 +30,21 @@ async function readInput(inputFile) {
     });
 }
 async function main() {
-    const cli = parseArgs(process.argv.slice(2));
+    const argv = process.argv.slice(2);
+    // a bare invocation has nothing to convert, so it asks for help
+    if (argv.length === 0) {
+        console.log(HELP_TEXT);
+        return;
+    }
+    const cli = parseArgs(argv);
+    if (cli.help) {
+        console.log(HELP_TEXT);
+        return;
+    }
+    if (cli.version) {
+        console.log(packageVersion());
+        return;
+    }
     const config = loadConfig(cli.configPath);
     const preset = resolvePreset(cli.presetName ?? config.preset);
     const [fromFormat, toFormat] = inferFormats(cli);
@@ -41,10 +62,12 @@ main().catch((error) => {
     if (error instanceof CliError) {
         // helpers throw instead of exiting; this is the only exit point
         if (error.cause !== undefined) {
+            // a cause means the input or environment failed, not the invocation
             console.error(error.message, error.cause);
         }
         else {
             console.error(error.message);
+            console.error("Run 'morg --help' for usage.");
         }
     }
     else {

package/dist/conversionOptions.d.ts

@@ -17,8 +17,8 @@ export interface SharedConversionOptions {
 }
 /**
  * Layers explicit overrides over the config file, per direction. Used by
- * both adapters (CLI and Web UI) so the documented precedence — CLI or
- * form > config > defaults — means the same thing in each.
+ * both adapters (CLI and Web UI) so the documented precedence (CLI or
+ * form > config > defaults) means the same thing in each.
  * @param overrides Explicitly requested values; `undefined` defers to config.
  * @param config The parsed `morg.toml`.
  * @param shared Values that apply to both directions.

package/dist/conversionOptions.js

@@ -1,7 +1,7 @@
 /**
  * Layers explicit overrides over the config file, per direction. Used by
- * both adapters (CLI and Web UI) so the documented precedence — CLI or
- * form > config > defaults — means the same thing in each.
+ * both adapters (CLI and Web UI) so the documented precedence (CLI or
+ * form > config > defaults) means the same thing in each.
  * @param overrides Explicitly requested values; `undefined` defers to config.
  * @param config The parsed `morg.toml`.
  * @param shared Values that apply to both directions.

package/dist/core/mdastToUniorg/blocks.js

@@ -98,7 +98,7 @@ export function transformMdastHtml(ctx, node) {
         : null;
 }
 // a bare <dl> whose body is nothing but attribute-less <dt>/<dd> pairs
-// (any whitespace between tags) becomes a ` :: ` list — the same
+// (any whitespace between tags) becomes a ` :: ` list, the same
 // markdown convention descriptive lists use without useHtml, so the
 // org side re-parses it as a native descriptive list; anything richer
 // stays a preserved md-ism

package/dist/core/mdastToUniorg/index.js

@@ -45,7 +45,7 @@ export function transformMdastNodeToUniorgNode(ctx, node) {
         case "paragraph": {
             // a paragraph of only #+KEY: lines is affiliated keywords (or
             // mid-file keywords) traveling verbatim; emit as raw text so they
-            // glue to the following element without a blank line — org only
+            // glue to the following element without a blank line: org only
             // attaches affiliated keywords when directly above their element
             const keywordLines = keywordOnlyLines(node);
             if (keywordLines) {

package/dist/core/uniorgToMdast/elements.js

@@ -191,7 +191,7 @@ function transformParagraph(ctx, node) {
     const children = transformUniorgObjects(ctx, node.children);
     // md gives leading whitespace structural meaning (list
     // continuation, code); collapse per-line indentation inside
-    // paragraphs — insignificant in org and in rendered md alike
+    // paragraphs, insignificant in org and in rendered md alike
     children.forEach((child, index) => {
         if (child.type === "text") {
             child.value = child.value.replace(/\n[ \t]+/g, "\n");

package/dist/core/uniorgToMdast/lists.js

@@ -69,7 +69,7 @@ function transformUniorgList(ctx, node) {
 }
 function transformUniorgListItem(ctx, item) {
     // md has no descriptive lists, so keep the ` :: ` syntax literally in the
-    // item text — the return trip re-parses it as a descriptive list
+    // item text; the return trip re-parses it as a descriptive list
     const tag = listItemTag(item);
     const children = transformNodes(ctx, (item.children || []).filter(child => child !== tag));
     if (tag) {

package/dist/fileNames.d.ts

@@ -1,7 +1,7 @@
 /**
  * Splits a file name into the part a derived name keeps and the extension
  * that carries its format. A dotless name and a dotfile both have no
- * extension — `org` is a file called org, and `.org` is a hidden file whose
+ * extension: `org` is a file called org, and `.org` is a hidden file whose
  * name happens to start with a dot.
  *
  * The extension comes from the last path segment, since the CLI is handed

package/dist/fileNames.js

@@ -6,7 +6,7 @@ const DOCUMENT_FORMATS = new Map([
 /**
  * Splits a file name into the part a derived name keeps and the extension
  * that carries its format. A dotless name and a dotfile both have no
- * extension — `org` is a file called org, and `.org` is a hidden file whose
+ * extension: `org` is a file called org, and `.org` is a hidden file whose
  * name happens to start with a dot.
  *
  * The extension comes from the last path segment, since the CLI is handed

package/dist/markdownToOrg.js

@@ -40,7 +40,7 @@ export function convertMarkdownToOrg(markdown, options = {}) {
         canonical
     ]));
     restoreOrgisms(uniorgAst, canonicalKeys);
-    // Phase 2c: formatting-as-structure — adjacent lists need two blank
+    // Phase 2c: formatting-as-structure. Adjacent lists need two blank
     // lines between them, or org's parser merges them into one list.
     separateAdjacentLists(uniorgAst);
     // Phase 2d: record the source's own style markers, so the return trip

package/dist/normalize.d.ts

@@ -1,7 +1,7 @@
 import type { MarkdownToOrgOptions, OrgToMarkdownOptions } from "./options.js";
 /**
  * The full option set of both directions: normalization uses the same
- * configuration as conversion — Convergence is per-config (see ADR
+ * configuration as conversion, because Convergence is per-config (ADR
  * 0002), so a file must be normalized with the exact config (preset,
  * style, key names, toggles) it will be converted with.
  */
@@ -9,7 +9,7 @@ export type NormalizeOptions = MarkdownToOrgOptions & OrgToMarkdownOptions;
 /**
  * Normalizes a Markdown string to morg's canonical form: one full round
  * trip (`md → org → md`), whose output is a fixed point (see ADR 0001).
- * This canonicalizes, it does not just re-style — org-isms and md-isms
+ * This canonicalizes, it does not just re-style: org-isms and md-isms
  * are rewritten the same way a conversion would rewrite them.
  * @param markdown The Markdown string to normalize.
  * @param options Warning callback and dialect preset.

package/dist/normalize.js

@@ -3,7 +3,7 @@ import { convertOrgToMarkdown } from "./orgToMarkdown.js";
 /**
  * Normalizes a Markdown string to morg's canonical form: one full round
  * trip (`md → org → md`), whose output is a fixed point (see ADR 0001).
- * This canonicalizes, it does not just re-style — org-isms and md-isms
+ * This canonicalizes, it does not just re-style: org-isms and md-isms
  * are rewritten the same way a conversion would rewrite them.
  * @param markdown The Markdown string to normalize.
  * @param options Warning callback and dialect preset.

package/dist/options.d.ts

@@ -33,7 +33,7 @@ export interface MarkdownToOrgOptions {
     /**
      * Custom names for org-ism `key::` lines, canonical → custom (e.g.
      * `{ todo: "state" }`). Must match the mapping the file was written
-     * with — Convergence is per-config (ADR 0002).
+     * with, since Convergence is per-config (ADR 0002).
      */
     orgismKeys?: Record<string, string>;
     /** Called for each construct dropped without an equivalent. */
@@ -46,7 +46,7 @@ export interface MarkdownToOrgOptions {
  * Canonical form is parameterized by these (see ADR 0001): round trips
  * must use the same style, and files formatted under one style are not
  * a fixed point under another. Defaults: `-` bullet, `*` emphasis /
- * `*` strong (i.e. `**bold**`), backtick fences, `-` rule — prettier's
+ * `*` strong (i.e. `**bold**`), backtick fences, `-` rule: prettier's
  * choices except emphasis (`emphasis: "_"` aligns with prettier).
  */
 export interface MarkdownStyleOptions {
@@ -78,7 +78,7 @@ export interface OrgToMarkdownOptions {
      * Render Org constructs without a Markdown equivalent as raw HTML
      * (`<u>`, `<sup>`, `<sub>`, `<dl>`) instead of keeping their org markup
      * verbatim. HTML round-trips as a preserved md-ism (export blocks and
-     * snippets), not back to native org markup — a one-way door unless
+     * snippets), not back to native org markup, a one-way door unless
      * the return trip enables its inverse, `interpretHtml`.
      * Default: `false`.
      */

package/dist/orgToMarkdown.js

@@ -15,7 +15,7 @@ import { takeRecordedStyle } from "./core/markdownStyle.js";
 export function convertOrgToMarkdown(org, options = {}) {
     // Phase 1: Parse Org-mode to uniorg-ast
     let uniorgAst = unified().use(uniorgParse).parse(org);
-    // Phase 1b: a recorded style is morg's own (ADR 0004) — consume it so
+    // Phase 1b: a recorded style is morg's own (ADR 0004), so consume it so
     // it does not travel on as frontmatter; explicit options still win
     const recordedStyle = takeRecordedStyle(uniorgAst);
     // Phase 2: Extract dialect preset conventions, if any

package/dist/presets/logseq.js

@@ -191,7 +191,7 @@ function repairHighlights(uniorgAst) {
 }
 // Logseq page and block references: [[page]] stays a wikilink,
 // [[page][label]] becomes [label]([[page]]), [[((uuid))][label]]
-// becomes [label](((uuid))) — emitted unescaped via verbatim-inline
+// becomes [label](((uuid))), emitted unescaped via verbatim-inline
 const BLOCK_REF_RE = /^\(\(.*\)\)$/;
 function pageRefValue(label, target) {
     if (!label) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remigius42/morg",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Bidirectional Markdown ↔ Org-mode converter with round-trip convergence",
   "keywords": [
     "org-mode",