md2org 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+
+## [1.1.0] — 2026-10-03
+
+### Added
+- #8 HTML Entities translated for CLI and web as an option
+- LaTeX math passes through unchanged
+
+### Changed
+- Warnings Footer improved
+- iOS Shortcut deployment target transform.js reduced in size by completely
+  removing all HTML entity transformation logic.
+
+### Fixed
+- Comments in code blocks were not passing through
+
+
+## [1.0.1] — 2026-09-06
+
+### Added
+- Entities md2org adds are now reported in the warnings footer.
+
+### Changed
+- `shortcut/transform.js` header comment now shows md2org version.
+
+### Fixed
+- A bare relative link path such as `[foo](url)` or `[foo](a/b.md)` became a fuzzy Org link, which Org reads as a search for a headline of that name. Export failed. This affected 26 of the 652 CommonMark spec examples.
+- The web page's Copy button did nothing in Chromium browsers over plain http,
+  where `navigator.clipboard` is undefined. It now falls back and reports failure.
+- A code span containing `]]` inside a link description ended the link early,
+  producing invalid Org. The span now unwraps (monospace lost, characters kept).
+
+## [1.0.0] — 2026-09-06
+
+First release. Markdown to Org conversion at the command line, in the browser, and
+via an iOS Shortcut.
+
+### Added
+- `md2org --version` / `-v`.
+- `CHANGELOG.md`
+- CI, and a CLI test tier.
+
+### Changed
+- DESIGN.md, MAPPING.md and README.md reconciled with the code: the escaping
+  table now lists every escape the program performs.
+- specs in test directory moved to `specs/`
+
+### Fixed
+- The CLI ignored unknown options and then waited on stdin, so a typo hung.
+  Usage errors now exit 2.
+- The CLI wrote no trailing newline, leaving a malformed text file.
+- `npm test` needed esbuild and so could not run where esbuild has no binary. The
+  derived-copy check now compares behaviour instead of rebuilding; CI still
+  asserts byte-identity.
+- `shortcut/transform.js` size reduced by removing dead code.
+
+### Removed
+- Dead code in `src/org-render.js` left from the pre-fork design
+
+## Guidelines for updating this document
+Only user facing changes to this project are documented here. Entries are very brief summaries.
+
+For a converter, "the public API" is the mapping in [MAPPING.md](MAPPING.md) as much as it is the `md2org(string)` function. A change to what a given Markdown construct becomes in Org is a change users will notice in their files, so it is treated as breaking unless the previous output was invalid Org or plainly wrong.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+[1.1.0]: https://github.com/nicholascarroll/md2org.js/releases/tag/1.1.0
+[1.0.1]: https://github.com/nicholascarroll/md2org.js/releases/tag/1.0.1
+[1.0.0]: https://github.com/nicholascarroll/md2org.js/releases/tag/1.0.0

package/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Nicholas Carroll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+## Third-party code
+
+This package bundles a modified copy of commonmark.js in `src/vendor/`,
+Copyright (c) 2014, John MacFarlane, used under the BSD 2-Clause License.
+Its full licence text is in `src/vendor/LICENSE-commonmark`, which is
+distributed with this package.

package/README.md

@@ -0,0 +1,134 @@
+# md2org.js
+
+md2org.js converts Markdown markup to Org markup.
+
+- at the command line as a Unix filter  🙂
+- on your phone via an iOS Shortcut  😎
+- [in your browser](https://nicholascarroll.github.io/md2org.js/) with nothing uploaded anywhere 🥷
+
+
+Source text that is not Markdown markup passes through unchanged. The conversion is one-way only.
+
+## Use
+
+### 1. Command line
+
+A Unix filter. Needs [Node.js](https://nodejs.org).
+
+```sh
+npm install -g md2org
+```
+Usage: 
+
+```sh
+md2org notes.md > notes.org
+cat notes.md | md2org
+md2org < notes.md
+md2org --help
+md2org --version
+md2org -e        # translate HTML entities
+```
+
+Exit status is 0 on success, 1 if the input file can't be read, 2 for a usage
+error.
+
+### 2. iOS Shortcut
+
+Copy Markdown, tap the md2org button in the Control Centre and your clipboard content converts to Org. See **[shortcut/README.md](shortcut/README.md)** for the two-minute setup, or get the [drop-in Shortcut definition](shortcut/)
+
+### 3. In the browser
+
+Open the [live page](https://nicholascarroll.github.io/md2org.js/). Paste Markdown, copy Org. Conversion happens entirely on your device; it sends nothing over the network.
+
+## Warnings Footer
+
+md2org will write any warnings to the tail of the Org mode output as comments. For example, if your source file had a line starting with `** foo`, you will see this at the bottom of your output.
+
+```
+# md2org warnings:
+# heading: line 2
+```
+This is warning you that line 2 of your output was not a heading in the source but has become a heading in the output. 
+
+
+## Known lossy conversions
+
+- Intraword emphasis `a**b**c` becomes `a*b*c`.
+- Link titles: `[t](/u "title")` loses the title.
+- `+ item` becomes `- item` and `_em_` becomes `/em/`. 
+- Raw HTML. Blocks become `#+BEGIN_EXPORT html`
+- inline HTML becomes  `@@html:…@@`. 
+- Character references pass through as you wrote them. `&mdash;` and `&HilbertSpace;`, and numeric ones such as `&#65;` and `&#x41;`, all reach the Org file untouched.  For CLI and web deployment targets you can enable translation to actual Unicode codepoints.
+
+
+## Correctness
+
+md2org.js forks and modifies the reference [CommonMark](https://spec.commonmark.org/0.31.2/) parser, and passes 652 of the specification's 652 test cases when the HTML Entities option is enabled. 
+
+Tables and footnotes are [GitHub Flavoured Markdown](specs/gfm-spec-0.29.txt) extensions that CommonMark doesn't define.
+
+If you encounter any nonconformities please log an issue or a PR even.
+
+### Edge cases
+
+The cases below are all tested:
+
+| Markdown | Naive output would mean | What md2org emits |
+|---|---|---|
+| a language-tagged fence containing `#+END_SRC` | block ends early, rest of the file is body text | `,#+END_SRC` (comma-quoted) |
+| `` `a=b` `` | verbatim ending at the first `=` | falls back to `~a=b~` |
+| `]` in a link path | the link ends early | percent-encoded by the parser |
+| `]]` in a link description | the link ends early | passed through and warned |
+| `\|` in a table cell | table alignment thrown out | passed through and warned |
+
+### Testing
+
+```sh
+npm test
+```
+
+`npm test` runs ten tiers, in order:
+1. **`test/spec.js`** is the behavioural contract.
+2. **`test/cli.js`** is the CLI contract, tests `bin/md2org` in the shell.
+3. **`test/conformance.js`** is CommonMark conformance, 652/652, measured against
+   the spec's own Markdown/HTML pairs run as data with HTML entities option
+   enabled.
+4. **`test/gfm.js`** is GFM table conformance, 8/8, against the GFM spec's
+  examples.
+5. **`test/document.js`** is document-scale inputs.
+6. **`test/invariant.js`** verifies invariant 1: every non-markup character in 
+   the source appears in the output. 
+7. **`test/warnings.js`** verifies invariant 4, the Warnings Footer.
+8. **`test/fuzz.js`** generates 5,000 documents from a fragment corpus and
+   asserts that every output is structurally valid Org. `npm run fuzz` runs 
+   100,000.
+9. **`test/size.js`** asserts `shortcut/transform.js` still fits into the
+   Actions app. See [MAPPING.md](MAPPING.md#bytes-budget).
+10. **`test/emacs.js`** tests using Emacs. `npm run test:emacs`.
+
+
+Specifications are in [`specs/`](specs/README.md).
+
+
+## Building
+
+`src/` is several modules; `build.js` concatenates them into the browser and
+Shortcut copies. Run it after editing anything in `src/`:
+
+```sh
+node build.js
+```
+
+The CommonMark parser in `src/vendor/` is generated and committed. You only need
+`node tools/build-vendor.js` if you want to regenerate it.
+
+### Size limit on the iOS Shortcut
+
+The iOS Shortcut is extremely tightly constrained by a size limit for the md2org core code `shortcut/transform.js`: when pasting its contents into the Actions app's JavaScript code field, the Shortcuts editor crashes. There is a limit on lines and on bytes. For that reason the Shortcut copy is minified and new features are costed in bytes in [MAPPING.md](MAPPING.md).
+
+I've tested on iOS 26.3.1(a) and 26.6.1 (iPhone 14).  If you hit this issue on your device, please open an issue with your iOS version. Might not be fixable 🙁. 
+
+
+## License
+
+MIT

package/bin/md2org

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/*
+ * md2org CLI: a Unix filter that reads Markdown and writes Org.
+ *
+ *   cat notes.md | md2org > notes.org
+ *   md2org notes.md > notes.org
+ *   md2org < notes.md
+ *
+ * Uses the same core as the web page and the iOS Shortcut.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const md2org = require(path.join(__dirname, "..", "src", "md2org.js"));
+
+const args = process.argv.slice(2);
+
+const USAGE =
+  "md2org — convert Markdown to Org mode\n\n" +
+  "Usage:\n" +
+  "  md2org [file]        convert file (or stdin) to stdout\n" +
+  "  cat f.md | md2org    read from a pipe\n\n" +
+  "Options:\n" +
+  "  -e, --entities       decode HTML entities and numeric character references\n" +
+  "                       to the characters they name (&mdash; and &#8212; to —)\n" +
+  "  -h, --help           show this help\n" +
+  "  -v, --version        show the version\n";
+
+if (args.includes("-h") || args.includes("--help")) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
+if (args.includes("-v") || args.includes("--version")) {
+  process.stdout.write(require("../package.json").version + "\n");
+  process.exit(0);
+}
+
+// Character-reference decoding, off by default (DESIGN.md, Character references
+// and entities).
+const entities = args.includes("-e") || args.includes("--entities");
+
+// Reject unknown options rather than falling through to wait on stdin.
+const badOpt = args.find((a) => a.startsWith("-") && a !== "-" &&
+                                a !== "-e" && a !== "--entities");
+if (badOpt) {
+  process.stderr.write("md2org: unknown option " + badOpt + "\n\n" + USAGE);
+  process.exit(2);
+}
+
+const fileArgs = args.filter((a) => !a.startsWith("-"));
+if (fileArgs.length > 1) {
+  process.stderr.write("md2org: expected at most one file, got " +
+                       fileArgs.length + "\n\n" + USAGE);
+  process.exit(2);
+}
+
+/*
+ * Terminates the output with a newline, as a POSIX text file requires. The core
+ * omits it because the browser and Shortcut place the result in a text box or on
+ * the clipboard.
+ */
+function convert(input) {
+  const out = entities ? md2org.withEntities(input) : md2org(input);
+  process.stdout.write(out === "" ? out : out.replace(/\n?$/, "\n"));
+}
+
+const fileArg = fileArgs[0];
+
+if (fileArg) {
+  let input;
+  try {
+    input = fs.readFileSync(fileArg, "utf8");
+  } catch (e) {
+    process.stderr.write("md2org: cannot read " + fileArg + ": " + e.message + "\n");
+    process.exit(1);
+  }
+  convert(input);
+} else {
+  // Reading stdin. A terminal means no pipe was given, so report it rather than
+  // block.
+  if (process.stdin.isTTY) {
+    process.stderr.write("md2org: no input — give a file or pipe stdin\n\n" + USAGE);
+    process.exit(2);
+  }
+  const chunks = [];
+  process.stdin.on("data", (c) => chunks.push(c));
+  process.stdin.on("end", () => convert(Buffer.concat(chunks).toString("utf8")));
+  process.stdin.resume();
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "md2org",
+  "version": "1.1.0",
+  "description": "One-way Markdown to Org mode converter. CLI, browser and iOS Shortcut.",
+  "bin": {
+    "md2org": "bin/md2org"
+  },
+  "main": "src/md2org.js",
+  "scripts": {
+    "test": "node test/spec.js && node test/cli.js && node test/conformance.js && node test/gfm.js && node test/document.js && node test/invariant.js && node test/warnings.js && node test/fuzz.js 5000 && node test/size.js && node test/emacs.js",
+    "build": "node build.js",
+    "vendor": "node tools/build-vendor.js",
+    "fuzz": "node test/fuzz.js 100000",
+    "prepublishOnly": "npm test",
+    "test:emacs": "node test/emacs.js",
+    "compare": "node tools/compare.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "markdown",
+    "org",
+    "org-mode",
+    "emacs",
+    "converter",
+    "commonmark",
+    "gfm",
+    "cli",
+    "ios",
+    "shortcuts"
+  ],
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "homepage": "https://nicholascarroll.github.io/md2org.js/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicholascarroll/md2org.js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nicholascarroll/md2org.js/issues"
+  },
+  "author": "Nicholas Carroll",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/md2org.js

@@ -0,0 +1,82 @@
+/*
+ * md2org: one-way Markdown to Org mode converter.
+ *
+ * A pure function, string in and string out, with no I/O or platform APIs. The
+ * CLI, the web page and the iOS Shortcut run this same code, copied into place by
+ * build.js.
+ *
+ * Structure follows CommonMark's two-phase parsing strategy (spec Appendix):
+ *
+ *   src/vendor/commonmark.js   parse   (forked commonmark.js, BSD-2-Clause)
+ *   src/org-render.js          AST to Org
+ *   src/org-escape.js          escaping
+ */
+
+
+/*
+ * Node/CommonJS bootstrap. Outside the core markers, so build.js drops it from
+ * the generated bundles, which concatenate the modules into one scope.
+ */
+if (typeof __cmark === "undefined") { var __cmark = require("./vendor/commonmark.js"); }
+if (typeof renderOrg === "undefined") { var renderOrg = require("./org-render.js"); }
+if (typeof codeSpan === "undefined") {
+  var __esc = require("./org-escape.js");
+  var codeSpan = __esc.codeSpan,
+      escapeLinkPath = __esc.escapeLinkPath,
+      protectBlockBody = __esc.protectBlockBody,
+      escapeCell = __esc.escapeCell;
+}
+
+/* --8<-- core start */
+
+function md2org(src) {
+  if (typeof src !== "string") src = String(src == null ? "" : src);
+  if (src === "") return "";
+  renderOrg.warn = {};
+
+  var parser = new __cmark.Parser({ sourcepos: true });
+
+  var escapes = {
+    codeSpan: codeSpan,
+    escapeLinkPath: escapeLinkPath,
+    protectBlockBody: protectBlockBody,
+    escapeCell: escapeCell
+  };
+
+  var out = renderOrg(parser.parse(src), escapes);
+  var k = Object.keys(renderOrg.warn);
+  return k.length ? out + "\n\n# md2org warnings:\n" +
+    k.map(function (x) { return "# " + x + ": line " + renderOrg.warn[x].join(", "); }).join("\n") : out;
+}
+
+/* --8<-- core end */
+
+/*
+ * Character-reference decoding, off by default (DESIGN.md, Character references
+ * and entities). Used by the CLI's -e option.
+ *
+ * Outside the core markers, so it costs the Shortcut nothing. It swaps in the
+ * parser built with upstream's entity table, which is loaded on first use. This
+ * works because the core reads __cmark at call time.
+ */
+var __cmarkEntities = null;
+
+md2org.withEntities = function (src) {
+  if (!__cmarkEntities) __cmarkEntities = require("./vendor/commonmark-entities.js");
+  var saved = __cmark;
+  __cmark = __cmarkEntities;
+  try {
+    return md2org(src);
+  } finally {
+    __cmark = saved;
+  }
+};
+
+// Universal export: CommonJS (Node/CLI), bundlers, browser global.
+if (typeof module !== "undefined" && module.exports) {
+  module.exports = md2org;
+  module.exports.md2org = md2org;
+}
+if (typeof window !== "undefined") {
+  window.md2org = md2org;
+}

package/src/org-escape.js

@@ -0,0 +1,70 @@
+/*
+ * All of md2org's escaping (DESIGN.md, Escaping).
+ *
+ * Literal text is not escaped. Each function below either applies Org's own
+ * quoting mechanism or protects markup that md2org generates.
+ */
+
+/* --8<-- core start */
+
+/*
+ * Block bodies (§Lesser Elements). A line beginning with "*" or "#+" inside a
+ * block is comma-quoted, or Org reads it as a headline or a block delimiter. Org
+ * removes the comma on read.
+ *
+ * Mirrors org-escape-code-in-string: quote only when the line, after any existing
+ * commas, begins with "*" or "#+". Org strips a comma only from such lines, so
+ * quoting ",foo" would not be reversed.
+ */
+function protectBlockBody(text) {
+  return text.split("\n").map(function (line) {
+    return line.replace(/^([ \t]*)(,*)(\*|#\+)/, "$1$2,$3");
+  }).join("\n");
+}
+
+/*
+ * Code spans (§Text Markup). CONTENTS may not contain the MARKER, so a span
+ * holding "=" uses "~" and vice versa. A span holding both is returned as plain
+ * text, since entities are not expanded inside verbatim or code.
+ */
+function codeSpan(text) {
+  if (text.indexOf("=") === -1) return "=" + text + "=";
+  if (text.indexOf("~") === -1) return "~" + text + "~";
+  return text;
+}
+
+/*
+ * Table cells (§Table). A bare "|" ends a cell and Org has no escape for it.
+ * The parser consumes the backslash of GFM's "\|"; this restores it, so the
+ * output shows what the author typed. The renderer warns.
+ */
+function escapeCell(text) {
+  return String(text).replace(/\|/g, "\\|");
+}
+
+/*
+ * Link paths (§Regular Link). "[", "]" and "\" in PATHREG are backslash-escaped,
+ * the only escape Org provides there.
+ *
+ * A bare path such as "url" or "a/b.md" would be a FUZZY link (a headline
+ * search), and "(foo)" a CODEREF, so any path without an explicit type gets
+ * "file:", Org's type for a relative path. Unchanged: a path with its own
+ * LINKTYPE ("http:", "mailto:", "id:"), a FILENAME starting with "/", "~", "./"
+ * or "../", and a "#" CUSTOM-ID.
+ */
+function linkType(path) {
+  return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(path)   // LINKTYPE:...
+      || /^[/~#]/.test(path)                      // FILENAME or #CUSTOM-ID
+      || /^\.\.?\//.test(path);                    // ./ or ../ FILENAME
+}
+
+function escapeLinkPath(path) {
+  var p = String(path);
+  if (p && !linkType(p)) p = "file:" + p;
+  return p.replace(/([\[\]\\])/g, "\\$1");
+}
+
+/* --8<-- core end */
+
+module.exports = { protectBlockBody: protectBlockBody, codeSpan: codeSpan,
+                   escapeLinkPath: escapeLinkPath, escapeCell: escapeCell };