@remigius42/morg 0.5.0 → 0.7.0

package/README.md

@@ -37,6 +37,13 @@ guarantee is to be **semantically faithful and convergent** instead
   org properties; `org → md` serializes Org-only constructs ("org-isms") as
   `key:: value` conventions ([ADR
   0002](docs/adr/0002-mdism-property-namespace.md)).
+- Frontmatter travels verbatim and inert in a
+  `#+begin_comment morg_frontmatter` block, not as org keywords, which
+  can act in Emacs; an org file's own leading keywords travel as a
+  `morg_keywords` frontmatter entry and come back as keywords, a
+  file-level drawer (org-roam's `:ID:`) as `morg_properties`. The
+  Logseq preset instead maps page properties natively ([ADR
+  0005](docs/adr/0005-frontmatter-as-a-marked-comment-block.md)).
 - The few constructs that cannot be carried are documented in the
   [mapping reference](docs/mappings.md) and reported as warnings.
 
@@ -198,7 +205,11 @@ preset })`: `preserveOrgisms` default `true`; `useHtml` (default
   reverse direction restores headings from `:heading:` properties and
   turns plain block headlines back into paragraphs. Hiccup blocks
   (`[:div …]`) pass through as plain text and are emitted unescaped in
-  Markdown. Logseq's own syntax maps both directions: `TODO`/`DONE`
+  Markdown. Page properties map both directions: a first block of
+  `key:: value` lines and flat frontmatter entries ↔ leading
+  `#+key: value` lines, which Logseq reads as page properties;
+  frontmatter keys that act in Emacs (`todo`, `include`, …) stay inert.
+  Logseq's own syntax maps both directions: `TODO`/`DONE`
   text markers and `[#A]` priorities ↔ org keywords/priorities, page
   references `[[page]]` and labeled forms `[label]([[page]])` ↔ org
   fuzzy links `[[page][label]]`, block refs `[label](((uuid)))` ↔

package/dist/core/affiliated.d.ts

@@ -0,0 +1,13 @@
+import type { AffiliatedKeywords } from "uniorg";
+export declare const DUAL_NAMES = "CAPTION|RESULTS";
+/**
+ * An element's affiliated keywords as key, value pairs, the way they are
+ * written above it: several values (#+CAPTION, #+HEADER, #+ATTR_*) as
+ * several pairs, parsed ones (#+CAPTION) as org text, a dual value as
+ * part of the key (`CAPTION[short]`).
+ * @param affiliated The element's affiliated keywords.
+ * @param asOrg Parsed values as org text, links and markup kept, not as
+ * plain text (a Markdown line above a body element reads markup anew).
+ * @returns The pairs in order.
+ */
+export declare function affiliatedEntries(affiliated?: AffiliatedKeywords, asOrg?: boolean): [string, string][];

package/dist/core/affiliated.js

@@ -0,0 +1,43 @@
+import { toString } from "orgast-util-to-string";
+import { renderInline } from "./render.js";
+const MULTIPLE_RE = /^(?:CAPTION|HEADER|ATTR_.*)$/;
+// the keywords org reads with a dual value (`#+CAPTION[short]: long`);
+// aliases (RESULT) are not
+export const DUAL_NAMES = "CAPTION|RESULTS";
+const DUAL_RE = new RegExp(`^(?:${DUAL_NAMES})$`);
+/**
+ * An element's affiliated keywords as key, value pairs, the way they are
+ * written above it: several values (#+CAPTION, #+HEADER, #+ATTR_*) as
+ * several pairs, parsed ones (#+CAPTION) as org text, a dual value as
+ * part of the key (`CAPTION[short]`).
+ * @param affiliated The element's affiliated keywords.
+ * @param asOrg Parsed values as org text, links and markup kept, not as
+ * plain text (a Markdown line above a body element reads markup anew).
+ * @returns The pairs in order.
+ */
+export function affiliatedEntries(affiliated = {}, asOrg = false) {
+    return Object.entries(affiliated).flatMap(([key, value]) => (MULTIPLE_RE.test(key) ? value : [value]).map(item => {
+        const [main, dual] = DUAL_RE.test(key) && isDual(item) ? item : [item];
+        return [
+            dual === undefined ? key : `${key}[${dual}]`,
+            asOrg ? orgText(main) : plainText(main)
+        ];
+    }));
+}
+function isDual(value) {
+    return (Array.isArray(value) && value.length === 2 && typeof value[1] === "string");
+}
+function plainText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    return Array.isArray(value)
+        ? value.map(plainText).join("")
+        : toString(value);
+}
+function orgText(value) {
+    const items = Array.isArray(value) ? value : [value];
+    return items
+        .map(item => (typeof item === "string" ? item : renderInline(item)))
+        .join("");
+}

package/dist/core/backslashCommands.d.ts

@@ -0,0 +1,10 @@
+import type { Parent } from "unist";
+/**
+ * md→org: escapes a literal backslash org would read as a command, but
+ * not in a passthrough element's org text (`#+begin_export latex`).
+ */
+export declare function escapeBackslashCommands(tree: Parent): void;
+/**
+ * org→md: drops the zero-width spaces `escapeBackslashCommands` inserts.
+ */
+export declare function unescapeBackslashCommands(tree: Parent): void;

package/dist/core/backslashCommands.js

@@ -0,0 +1,43 @@
+import { EXIT, SKIP, visit } from "unist-util-visit";
+import { isPassthroughParagraph } from "./lineSyntax.js";
+import { ZERO_WIDTH_SPACE } from "./markupBoundary.js";
+// org reads a backslash before a letter as an entity (`\alpha`) or a
+// LaTeX fragment (`\Users`, `\foo{x}`), before `(` or `[` as a LaTeX
+// fragment too; a zero-width space after the backslash leaves it text
+const COMMAND_RE = /\\(?=[A-Za-z([])/g;
+const ESCAPED_RE = new RegExp(String.raw `\\${ZERO_WIDTH_SPACE}(?=[A-Za-z([])`, "g");
+/**
+ * md→org: escapes a literal backslash org would read as a command, but
+ * not in a passthrough element's org text (`#+begin_export latex`).
+ */
+export function escapeBackslashCommands(tree) {
+    visit(tree, (node, index, parent) => {
+        if (holdsCommand(node) &&
+            isPassthroughParagraph(node, index ?? 0, parent)) {
+            return SKIP;
+        }
+        if (node.type === "text") {
+            const text = node;
+            text.value = text.value?.replace(COMMAND_RE, `\\${ZERO_WIDTH_SPACE}`);
+        }
+        return undefined;
+    });
+}
+// whether a text in `node` holds a backslash org would read as a
+// command: the only paragraphs worth a passthrough check
+function holdsCommand(node) {
+    let found = false;
+    visit(node, "text", (text) => {
+        found ||= new RegExp(COMMAND_RE.source).test(text.value ?? "");
+        return found ? EXIT : undefined;
+    });
+    return found;
+}
+/**
+ * org→md: drops the zero-width spaces `escapeBackslashCommands` inserts.
+ */
+export function unescapeBackslashCommands(tree) {
+    visit(tree, "text", (node) => {
+        node.value = node.value?.replace(ESCAPED_RE, "\\");
+    });
+}

package/dist/core/bracedScripts.d.ts

@@ -0,0 +1,12 @@
+import type { OrgData } from "uniorg";
+/**
+ * md→org: adds `^:{}` to the document's `#+OPTIONS:` when its text
+ * holds a bare underscore or caret org would read as a script.
+ */
+export declare function requireBracedScripts(uniorgAst: OrgData): void;
+/**
+ * org→md: parses org, honoring its `^:` setting, and consuming `^:{}`
+ * where the text needs it: md→org adds it only then, so anywhere else
+ * it is the author's own setting.
+ */
+export declare function parseOrg(org: string): OrgData;

package/dist/core/bracedScripts.js

@@ -0,0 +1,159 @@
+import { unified } from "unified";
+import uniorgParse from "uniorg-parse";
+import { EXIT, visit } from "unist-util-visit";
+import { isInline, orgParser, positionParser, renderChildren, tryParse } from "./render.js";
+// org's `#+OPTIONS: ^:{}` limits sub/superscripts to the braced form
+// (`H_{2}O`), so a bare underscore or caret (`a_b`, `x^y`) stays text.
+// Markdown has no script syntax, so md text needs it; the braced
+// scripts morg itself emits are unaffected
+const BRACED_SCRIPTS = "^:{}";
+// built once: constructing a processor per parse dominates the cost
+const bracedScriptsParser = unified()
+    .use(uniorgParse, { useSubSuperscripts: "{}" })
+    .freeze();
+function isScript(node) {
+    return node.type === "subscript" || node.type === "superscript";
+}
+// a tree uniorg fails to read counts as holding none
+function countScripts(tree) {
+    let count = 0;
+    if (tree) {
+        visit(tree, (node) => {
+            if (isScript(node)) {
+                count++;
+            }
+        });
+    }
+    return count;
+}
+// a block's inline content as org renders it; a block element inside
+// (a list item's nested list) only ends a line
+function renderedContent(node) {
+    if (isInline(node) ||
+        !("children" in node) ||
+        !node.children.some(isInline)) {
+        return undefined;
+    }
+    return renderChildren(node.children).join("");
+}
+// a script org reads without `^:{}` only (uniorg's
+// matchSubstringRegex without the braced form, loosened): a `_` or `^`
+// after a non-blank, then `(`, `*`, or a word ending in a letter or
+// digit. Text without one reads the same either way and skips the parses
+const BARE_SCRIPT_RE = /\S[_^](?:[(*]|[+-]?[\p{L}\p{N}.,\\]*[\p{L}\p{N}])/u;
+// whether `tree` (of `content`) holds a script not in the braced form.
+// uniorg tries the braced form first, so without one both parsers read
+// the same, and the braced parse can be skipped
+function holdsBareScript(tree, content) {
+    let found = false;
+    visit(tree, (node) => {
+        const offset = node.position?.start.offset;
+        found =
+            isScript(node) && offset !== undefined && content[offset + 1] !== "{";
+        return found ? EXIT : undefined;
+    });
+    return found;
+}
+function readsBareScriptsIn(content) {
+    if (!BARE_SCRIPT_RE.test(content)) {
+        return false;
+    }
+    const tree = tryParse(content, positionParser);
+    return (tree !== undefined &&
+        holdsBareScript(tree, content) &&
+        countScripts(tree) > countScripts(tryParse(content, bracedScriptsParser)));
+}
+// whether org reads a script in the text that `^:{}` would keep text.
+// Checked per block as rendered, not per text node: the char before a
+// `_` or `^` may belong to a neighbor (a marker, a link's `]`, an
+// escape); a script never spans blocks
+function readsBareScripts(tree) {
+    let found = false;
+    visit(tree, (node) => {
+        const content = renderedContent(node);
+        found = content !== undefined && readsBareScriptsIn(content);
+        return found ? EXIT : undefined;
+    });
+    return found;
+}
+function isOptions(node) {
+    return (node.type === "keyword" && node.key.toUpperCase() === "OPTIONS");
+}
+/**
+ * md→org: adds `^:{}` to the document's `#+OPTIONS:` when its text
+ * holds a bare underscore or caret org would read as a script.
+ */
+export function requireBracedScripts(uniorgAst) {
+    if (!readsBareScripts(uniorgAst)) {
+        return;
+    }
+    const options = uniorgAst.children.find(isOptions);
+    if (!options) {
+        uniorgAst.children.unshift({
+            type: "keyword",
+            key: "OPTIONS",
+            value: BRACED_SCRIPTS
+        });
+    }
+    else if (!/(^|\s)\^:/.test(options.value)) {
+        // an explicit ^: setting is the author's call
+        options.value = `${options.value} ${BRACED_SCRIPTS}`;
+    }
+}
+// the `^:` setting in an `#+OPTIONS:` value, if any
+function scriptsSetting(options) {
+    const items = options.split(/\s+/).filter(item => item.startsWith("^:"));
+    return items.at(-1)?.slice(2);
+}
+// org→md honors every `^:` setting: `{}` limits scripts to the braced
+// form, `nil` turns them off, `t` (org's default) keeps them on
+const scriptsParsers = {
+    "{}": bracedScriptsParser,
+    nil: unified().use(uniorgParse, { useSubSuperscripts: false }).freeze()
+};
+// the settings the document may use, which the parser has to know up
+// front; only a top-level keyword counts, which takes a parse to tell
+function mayUseScripts(org) {
+    const settings = [...org.matchAll(/^[ \t]*#\+options:(.*)$/gim)].map(([, value]) => scriptsSetting(value ?? ""));
+    return [...new Set(settings)].filter((setting) => setting !== undefined);
+}
+function usesScripts(uniorgAst, setting) {
+    return uniorgAst.children.some(node => isOptions(node) && scriptsSetting(node.value) === setting);
+}
+// drops `^:{}` from the top-level `#+OPTIONS:`, the whole keyword if
+// nothing else is left; md text has no scripts, so the return trip
+// re-adds it wherever it is needed
+function takeBracedScripts(uniorgAst) {
+    uniorgAst.children = uniorgAst.children.filter(node => {
+        if (!isOptions(node)) {
+            return true;
+        }
+        node.value = node.value
+            .split(/\s+/)
+            .filter(item => item && item !== BRACED_SCRIPTS)
+            .join(" ");
+        return node.value !== "";
+    });
+}
+/**
+ * org→md: parses org, honoring its `^:` setting, and consuming `^:{}`
+ * where the text needs it: md→org adds it only then, so anywhere else
+ * it is the author's own setting.
+ */
+export function parseOrg(org) {
+    for (const setting of mayUseScripts(org)) {
+        const parser = scriptsParsers[setting];
+        if (!parser) {
+            continue;
+        }
+        // keywords parse the same either way
+        const uniorgAst = parser.parse(org);
+        if (usesScripts(uniorgAst, setting)) {
+            if (setting === "{}" && readsBareScripts(uniorgAst)) {
+                takeBracedScripts(uniorgAst);
+            }
+            return uniorgAst;
+        }
+    }
+    return orgParser.parse(org);
+}

package/dist/core/footnoteReferences.d.ts

@@ -0,0 +1,10 @@
+import type { Parent } from "unist";
+/**
+ * md→org: escapes a literal `[fn:` in text.
+ */
+export declare function escapeFootnoteReferences(tree: Parent): void;
+/**
+ * org→md: drops the zero-width spaces `escapeFootnoteReferences`
+ * inserts.
+ */
+export declare function unescapeFootnoteReferences(tree: Parent): void;

package/dist/core/footnoteReferences.js

@@ -0,0 +1,24 @@
+import { visit } from "unist-util-visit";
+import { ZERO_WIDTH_SPACE } from "./markupBoundary.js";
+// org reads `[fn:` in text as a footnote reference (`[fn:1]`, `[fn::x]`,
+// `[fn:a:x]`), at a line start as a definition; a zero-width space after
+// the `[` leaves it text
+const REFERENCE = "[fn:";
+const ESCAPED = `[${ZERO_WIDTH_SPACE}fn:`;
+/**
+ * md→org: escapes a literal `[fn:` in text.
+ */
+export function escapeFootnoteReferences(tree) {
+    visit(tree, "text", (node) => {
+        node.value = node.value?.replaceAll(REFERENCE, ESCAPED);
+    });
+}
+/**
+ * org→md: drops the zero-width spaces `escapeFootnoteReferences`
+ * inserts.
+ */
+export function unescapeFootnoteReferences(tree) {
+    visit(tree, "text", (node) => {
+        node.value = node.value?.replaceAll(ESCAPED, REFERENCE);
+    });
+}

package/dist/core/frontmatterBlock.d.ts

@@ -0,0 +1,89 @@
+import type { OrgData } from "uniorg";
+import { type Scalar } from "yaml";
+export interface FrontmatterNode {
+    type: "morg-frontmatter";
+    yaml: string;
+}
+export declare function isFrontmatterNode(node: {
+    type: string;
+}): node is FrontmatterNode;
+/**
+ * md→org: puts the file's header in place, past keywords any pass put
+ * in front: an Emacs mode line and the file-level drawer lead the file,
+ * keywords org would attach to what follows stay apart, and the
+ * frontmatter node becomes the marked comment block.
+ * @param uniorgAst The document.
+ */
+export declare function renderFileHeader(uniorgAst: OrgData): void;
+/**
+ * md→org: takes the top-level entries `take` maps to keywords out of
+ * the frontmatter; the rest stays verbatim, comments included.
+ * @param yaml The frontmatter's YAML text.
+ * @param take Keywords for an entry, or null to leave it in place.
+ * @returns The keywords in order, and the remaining YAML text.
+ */
+export declare function takeFrontmatterEntries(yaml: string, take: (key: Scalar, value: unknown, text: (scalar: Scalar) => string) => [string, string][] | null): {
+    keywords: [string, string][];
+    yaml: string;
+};
+export declare const KEYWORD_NAME: string;
+export declare function fitsKeywordLine(key: string, value: string): boolean;
+export declare function fitsPropertyLine(key: string, value: string): boolean;
+/**
+ * org→md: whether morg's own entries (`morg_properties`,
+ * `morg_keywords`) can join the frontmatter: whether the YAML with one
+ * more top-level entry appended still parses as a single block mapping
+ * holding none of them yet. Comments alone take them; an indented
+ * mapping, a list, a flow mapping or a document ending in `...` do not.
+ * @param yaml The frontmatter's YAML text.
+ */
+export declare function takesMorgEntries(yaml: string): boolean;
+/**
+ * md→org: one of morg's own entries, a sequence of one-entry maps
+ * (`morg_keywords`, `morg_properties`, ADR 0005), restored only if
+ * every item fits its org line.
+ * @param yaml The frontmatter's YAML text.
+ * @param name The entry's key.
+ * @param fits Whether a key and value fit the org line they go back to.
+ * @returns The key, value pairs in order, and the remaining YAML text.
+ */
+export declare function takeMorgEntry(yaml: string, name: string, fits: (key: string, value: string) => boolean): {
+    keywords: [string, string][];
+    yaml: string;
+};
+interface FileHeader {
+    frontmatter?: string;
+    fileProperties?: [string, string][];
+    takesMorgEntries: boolean;
+    startsWithModeLine: boolean;
+}
+/**
+ * org→md: takes the file's header morg carries as frontmatter: the
+ * marked block and, where its YAML can take it, a file-level drawer.
+ * @param uniorgAst The parsed document.
+ * @param org The text it was parsed from.
+ * @param onWarning Reports a marked block morg cannot take.
+ * @returns The transform options holding them.
+ */
+export declare function takeFileHeader(uniorgAst: OrgData, org: string, onWarning?: (message: string) => void): FileHeader;
+/**
+ * org→md, for a tree `transformMdastToUniorgAst` built rather than one
+ * parsed from org text: its file header, the block still raw text.
+ * @param uniorgAst The document; its header nodes are removed.
+ * @returns The transform options holding the header.
+ */
+export declare function takeRenderedFileHeader(uniorgAst: OrgData): FileHeader;
+export declare function isModeLine(comment: string): boolean;
+export declare function isModeLineComment(node: {
+    type: string;
+}): boolean;
+/**
+ * md→org: marks the comment made from the Markdown body's first node as
+ * the file's mode line, if it is a -*- comment: what passes do to the
+ * tree before the header is rendered cannot make another one lead.
+ * @param node The uniorg node made from the body's first node.
+ */
+export declare function markModeLine(node: {
+    type: string;
+} | null): void;
+export {};