@davidsneighbour/draft-pipeline 0.1.1-rc.0

package/.env.example

@@ -0,0 +1,27 @@
+# Markdown source directory (recursive search: **/*.md, **/*.markdown)
+MARKDOWN_INPUT_DIR=./book
+
+# Build output directory for css + generated PDFs
+OUTPUT_DIR=./dist
+OUTPUT_CSS_FILE=./dist/output.css
+
+# Tailwind input CSS entrypoint
+TAILWIND_INPUT_CSS=./styles/pdf.css
+
+# PDF rendering templates
+HEADER_TEMPLATE_PATH=./templates/header.html
+FOOTER_TEMPLATE_PATH=./templates/footer.html
+DOCUMENT_TEMPLATE_PATH=./templates/document.html
+BOOK_LAYOUT_CSS_PATH=./styles/pdf-book-layout.css
+
+# Upload behavior
+REMARKABLE_UPLOAD_ENABLED=false
+REMARKABLE_HOST=remarkable
+REMARKABLE_XOCHITL_DIR=.local/share/remarkable/xochitl
+
+# Target location in reMarkable xochitl metadata
+# Required when upload is enabled
+REMARKABLE_PARENT_FOLDER_UUID=
+
+# Optional: only for human-readable documentation
+REMARKABLE_PARENT_FOLDER_NAME=Book of Hugo

package/.release-it.ts

@@ -0,0 +1,85 @@
+import type { Config } from 'release-it';
+
+const config = {
+  npm: {
+    publish: true,
+  },
+  git: {
+    requireCleanWorkingDir: true,
+    commit: true,
+    commitMessage: 'chore(release): v${version}',
+    tag: true,
+    tagName: 'v${version}',
+    push: true,
+    pushArgs: ['--follow-tags'],
+  },
+  github: {
+    release: true,
+    releaseName: 'v${version}',
+    skipChecks: true,
+    tokenRef: 'GITHUB_TOKEN_DEV',
+  },
+  plugins: {
+    '@release-it/conventional-changelog': {
+      infile: 'CHANGELOG.md',
+      preset: {
+        name: 'conventionalcommits',
+        types: [
+          { type: 'content', section: 'Content' },
+          { type: 'feat', section: 'Features' },
+          { type: 'fix', section: 'Bug Fixes' },
+          { type: 'build', section: 'Other Changes' },
+          { type: 'chore', section: 'Other Changes' },
+          { type: 'ci', section: 'Other Changes' },
+          { type: 'docs', section: 'Other Changes' },
+          { type: 'perf', section: 'Other Changes' },
+          { type: 'refactor', section: 'Other Changes' },
+          { type: 'revert', section: 'Other Changes' },
+          { type: 'style', section: 'Other Changes' },
+          { type: 'test', section: 'Other Changes' },
+        ],
+      },
+      whatBump(commits: Array<{ type?: string; notes?: unknown[] }>) {
+        let level: 2 | 1 | 0 | null = null;
+
+        for (const commit of commits) {
+          const notes = Array.isArray(commit.notes) ? commit.notes : [];
+          const type = typeof commit.type === 'string' ? commit.type : '';
+
+          if (notes.length > 0) {
+            return {
+              level: 0,
+              reason: 'There are BREAKING CHANGES.',
+            };
+          }
+
+          if (type === 'feat' || type === 'content') {
+            level = 1;
+            continue;
+          }
+
+          if (
+            level === null &&
+            ['fix', 'build', 'chore', 'ci', 'docs', 'perf', 'refactor', 'revert', 'style', 'test'].includes(type)
+          ) {
+            level = 2;
+          }
+        }
+
+        if (level === null) {
+          return false;
+        }
+
+        return {
+          level,
+          reason:
+            level === 1
+              ? 'There are feat/content commits.'
+              : 'There are patch-level changes.',
+        };
+      }
+    },
+  },
+} satisfies Config;
+
+export default config;

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [0.1.1-rc.0](https://github.com/davidsneighbour/draft-pipeline/compare/v0.0.1...v0.1.1-rc.0) (2026-03-15)
+
+### Other Changes
+
+* **fix:** enable npm package publishing ([267e186](https://github.com/davidsneighbour/draft-pipeline/commit/267e18692536dc3ea7c978bee7805de8c7336a11))
+* **fix:** make this package public ([41559ea](https://github.com/davidsneighbour/draft-pipeline/commit/41559eaa2c84b4d60c3fefd6ce38a1a8ea2fac29))
+
+## 0.0.1 (2026-03-15)
+
+### Other Changes
+
+* add release setup via release-it ([3cc45e1](https://github.com/davidsneighbour/draft-pipeline/commit/3cc45e1d55dc01a7f5f1514fb30a1b66f8baa284))
+* extend todo list ([4aa0ecf](https://github.com/davidsneighbour/draft-pipeline/commit/4aa0ecfa2806374ea914e7bcb46baff3f69d8c2c))
+* extend todo list ([3bd13c6](https://github.com/davidsneighbour/draft-pipeline/commit/3bd13c64a5769e155d2d9b78b08acba186e24fe2))
+* initial commit, current state ([8b30599](https://github.com/davidsneighbour/draft-pipeline/commit/8b30599978fdd9e044c473a40ba137a49401e6e3))
+* initial commit, license file added ([57438c2](https://github.com/davidsneighbour/draft-pipeline/commit/57438c27781d05f745335c112b2996ec0279ec7b))
+
+All notable changes to this project will be documented in this file.

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright (c) 2026 Patrick Kollitsch
+
+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,85 @@
+# draft-pipeline
+
+A standalone package extracted from the `bookofhugo.dev` toolchain for:
+
+1. Markdown → print-style PDF generation.
+2. Tailwind CSS compilation for PDF styling.
+3. Optional upload of built PDFs to a reMarkable tablet over SSH.
+
+## Extracted requirements and procedures
+
+### Markdown to PDF requirements
+
+- Input is a directory tree containing Markdown (`.md`, `.markdown`).
+- Front matter is read with `gray-matter`.
+- Files with `b/pdf/ignore: true` are skipped.
+- Markdown content is rendered via `marked`.
+- PDF generation runs through headless Playwright Chromium.
+- Header/footer/document HTML templates are applied with token replacement.
+- Output PDF names are flattened/sanitized from source path segments.
+
+### Upload to reMarkable requirements
+
+- SSH access to a configured reMarkable host (`REMARKABLE_HOST`).
+- Target xochitl data directory (`REMARKABLE_XOCHITL_DIR`).
+- Folder UUID where documents should be attached (`REMARKABLE_PARENT_FOLDER_UUID`).
+- Upload is explicitly toggleable with `REMARKABLE_UPLOAD_ENABLED=true|false`.
+
+### Procedure flow
+
+1. Build Tailwind CSS from `TAILWIND_INPUT_CSS` to `OUTPUT_CSS_FILE`.
+2. Convert Markdown files from `MARKDOWN_INPUT_DIR` into PDFs in `OUTPUT_DIR`.
+3. If upload is enabled, upload generated PDFs to reMarkable and restart xochitl.
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env
+```
+
+Edit `.env` as needed.
+
+## Commands
+
+```bash
+npm run css      # compile tailwind css
+npm run pdf      # generate PDFs only
+npm run upload   # upload only (if enabled)
+npm run build    # css + pdf + upload
+npm run release  # create a stable release (git tag + npm + GitHub)
+npm run release:pre # create an rc pre-release
+```
+
+Or with the CLI:
+
+```bash
+node src/cli.mjs build
+```
+
+## Configuration defaults
+
+Defaults are designed for a repository that mirrors this package structure.
+
+- Templates:
+  - `./templates/header.html`
+  - `./templates/footer.html`
+  - `./templates/document.html`
+- Tailwind CSS:
+  - input `./styles/pdf.css`
+  - output `./dist/output.css`
+- Markdown input: `./book`
+- PDF output: `./dist`
+- Upload disabled by default.
+- reMarkable host default: `remarkable`.
+
+## Graceful errors
+
+The package intentionally fails with direct explanations when:
+
+- input/template/css files are not readable,
+- no markdown files are found,
+- upload is enabled but host is unreachable,
+- upload is enabled but folder UUID is missing,
+- no PDFs are available for upload,
+- Tailwind build command fails.

package/ToDo.md

@@ -0,0 +1,57 @@
+## ToDo
+
+### .env setup
+
+- [ ] create a way to setup a custom `.pipeline.env` with demo content
+- [ ] set `.pipeline.env` as default env file and add a CLI parameter to set path to .env file
+
+### Override templates
+
+- [ ] add options to override each individual template with local path
+
+### Add print ready PDF output
+
+- [ ] add bleeds to PDF output and make it configurable (only when CLI parameter `--printready` is added)
+
+### Deprecate dotenv usage
+
+- [ ] require Node version that supports native .env integration
+- [ ] use native .env integration instead of dotenv
+
+### Add release pipeline via release-it
+
+- [x] add release-it configuration
+- [x] add `npm run release` script using release-it config
+- [x] add npm package release
+- [x] add github release
+- [x] add conventional commits changelog generation via release-it plugin
+- [x] add `npm run release:pre` to create pre-release packages
+
+### Fix/Add config order
+
+- [ ] make sure that all configuration can be done via .env file AND config file AND CLI parameters (overrides in that order)
+- [ ] make debuggable from where we receive the configuration (env, config, cli)
+- [ ] make config debuggable (output list or json)
+
+### Documentation
+
+- [ ] add section explaining how to configure (env vs. config vs. cli)
+- [ ] add section explaining all parameters (CLI, add env and config names as note to each parameter)
+
+### Sensible configuration defaults
+
+- [ ] add and document sensible configuration defaults for all options
+
+### Isolate reMarkable integration
+
+- [ ] explain in docs that reMarkable has a system of UUID and meta data files, that this is created on the fly and then uploaded via SSH to the reMarkable
+- [ ] add links to official docs or explanations how to setup for SSH access (cable required, host name configuration via /etc/hosts or IP address required)
+- [ ] isolate the remarkable upload into it's on little plugin/system and enable/disable via config option
+- [ ] requires explicit enable/disable via config option
+
+### Add SSH integration
+
+- [ ] enable upload via ssh to any location (add config parameters)
+- [ ] explore if this should/could be done via rsync so we have more target options for this
+- [ ] add in parallel to the remarkable setup
+- [ ] requires explicit enable/disable via config option

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@davidsneighbour/draft-pipeline",
+  "version": "0.1.1-rc.0",
+  "description": "Reusable markdown-to-pdf and optional reMarkable upload toolkit",
+  "type": "module",
+  "bin": {
+    "draft-pipeline": "./src/cli.mjs"
+  },
+  "scripts": {
+    "css": "node ./src/cli.mjs css",
+    "pdf": "node ./src/cli.mjs pdf",
+    "upload": "node ./src/cli.mjs upload",
+    "build": "node ./src/cli.mjs build",
+    "check": "node --check ./src/*.mjs",
+    "release": "release-it --config .release-it.ts",
+    "release:pre": "release-it --config .release-it.ts --preRelease=rc"
+  },
+  "dependencies": {
+    "@tailwindcss/cli": "4.2.1",
+    "dotenv": "17.3.1",
+    "fast-glob": "3.3.3",
+    "gray-matter": "4.0.3",
+    "marked": "17.0.4",
+    "playwright": "1.58.2",
+    "tailwindcss": "4.2.1"
+  },
+  "devDependencies": {
+    "@release-it/conventional-changelog": "10.0.6",
+    "release-it": "19.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/build-css.mjs

@@ -0,0 +1,21 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { assertReadableFile } from './config.mjs';
+
+export async function buildCss(config) {
+  await assertReadableFile(config.tailwindInputCss, 'Tailwind input CSS');
+  await mkdir(path.dirname(config.outputCssFile), { recursive: true });
+
+  const result = spawnSync(
+    'npx',
+    ['@tailwindcss/cli', '-i', config.tailwindInputCss, '-o', config.outputCssFile],
+    { stdio: 'inherit' },
+  );
+
+  if (result.status !== 0) {
+    throw new Error(
+      'Tailwind CSS build failed. Ensure @tailwindcss/cli is installed and TAILWIND_INPUT_CSS points to a valid file.',
+    );
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { loadConfig } from './config.mjs';
+import { buildCss } from './build-css.mjs';
+import { renderMarkdownDirectory } from './md-to-pdf.mjs';
+import { uploadToRemarkable } from './upload-remarkable.mjs';
+
+function printHelp() {
+  console.log(`draft-pipeline - A tool to convert markdown files to PDFs and upload them to reMarkable.
+
+Commands:
+  css     Build Tailwind CSS
+  pdf     Convert markdown files to PDFs
+  upload  Upload generated PDFs to reMarkable (when enabled)
+  build   Run css + pdf + upload
+
+Configuration:
+  Configure via .env file (see .env.example).
+`);
+}
+
+async function main() {
+  const command = process.argv[2] ?? 'build';
+
+  if (command === '--help' || command === '-h' || command === 'help') {
+    printHelp();
+    return;
+  }
+
+  const config = loadConfig(process.cwd());
+
+  if (command === 'css') {
+    await buildCss(config);
+    return;
+  }
+
+  if (command === 'pdf') {
+    await renderMarkdownDirectory(config, { verbose: true });
+    return;
+  }
+
+  if (command === 'upload') {
+    await uploadToRemarkable(config);
+    return;
+  }
+
+  if (command === 'build') {
+    await buildCss(config);
+    await renderMarkdownDirectory(config, { verbose: true });
+    await uploadToRemarkable(config);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}. Run with --help.`);
+}
+
+main().catch((error) => {
+  console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});

package/src/config.mjs

@@ -0,0 +1,62 @@
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { constants } from 'node:fs';
+import { config as loadDotEnv } from 'dotenv';
+
+const DEFAULTS = {
+  MARKDOWN_INPUT_DIR: './book',
+  OUTPUT_DIR: './dist',
+  OUTPUT_CSS_FILE: './dist/output.css',
+  TAILWIND_INPUT_CSS: './styles/pdf.css',
+  HEADER_TEMPLATE_PATH: './templates/header.html',
+  FOOTER_TEMPLATE_PATH: './templates/footer.html',
+  DOCUMENT_TEMPLATE_PATH: './templates/document.html',
+  BOOK_LAYOUT_CSS_PATH: './styles/pdf-book-layout.css',
+  REMARKABLE_UPLOAD_ENABLED: 'false',
+  REMARKABLE_HOST: 'remarkable',
+  REMARKABLE_XOCHITL_DIR: '.local/share/remarkable/xochitl',
+  REMARKABLE_PARENT_FOLDER_UUID: '',
+  REMARKABLE_PARENT_FOLDER_NAME: 'Book of Hugo',
+};
+
+export function loadConfig(cwd = process.cwd()) {
+  loadDotEnv({ path: path.join(cwd, '.env'), override: false });
+
+  const env = { ...DEFAULTS, ...process.env };
+
+  const config = {
+    cwd,
+    markdownInputDir: path.resolve(cwd, env.MARKDOWN_INPUT_DIR),
+    outputDir: path.resolve(cwd, env.OUTPUT_DIR),
+    outputCssFile: path.resolve(cwd, env.OUTPUT_CSS_FILE),
+    tailwindInputCss: path.resolve(cwd, env.TAILWIND_INPUT_CSS),
+    headerTemplatePath: path.resolve(cwd, env.HEADER_TEMPLATE_PATH),
+    footerTemplatePath: path.resolve(cwd, env.FOOTER_TEMPLATE_PATH),
+    documentTemplatePath: path.resolve(cwd, env.DOCUMENT_TEMPLATE_PATH),
+    bookLayoutCssPath: path.resolve(cwd, env.BOOK_LAYOUT_CSS_PATH),
+    remarkableUploadEnabled: String(env.REMARKABLE_UPLOAD_ENABLED).toLowerCase() === 'true',
+    remarkableHost: env.REMARKABLE_HOST,
+    remarkableXochitlDir: env.REMARKABLE_XOCHITL_DIR,
+    remarkableParentFolderUuid: env.REMARKABLE_PARENT_FOLDER_UUID,
+    remarkableParentFolderName: env.REMARKABLE_PARENT_FOLDER_NAME,
+  };
+
+  return config;
+}
+
+export async function assertReadableFile(filePath, label) {
+  try {
+    await access(filePath, constants.R_OK);
+  } catch {
+    throw new Error(`${label} is not readable: ${filePath}`);
+  }
+}
+
+export async function assertReadableDir(dirPath, label) {
+  try {
+    await access(dirPath, constants.R_OK);
+  } catch {
+    throw new Error(`${label} is not readable: ${dirPath}`);
+  }
+}

package/src/md-to-pdf.mjs

@@ -0,0 +1,153 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import fg from 'fast-glob';
+import matter from 'gray-matter';
+import { marked } from 'marked';
+import { chromium } from 'playwright';
+import { assertReadableDir, assertReadableFile } from './config.mjs';
+
+function escapeHtml(value) {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+function shouldIgnorePdf(data) {
+  return data?.['b/pdf/ignore'] === true || data?.['b/pdf/ignore'] === 'true';
+}
+
+function sanitiseSegment(value) {
+  return value
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-');
+}
+
+function buildFlatPdfFileName(relativePath) {
+  const parsed = path.parse(relativePath);
+  const segments = [...(parsed.dir ? parsed.dir.split(path.sep) : []), parsed.name]
+    .map(sanitiseSegment)
+    .filter(Boolean);
+
+  return `${segments.join('-') || 'document'}.pdf`;
+}
+
+function applyTemplate(template, replacements) {
+  return template.replaceAll(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (token, key) => replacements[key] ?? token);
+}
+
+async function buildJobs(inputDir, outputDir) {
+  const files = await fg(['**/*.md', '**/*.markdown'], {
+    cwd: inputDir,
+    onlyFiles: true,
+    absolute: true,
+  });
+
+  const used = new Set();
+  const jobs = [];
+
+  for (const absolutePath of files.sort()) {
+    const relativePath = path.relative(inputDir, absolutePath);
+    const parsed = matter(await readFile(absolutePath, 'utf8'));
+
+    if (shouldIgnorePdf(parsed.data)) {
+      continue;
+    }
+
+    const sourceName = path.basename(relativePath, path.extname(relativePath));
+    const title = typeof parsed.data?.title === 'string' ? parsed.data.title.trim() || sourceName : sourceName;
+
+    let outputName = buildFlatPdfFileName(relativePath);
+    if (used.has(outputName)) {
+      const p = path.parse(outputName);
+      let i = 2;
+      while (used.has(`${p.name}-${i}${p.ext}`)) i += 1;
+      outputName = `${p.name}-${i}${p.ext}`;
+    }
+
+    used.add(outputName);
+    jobs.push({ absolutePath, title, outputPdfPath: path.join(outputDir, outputName), fileName: path.basename(relativePath) });
+  }
+
+  return jobs;
+}
+
+export async function renderMarkdownDirectory(config, { verbose = false } = {}) {
+  await assertReadableDir(config.markdownInputDir, 'Markdown input directory');
+  await assertReadableFile(config.outputCssFile, 'Compiled CSS file');
+  await assertReadableFile(config.bookLayoutCssPath, 'Book layout CSS file');
+  await assertReadableFile(config.documentTemplatePath, 'Document template');
+  await assertReadableFile(config.headerTemplatePath, 'Header template');
+  await assertReadableFile(config.footerTemplatePath, 'Footer template');
+
+  await mkdir(config.outputDir, { recursive: true });
+
+  const [css, bookCss, htmlTemplate, headerTemplate, footerTemplate] = await Promise.all([
+    readFile(config.outputCssFile, 'utf8'),
+    readFile(config.bookLayoutCssPath, 'utf8'),
+    readFile(config.documentTemplatePath, 'utf8'),
+    readFile(config.headerTemplatePath, 'utf8'),
+    readFile(config.footerTemplatePath, 'utf8'),
+  ]);
+
+  const jobs = await buildJobs(config.markdownInputDir, config.outputDir);
+  if (jobs.length === 0) {
+    throw new Error(`No markdown files found in ${config.markdownInputDir}. Add *.md files or change MARKDOWN_INPUT_DIR.`);
+  }
+
+  if (verbose) {
+    console.log(`Rendering ${jobs.length} markdown file(s) from ${config.markdownInputDir}`);
+  }
+
+  const browser = await chromium.launch({ headless: true });
+  try {
+    for (const job of jobs) {
+      const parsed = matter(await readFile(job.absolutePath, 'utf8'));
+      const htmlBody = marked.parse(parsed.content, { gfm: true, breaks: false });
+      const html = applyTemplate(htmlTemplate, {
+        documentTitle: escapeHtml(job.title),
+        css: `${css}\n${bookCss}`,
+        htmlBody,
+        marginTop: '20mm',
+        marginBottom: '20mm',
+        marginInner: '1.5cm',
+        marginOuter: '1cm',
+      });
+
+      const page = await browser.newPage();
+      try {
+        await page.setContent(html, { waitUntil: 'load' });
+        await page.pdf({
+          path: job.outputPdfPath,
+          width: '7in',
+          height: '10in',
+          printBackground: true,
+          displayHeaderFooter: true,
+          headerTemplate: applyTemplate(headerTemplate, {
+            fileName: escapeHtml(job.fileName),
+            flatPdfName: escapeHtml(path.basename(job.outputPdfPath)),
+            title: escapeHtml(job.title),
+          }),
+          footerTemplate: applyTemplate(footerTemplate, {
+            fileName: escapeHtml(job.fileName),
+            flatPdfName: escapeHtml(path.basename(job.outputPdfPath)),
+            title: escapeHtml(job.title),
+          }),
+          margin: { top: '20mm', right: '0mm', bottom: '20mm', left: '0mm' },
+        });
+      } finally {
+        await page.close();
+      }
+
+      console.log(`Created PDF: ${job.outputPdfPath}`);
+    }
+  } finally {
+    await browser.close();
+  }
+}

package/src/upload-remarkable.mjs

@@ -0,0 +1,110 @@
+import { readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+function ssh(host, args, options = {}) {
+  return spawnSync('ssh', [host, ...args], { encoding: 'utf8', ...options });
+}
+
+function scp(host, localPath, remotePath) {
+  return spawnSync('scp', [localPath, `${host}:${remotePath}`], { stdio: 'inherit' });
+}
+
+function remarkableAvailable(host) {
+  const result = spawnSync('ssh', ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=3', host, 'exit'], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+async function getPdfFiles(outputDir) {
+  const entries = await readdir(outputDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && entry.name.endsWith('.pdf')).map((entry) => join(outputDir, entry.name)).sort();
+}
+
+function resolveParentId(config) {
+  if (config.remarkableParentFolderUuid) {
+    return config.remarkableParentFolderUuid;
+  }
+
+  throw new Error(
+    'Upload needs REMARKABLE_PARENT_FOLDER_UUID. Set it in .env or disable uploads with REMARKABLE_UPLOAD_ENABLED=false.',
+  );
+}
+
+function purgeFolder(config, parentId) {
+  const script = `
+cd ${config.remarkableXochitlDir}
+for f in *.metadata; do
+  if grep -q '\"parent\": \"${parentId}\"' "$f"; then
+    uuid="\${f%.metadata}"
+    rm -rf "\${uuid}"*
+  fi
+done
+`;
+
+  ssh(config.remarkableHost, [script], { stdio: 'inherit' });
+}
+
+function uploadPdf(config, parentId, file) {
+  const uuid = randomUUID();
+  const name = basename(file, '.pdf');
+
+  const metadata = JSON.stringify(
+    {
+      deleted: false,
+      lastModified: String(Date.now()),
+      metadatamodified: false,
+      modified: false,
+      parent: parentId,
+      pinned: false,
+      synced: false,
+      type: 'DocumentType',
+      version: 1,
+      visibleName: name,
+    },
+    null,
+    1,
+  );
+
+  const content = JSON.stringify({ fileType: 'pdf', pageCount: 0 }, null, 1);
+
+  const tmpMeta = `/tmp/${uuid}.metadata`;
+  const tmpContent = `/tmp/${uuid}.content`;
+
+  spawnSync('bash', ['-lc', `cat > ${tmpMeta} <<'JSON'\n${metadata}\nJSON`]);
+  spawnSync('bash', ['-lc', `cat > ${tmpContent} <<'JSON'\n${content}\nJSON`]);
+
+  scp(config.remarkableHost, file, `${config.remarkableXochitlDir}/${uuid}.pdf`);
+  scp(config.remarkableHost, tmpMeta, `${config.remarkableXochitlDir}/${uuid}.metadata`);
+  scp(config.remarkableHost, tmpContent, `${config.remarkableXochitlDir}/${uuid}.content`);
+}
+
+export async function uploadToRemarkable(config, { purge = true } = {}) {
+  if (!config.remarkableUploadEnabled) {
+    console.log('Upload skipped: REMARKABLE_UPLOAD_ENABLED=false');
+    return;
+  }
+
+  if (!remarkableAvailable(config.remarkableHost)) {
+    throw new Error(`Cannot reach reMarkable host \`${config.remarkableHost}\` over SSH.`);
+  }
+
+  const files = await getPdfFiles(config.outputDir);
+  if (files.length === 0) {
+    throw new Error(`No PDF files found in ${config.outputDir}. Run build first.`);
+  }
+
+  const parentId = resolveParentId(config);
+  if (purge) {
+    console.log(`Purging existing documents in folder UUID ${parentId}...`);
+    purgeFolder(config, parentId);
+  }
+
+  for (const file of files) {
+    console.log(`Uploading ${file}`);
+    uploadPdf(config, parentId, file);
+  }
+
+  console.log('Restarting xochitl...');
+  ssh(config.remarkableHost, ['systemctl restart xochitl'], { stdio: 'inherit' });
+}

package/styles/pdf-book-layout.css

@@ -0,0 +1,23 @@
+@page :left {
+  margin-top: var(--pdf-margin-top);
+  margin-right: var(--pdf-margin-inner);
+  margin-bottom: var(--pdf-margin-bottom);
+  margin-left: var(--pdf-margin-outer);
+}
+
+@page :right {
+  margin-top: var(--pdf-margin-top);
+  margin-right: var(--pdf-margin-outer);
+  margin-bottom: var(--pdf-margin-bottom);
+  margin-left: var(--pdf-margin-inner);
+}
+
+main.document h1 {
+  break-before: right;
+  page-break-before: right;
+}
+
+main.document > h1:first-child {
+  break-before: auto;
+  page-break-before: auto;
+}

package/styles/pdf.css

@@ -0,0 +1,18 @@
+@import "tailwindcss";
+
+:root {
+  color-scheme: light;
+}
+
+@page {
+  size: auto;
+}
+
+html {
+  @apply h-full w-full;
+  @apply bg-white text-gray-800;
+}
+
+body {
+  @apply bg-white text-gray-800;
+}

package/templates/document.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{documentTitle}}</title>
+    <style>
+{{css}}
+    </style>
+  </head>
+  <body style="--pdf-margin-top: {{marginTop}}; --pdf-margin-bottom: {{marginBottom}}; --pdf-margin-inner: {{marginInner}}; --pdf-margin-outer: {{marginOuter}};">
+    <main class="document prose prose-slate max-w-none">
+{{htmlBody}}
+    </main>
+  </body>
+</html>

package/templates/footer.html

@@ -0,0 +1,25 @@
+<div style="font-size: 9px; color: #6b7280; font-family: Arial, sans-serif; width: 100%; box-sizing: border-box; padding: 0 12mm;">
+  <span class="pageNumber" style="display:none;"></span>
+  <div id="footer-odd" style="display:flex; align-items:center; justify-content:space-between; width:100%;">
+    <span>{{title}}</span>
+    <span><span class="pageNumber"></span>/<span class="totalPages"></span></span>
+  </div>
+  <div id="footer-even" style="display:none; align-items:center; justify-content:space-between; width:100%;">
+    <span><span class="pageNumber"></span>/<span class="totalPages"></span></span>
+    <span>{{title}}</span>
+  </div>
+</div>
+<script>
+  (function () {
+    var pageNumberElement = document.querySelector('.pageNumber');
+    var pageNumber = Number((pageNumberElement && pageNumberElement.textContent) || '1');
+    var isEven = pageNumber % 2 === 0;
+    var oddFooter = document.getElementById('footer-odd');
+    var evenFooter = document.getElementById('footer-even');
+
+    if (oddFooter && evenFooter) {
+      oddFooter.style.display = isEven ? 'none' : 'flex';
+      evenFooter.style.display = isEven ? 'flex' : 'none';
+    }
+  })();
+</script>

package/templates/header.html

@@ -0,0 +1,25 @@
+<div style="font-size: 9px; color: #6b7280; font-family: Arial, sans-serif; width: 100%; box-sizing: border-box; padding: 0 12mm;">
+  <span class="pageNumber" style="display:none;"></span>
+  <div id="header-odd" style="display:flex; align-items:center; justify-content:space-between; width:100%;">
+    <span>{{title}}</span>
+    <span>{{fileName}}</span>
+  </div>
+  <div id="header-even" style="display:none; align-items:center; justify-content:space-between; width:100%;">
+    <span>{{fileName}}</span>
+    <span>{{title}}</span>
+  </div>
+</div>
+<script>
+  (function () {
+    var pageNumberElement = document.querySelector('.pageNumber');
+    var pageNumber = Number((pageNumberElement && pageNumberElement.textContent) || '1');
+    var isEven = pageNumber % 2 === 0;
+    var oddHeader = document.getElementById('header-odd');
+    var evenHeader = document.getElementById('header-even');
+
+    if (oddHeader && evenHeader) {
+      oddHeader.style.display = isEven ? 'none' : 'flex';
+      evenHeader.style.display = isEven ? 'flex' : 'none';
+    }
+  })();
+</script>