@remigius42/morg 0.6.0 → 0.8.0

package/README.md

@@ -17,8 +17,8 @@ Bidirectional **Markdown ↔ Org-mode** converter, built on the
 
 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.
+[Logseq](https://docs.logseq.com/)'s outline of blocks and page
+properties, are supported via presets.
 
 ## Round-trip convergence
 
@@ -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.
 
@@ -191,15 +198,20 @@ preset })`: `preserveOrgisms` default `true`; `useHtml` (default
   `- [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
-  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
-  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`
-  text markers and `[#A]` priorities ↔ org keywords/priorities, page
+- `logseq()`: a page is Logseq's outline of blocks, converted block by
+  block: a headline (stars, a space, the block's content, an empty
+  block as the bare stars) ↔ a `-` bullet indented one tab per level,
+  its lines below the first two spaces further in. A block's content
+  is one fragment, so a code block or table that starts on the
+  headline line converts as a whole. `:heading: N` ↔ `- ## …`, a
+  block's property drawer ↔ `key:: value` lines; planning lines and
+  other drawers (`:LOGBOOK:`) stay as written. A heading outside the
+  bullets is a top-level block, as Logseq writes a page's first one.
+  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.
+  Task markers and `[#A]` priorities stay text, page
   references `[[page]]` and labeled forms `[label]([[page]])` ↔ org
   fuzzy links `[[page][label]]`, block refs `[label](((uuid)))` ↔
   `[[((uuid))][label]]`, and `^^highlight^^` markup survives verbatim

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

@@ -4,6 +4,13 @@ import type { OrgData } from "uniorg";
  * holds a bare underscore or caret org would read as a script.
  */
 export declare function requireBracedScripts(uniorgAst: OrgData): void;
+/**
+ * Whether org→md would consume a `^:{}` setting at the head of `org`:
+ * its text reads a script org would otherwise take for one.
+ * @param org The org text, the setting included.
+ * @returns Whether the setting is taken as the one md→org adds.
+ */
+export declare function consumesBracedScripts(org: string): boolean;
 /**
  * org→md: parses org, honoring its `^:` setting, and consuming `^:{}`
  * where the text needs it: md→org adds it only then, so anywhere else

package/dist/core/bracedScripts.js

@@ -135,6 +135,16 @@ function takeBracedScripts(uniorgAst) {
         return node.value !== "";
     });
 }
+/**
+ * Whether org→md would consume a `^:{}` setting at the head of `org`:
+ * its text reads a script org would otherwise take for one.
+ * @param org The org text, the setting included.
+ * @returns Whether the setting is taken as the one md→org adds.
+ */
+export function consumesBracedScripts(org) {
+    // text without a bare script candidate skips the parse
+    return (BARE_SCRIPT_RE.test(org) && readsBareScripts(bracedScriptsParser.parse(org)));
+}
 /**
  * org→md: parses org, honoring its `^:` setting, and consuming `^:{}`
  * where the text needs it: md→org adds it only then, so anywhere else

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 {};