margins 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dheeraj Jha
+
+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.

package/README.md

@@ -0,0 +1,225 @@
+# margins
+
+[![CI](https://github.com/dheerajjha/inkd/actions/workflows/ci.yml/badge.svg)](https://github.com/dheerajjha/inkd/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
+[![Tests](https://img.shields.io/badge/tests-80-brightgreen.svg)](test/)
+[![Dependencies](https://img.shields.io/badge/dependencies-2-brightgreen.svg)](package.json)
+
+Open any folder of markdown in your browser, from the terminal. Browse it as a
+tree, read it rendered, follow the links between files — `[[wikilinks]]`
+included — edit with a live preview, and search all of it. Close the tab when
+you are done and it stops.
+
+```bash
+npm install -g margins
+
+cd ~/notes
+margins
+```
+
+No vault to create, no app to install, no account, nothing to configure. The
+only thing margins ever writes into the folder is a file you save.
+
+![A folder of team notes open in margins: a file tree on the left, a rendered note in the middle with wikilinks and a diagram, and on the right the note's outline and the notes that link to it](docs/screenshot-reading.png)
+
+## Why
+
+A folder of markdown is the most durable way to keep notes and docs there is.
+Every editor opens it, git versions it, and it will still be readable in
+twenty years. What is missing is a good way to *read* one.
+
+- **Single-file editors** — MarkEdit, Typora, TextEdit — open one file at a
+  time. There is no folder to see, so the links between files go nowhere.
+- **Obsidian** is built around exactly this, but it is an application with a
+  vault: it wants the folder registered, it writes a `.obsidian` directory into
+  it, and you cannot point it at a repository's `docs/` from the terminal.
+- **Markdown preview servers** — markserv, grip, md-fileserver — show a folder
+  in the browser but only read it, and know nothing of `[[wikilinks]]`.
+
+margins sits in between: the folder tree and linked notes of Obsidian, the
+lightness of a single-file editor, started from the terminal in whatever folder
+you are standing in — your notes, a project's `docs/`, a colleague's repository.
+
+## What it does
+
+- **Browse** the folder as a tree. Markdown first; other text files and images
+  are there too.
+- **Read** GitHub-flavoured markdown: tables, task lists, strikethrough, code
+  blocks, images from the folder, and the HTML that READMEs use — `<details>`,
+  `<kbd>`, `<img width>`.
+- **Follow links** the way GitHub reads them — `[text](other.md#section)` — and
+  the way Obsidian does — `[[Other]]`, `[[Other#Section]]`, `[[Other|alias]]`,
+  `![[diagram.png]]`.
+- **See what links here.** Every note shows the notes that link to it, by
+  either kind of link, with the line that does.
+- **Edit** with the source beside a live preview. `Ctrl/Cmd+S` saves.
+- **Create** a note from the sidebar, or by clicking a `[[link]]` to a note that
+  does not exist yet — the way Obsidian does it.
+- **Open a file by name** (`Ctrl/Cmd+P`) and **search every file**
+  (`Ctrl/Cmd+Shift+F`).
+- **Keep up with other editors.** Change a file in vim, VS Code or with an
+  agent, and the page shows the new version within two seconds.
+- **Never lose an edit to one.** If the file changed on disk after you opened
+  it, saving writes nothing and asks you which version to keep.
+
+![Editing a note: the markdown source on the left and the rendered preview on the right, updating as you type](docs/screenshot-editing.png)
+
+![Searching every file: matches grouped by file, with the matched word highlighted on each line](docs/screenshot-search.png)
+
+It follows your system's light or dark setting.
+
+![The same view in the dark theme](docs/screenshot-dark.png)
+
+## Usage
+
+```
+margins [path] [options]
+```
+
+`path` is a folder, or a file inside the folder to open first. It defaults to
+the current directory. A folder opens on its `README.md` or `index.md` if it has
+one — the page you would start from on GitHub.
+
+| Option | |
+|---|---|
+| `-p, --port <n>` | Port to listen on. Default 4600; if it is taken, a free one is used. |
+| `--hidden` | Show hidden files and folders — names starting with a dot. |
+| `--no-open` | Print the address instead of opening a browser. |
+| `-v, --version` | Print the version. |
+| `-h, --help` | Print the usage. |
+
+```bash
+margins                     # the folder you are in
+margins ~/notes             # another one
+margins docs/guide.md       # a repository's docs, opened on one page
+npx margins                 # without installing it
+```
+
+margins stops when you close its last tab. A reload, or a second tab, keeps it
+running; so does never opening a tab at all, if you would rather open the
+address yourself later. `Ctrl+C` stops it any time.
+
+### Keys
+
+| Key | |
+|---|---|
+| `Ctrl/Cmd+P` | Open a file by name |
+| `Ctrl/Cmd+Shift+F` | Search every file |
+| `e` | Edit this file |
+| `Ctrl/Cmd+S` | Save |
+| `Esc` | Close a panel, or stop editing |
+| `[` `]` | Back and forward |
+| `?` | Every shortcut |
+
+## How links are followed
+
+A **relative link** is resolved from the file it is in, as GitHub does:
+`[setup](../guide.md#install)` from `notes/a.md` opens `guide.md` at its
+*install* heading. Heading anchors are made the way GitHub makes them, so a
+link written for GitHub lands in the same place here.
+
+A **wikilink** names a file, not a path, so it keeps working when notes move.
+`[[Ideas]]` means the file called `Ideas.md` — and when several are, the one in
+the linking note's own folder, then the shallowest, then the first
+alphabetically, so the answer is always the same one. `[[projects/Ideas]]`
+narrows it by path. A wikilink to a note that does not exist yet is shown in a
+different colour, and clicking it creates the note.
+
+Links written as examples inside code blocks and code spans are left alone, and
+are not counted as links to anything.
+
+## Safety
+
+margins is meant to be pointed at folders you did not write — a cloned
+repository, a colleague's notes — and it can write files. So it assumes the
+folder might be hostile, and so might other websites open in the same browser.
+
+- **Nothing in a markdown file can run.** Rendered HTML is sanitised with
+  [DOMPurify](https://github.com/cure53/DOMPurify): no scripts, no event
+  handlers, no `javascript:` links, no forms, frames, embedded SVG or inline
+  styles. A strict Content-Security-Policy is the second lock: the page runs no
+  script margins did not ship itself. Images are served in a sandbox, so even an
+  SVG with a script in it only draws.
+- **Nothing outside the folder can be read or written** — not with `..`, not
+  with an absolute path, and not through a symlink inside the folder that points
+  somewhere else.
+- **`.git` and `node_modules` are never opened or written.** Writing
+  `.git/hooks/pre-commit` would be running code on your next commit.
+- **Other websites cannot use it.** It listens on `127.0.0.1` only; it answers
+  no request addressed to any other name, which stops DNS rebinding; it accepts
+  changes only from its own page; and it sends no CORS headers, so no other site
+  can read what it serves.
+- **Your own work is not lost to another program's.** Saving checks the file
+  still holds what you opened, by content hash rather than timestamp.
+
+Remote images — the badges at the top of most READMEs — are loaded, without a
+referrer, so the image host is not told which file or folder they appeared in.
+
+Each protection the server enforces has a test that fails without it — checked
+by removing them one at a time. Sanitising happens in the browser, where the
+test suite cannot reach, so it is checked there: against a markdown file that
+tries every trick above, in a real browser, before each release.
+
+## What it does not do
+
+It is deliberately small. There is no graph view, no plugins, no sync, no
+database and no index on disk — search and backlinks read the files each time,
+which is fast for a folder of notes and slow for a folder of hundreds of
+thousands of files, where margins stops at 20,000 and says so. Code blocks are
+not syntax-highlighted yet. `![[Note]]` embeds are shown as links, not inlined.
+Renaming and deleting are left to your file manager or editor. `.gitignore` is
+not read.
+
+## How it compares
+
+| | Folder tree | Edit | Search | Wikilinks and backlinks | Start from a terminal | Writes into your folder |
+|---|---|---|---|---|---|---|
+| MarkEdit | — | yes | — | — | — | only what you save |
+| Obsidian | yes | yes | yes | yes | — | a `.obsidian` folder |
+| markserv | yes | — | yes | — | yes | nothing |
+| SilverBullet | yes | yes | yes | yes | runs as a server | an index |
+| **margins** | yes | yes | yes | yes | yes | only what you save |
+
+## HTTP API
+
+The page is a client of this; nothing is hidden from you.
+
+| Endpoint | |
+|---|---|
+| `GET /api/info` | The folder, and the file to open first |
+| `GET /api/tree?path=` | One folder's entries |
+| `GET /api/files` | Every file below the folder |
+| `GET /api/file?path=` | A file's content and version, or what kind of thing it is |
+| `PUT /api/file` | Save `{path, content, version}`; 409 if the file changed |
+| `POST /api/file` | Create `{path, content}`; 409 if it exists |
+| `GET /api/version?path=` | A file's current version, for noticing changes |
+| `GET /api/search?q=` | Matches across every text file |
+| `GET /api/backlinks?path=` | What links to a file |
+| `GET /raw/<path>` | An image from the folder |
+| `GET /api/alive` | Held open by the page; when the last one closes, margins stops |
+
+## Development
+
+```bash
+git clone https://github.com/dheerajjha/inkd.git
+cd margins && npm install
+npm test                    # 80 tests
+node bin/margins.js ~/notes
+```
+
+The server uses no packages at all — Node's own `http`, `fs` and `path`. The
+two dependencies, [marked](https://github.com/markedjs/marked) and
+[DOMPurify](https://github.com/cure53/DOMPurify), are sent to the browser, where
+the rendering happens. Tests never touch the network, and every file they use is
+written by the test itself.
+
+## Related
+
+From the author of [reviewer](https://github.com/dheerajjha/reviewer), which
+does the same for reading a coding agent's changes: `git reviewer` in a
+repository opens its diff for review in the browser.
+
+## License
+
+MIT

package/bin/margins.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const { USAGE, UsageError, parseArgs } = require('../lib/cli');
+const { openInBrowser } = require('../lib/browser');
+const { DEFAULT_HOST, DEFAULT_PORT, displayPath, startServer } = require('../server');
+const { MARKDOWN_EXTENSIONS } = require('../lib/files');
+const { version } = require('../package.json');
+
+/** Everything said to the person running it goes to stderr; stdout stays clean. */
+function note(line = '') {
+  process.stderr.write(`${line}\n`);
+}
+
+/**
+ * What to serve and what to open first, from the path given.
+ *
+ * A file means its folder, opened on that file. A folder means itself,
+ * opened on its README or index if it has one -- the page a person would
+ * start from on GitHub.
+ */
+async function resolveTarget(given) {
+  const target = path.resolve(given ?? '.');
+  let stat;
+  try {
+    stat = await fs.stat(target);
+  } catch {
+    throw new UsageError(`Nothing at ${given ?? target}.`);
+  }
+
+  if (stat.isFile()) {
+    return { root: path.dirname(target), initial: path.basename(target) };
+  }
+
+  const names = await fs.readdir(target);
+  const start = ['readme', 'index']
+    .flatMap(stem => [...MARKDOWN_EXTENSIONS].map(ext => stem + ext))
+    .map(wanted => names.find(name => name.toLowerCase() === wanted))
+    .find(Boolean);
+  return { root: target, initial: start ?? null };
+}
+
+async function listen(port, options) {
+  try {
+    return await startServer({ ...options, port, host: DEFAULT_HOST });
+  } catch (error) {
+    if (error.code !== 'EADDRINUSE') throw error;
+    note(`Port ${port} is in use, picking another.`);
+    return startServer({ ...options, port: 0, host: DEFAULT_HOST });
+  }
+}
+
+async function main(argv) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (options.version) {
+    process.stdout.write(`${version}\n`);
+    return;
+  }
+
+  const { root, initial } = await resolveTarget(options.path);
+
+  let server;
+  const stop = () => {
+    server?.close(() => process.exit(0));
+    // Do not wait forever on a browser holding a connection open.
+    setTimeout(() => process.exit(0), 1500).unref();
+  };
+
+  server = await listen(options.port ?? (Number(process.env.PORT) || DEFAULT_PORT), {
+    root,
+    initial,
+    hidden: options.hidden,
+    onIdle: () => {
+      note('\n  Browser closed. Stopping.\n');
+      stop();
+    }
+  });
+
+  const url = `http://${DEFAULT_HOST}:${server.address().port}/`;
+  note(`\n  margins  ${url}`);
+  note(`  folder   ${displayPath(server.realRoot)}`);
+  note('\n  Close the tab when you are done, or press Ctrl+C.\n');
+
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+
+  if (options.open && !(await openInBrowser(url))) {
+    note('  Could not open a browser; open the address above yourself.\n');
+  }
+}
+
+main(process.argv.slice(2)).catch(error => {
+  if (error instanceof UsageError) {
+    note(`margins: ${error.message}`);
+    note('Run margins --help for usage.');
+    process.exit(2);
+  }
+  note(`margins: ${error.message}`);
+  process.exit(1);
+});

package/lib/browser.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const childProcess = require('node:child_process');
+
+/**
+ * Opening a URL in the default browser, with no dependency for it.
+ * The same approach reviewer uses, and for the same reasons.
+ */
+
+function openCommand(platform, url) {
+  switch (platform) {
+    case 'darwin':
+      return { command: 'open', args: [url] };
+    case 'win32':
+      // `start` is a cmd builtin, and its first quoted argument is the window
+      // title -- so an empty one comes first, or the URL is swallowed as it.
+      return { command: 'cmd', args: ['/c', 'start', '', url] };
+    default:
+      return { command: 'xdg-open', args: [url] };
+  }
+}
+
+/**
+ * @returns {Promise<boolean>} whether an opener was launched. A missing
+ *   opener fails asynchronously -- spawn does not throw for it -- so this
+ *   waits for the 'spawn' event instead of assuming.
+ */
+function openInBrowser(url, { platform = process.platform, spawn = childProcess.spawn } = {}) {
+  const { command, args } = openCommand(platform, url);
+  return new Promise(resolve => {
+    try {
+      const child = spawn(command, args, { stdio: 'ignore', detached: true });
+      child.on('error', () => resolve(false));
+      child.on('spawn', () => {
+        child.unref();
+        resolve(true);
+      });
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+module.exports = { openCommand, openInBrowser };

package/lib/cli.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Reading the command line. Pure, so it can be tested without starting
+ * anything.
+ */
+
+const USAGE = `margins — open a folder of markdown in your browser
+
+Usage:
+  margins [path] [options]
+
+Browse, read, edit and search the markdown in a folder, and follow the links
+between files, [[wikilinks]] included. Close the tab when you are done and it
+stops. Nothing is written into the folder except the files you save.
+
+Arguments:
+  path              A folder, or a file inside the folder to open first.
+                    Defaults to the current directory.
+
+Options:
+  -p, --port <n>    Port to listen on (default 4600; if it is taken, a free
+                    one is picked)
+      --hidden      Show hidden files and folders (names starting with a dot)
+      --no-open     Print the address instead of opening a browser
+  -v, --version     Print the version
+  -h, --help        Print this
+
+Keys, once it is open:
+  Ctrl/Cmd+P  open a file by name      Ctrl/Cmd+Shift+F  search every file
+  e           edit this file            Ctrl/Cmd+S        save
+  ?           every shortcut
+`;
+
+class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+/**
+ * @param {string[]} argv the arguments after `margins`
+ * @returns {{path: string|null, port: number|null, hidden: boolean, open: boolean, help: boolean, version: boolean}}
+ * @throws {UsageError}
+ */
+function parseArgs(argv) {
+  const options = { path: null, port: null, hidden: false, open: true, help: false, version: false };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        options.help = true;
+        break;
+      case '-v':
+      case '--version':
+        options.version = true;
+        break;
+      case '--hidden':
+        options.hidden = true;
+        break;
+      case '--no-open':
+        options.open = false;
+        break;
+      case '-p':
+      case '--port': {
+        const value = argv[++i];
+        const port = Number(value);
+        if (value === undefined || !Number.isInteger(port) || port < 0 || port > 65535) {
+          throw new UsageError(`${arg} needs a port number between 0 and 65535.`);
+        }
+        options.port = port;
+        break;
+      }
+      default:
+        if (arg.startsWith('-')) throw new UsageError(`Unknown option: ${arg}`);
+        if (options.path !== null) throw new UsageError('Give one folder or file, not several.');
+        options.path = arg;
+    }
+  }
+  return options;
+}
+
+module.exports = { USAGE, UsageError, parseArgs };

package/lib/files.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+/**
+ * Reading files for the page, and writing them back without losing anyone's
+ * work.
+ */
+
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown', '.mdown', '.mkd', '.mkdn', '.mdx']);
+const IMAGE_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.bmp': 'image/bmp'
+};
+
+// Past this a file is not opened as text. A notes folder has no 2 MB files;
+// a repository has lockfiles and generated bundles, and drawing one of those
+// into a textarea would freeze the tab to show nobody anything useful.
+const MAX_TEXT_BYTES = 2 * 1024 * 1024;
+
+// How much of a file is looked at to decide whether it is text. Git uses the
+// same test -- a NUL byte in the first 8000 -- and it is right often enough
+// that a folder browser has no reason to be cleverer.
+const SNIFF_BYTES = 8000;
+
+class FileTooLargeError extends Error {
+  constructor(size) {
+    super(`This file is ${(size / 1024 / 1024).toFixed(1)} MB, too large to open as text here.`);
+    this.name = 'FileTooLargeError';
+    this.status = 413;
+  }
+}
+
+class NotEditableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'NotEditableError';
+    this.status = 400;
+  }
+}
+
+/**
+ * The file changed on disk since the page loaded it. Carries what is there
+ * now, so the page can offer to show it rather than only refuse.
+ */
+class ConflictError extends Error {
+  constructor(current) {
+    super('This file changed on disk after you opened it. Your edit was not saved.');
+    this.name = 'ConflictError';
+    this.status = 409;
+    this.current = current;
+  }
+}
+
+/** 'markdown' | 'image' | 'file', from the name alone -- cheap enough for a listing. */
+function kindOf(name) {
+  const ext = path.extname(name).toLowerCase();
+  if (MARKDOWN_EXTENSIONS.has(ext)) return 'markdown';
+  if (IMAGE_TYPES[ext]) return 'image';
+  return 'file';
+}
+
+function imageType(name) {
+  return IMAGE_TYPES[path.extname(name).toLowerCase()] ?? null;
+}
+
+/**
+ * A short fingerprint of a file's content, which is what "the version the
+ * page has" means.
+ *
+ * Not the modification time. Two saves inside one millisecond, or a tool
+ * that restores mtimes, would both look like "unchanged" to an mtime check
+ * and lose an edit silently. A hash cannot be fooled that way, and for a
+ * file small enough to edit in a browser it costs nothing.
+ */
+function versionOf(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+function looksBinary(buffer) {
+  return buffer.subarray(0, SNIFF_BYTES).includes(0);
+}
+
+/**
+ * Everything the page needs to show one file.
+ *
+ * @param {string} abs an absolute path already confined to the root
+ * @returns {Promise<{kind: string, size: number, content?: string, version?: string}>}
+ */
+async function readForView(abs) {
+  const stat = await fs.stat(abs);
+  // A link like [docs](docs/) names a folder. The page shows it the way
+  // GitHub does -- its contents, then its README -- so this says what it is
+  // rather than refusing.
+  if (stat.isDirectory()) return { kind: 'folder', size: 0 };
+
+  const kind = kindOf(abs);
+  if (kind === 'image') return { kind, size: stat.size };
+  if (stat.size > MAX_TEXT_BYTES) throw new FileTooLargeError(stat.size);
+
+  const buffer = await fs.readFile(abs);
+  if (looksBinary(buffer)) return { kind: 'binary', size: stat.size };
+
+  return {
+    kind: kind === 'markdown' ? 'markdown' : 'text',
+    size: stat.size,
+    content: buffer.toString('utf8'),
+    version: versionOf(buffer)
+  };
+}
+
+/**
+ * Save over an existing file, if it is still the file the page loaded.
+ *
+ * @param {string} abs
+ * @param {string} content
+ * @param {string} expectedVersion what versionOf gave when the page opened it
+ * @returns {Promise<{version: string}>}
+ * @throws {ConflictError} when the file on disk is not that version any more
+ */
+async function writeChecked(abs, content, expectedVersion) {
+  if (typeof content !== 'string') throw new NotEditableError('Content must be text.');
+  if (Buffer.byteLength(content) > MAX_TEXT_BYTES) throw new FileTooLargeError(Buffer.byteLength(content));
+
+  const stat = await fs.stat(abs);
+  if (stat.isDirectory()) throw new NotEditableError('That is a folder.');
+  if (kindOf(abs) === 'image') throw new NotEditableError('Images cannot be edited here.');
+
+  const current = await fs.readFile(abs);
+  if (looksBinary(current)) throw new NotEditableError('That file is not text.');
+
+  // Between this read and the write below another program could still save;
+  // that window is a few milliseconds and the alternative, locking files
+  // other editors do not know about, is worse.
+  if (versionOf(current) !== expectedVersion) {
+    throw new ConflictError({ content: current.toString('utf8'), version: versionOf(current) });
+  }
+
+  // In place, not write-to-temp-and-rename. A rename replaces the file with
+  // a new one: it drops hard links, resets permissions and ownership on some
+  // systems, and breaks anything watching the old inode. An editor in a
+  // browser has no business changing what kind of file this is.
+  await fs.writeFile(abs, content, 'utf8');
+  return { version: versionOf(Buffer.from(content, 'utf8')) };
+}
+
+/**
+ * Create a file that does not exist yet, making folders on the way.
+ *
+ * @returns {Promise<{version: string}>}
+ * @throws {ConflictError} when something is already there
+ */
+async function createNew(abs, content) {
+  if (typeof content !== 'string') throw new NotEditableError('Content must be text.');
+
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  try {
+    // 'wx': fail rather than overwrite. Checking for existence first and
+    // then writing is the race this flag exists to close.
+    await fs.writeFile(abs, content, { encoding: 'utf8', flag: 'wx' });
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      const err = new ConflictError(null);
+      err.message = 'A file with that name already exists.';
+      throw err;
+    }
+    throw error;
+  }
+  return { version: versionOf(Buffer.from(content, 'utf8')) };
+}
+
+module.exports = {
+  ConflictError,
+  FileTooLargeError,
+  MARKDOWN_EXTENSIONS,
+  MAX_TEXT_BYTES,
+  NotEditableError,
+  createNew,
+  imageType,
+  kindOf,
+  looksBinary,
+  readForView,
+  versionOf,
+  writeChecked
+};