usfm2html 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# usfm2html-cli
+
+Convert USFM to HTML using Proskomma and Sofria renderers.
+
+Repository: `https://github.com/unfoldingWord/node-usfm2html-cli`
+
+## Install
+
+```
+# npm
+npm install -g usfm2html-cli
+
+# pnpm
+pnpm add -g usfm2html-cli
+
+# yarn
+yarn global add usfm2html-cli
+```
+
+## Usage
+
+```
+# Write to stdout
+usfm2html path/to/file.usfm > output.html
+
+# Write to a file directly
+usfm2html path/to/file.usfm -o output.html
+
+# Read from stdin
+cat path/to/file.usfm | usfm2html - > output.html
+```
+
+## Options
+
+```
+-o, --out <path>   Write output to a file instead of stdout
+-h, --help         Show help
+-v, --version      Show version
+```
+
+## Notes
+
+- Alignment markers are removed before rendering.
+- Output is a full HTML document with embedded CSS.
+- The renderer matches the Sofria HTML output used in the door43 preview app.

package/bin/usfm2html.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+run().catch((error) => {
+  console.error(`usfm2html: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "usfm2html",
+  "version": "0.1.0",
+  "type": "module",
+  "engines": {
+    "node": ">=18",
+    "pnpm": ">=8"
+  },
+  "bin": {
+    "usfm2html": "bin/usfm2html.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "lint": "echo 'No lint configured'"
+  },
+  "description": "Convert USFM to HTML using Proskomma and Sofria renderers.",
+  "keywords": [
+    "usfm",
+    "bible",
+    "proskomma",
+    "cli",
+    "html"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unfoldingWord/node-usfm2html-cli.git"
+  },
+  "homepage": "https://github.com/unfoldingWord/node-usfm2html-cli",
+  "bugs": {
+    "url": "https://github.com/unfoldingWord/node-usfm2html-cli/issues"
+  },
+  "license": "UNLICENSED",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "proskomma-core": "^0.11.3",
+    "proskomma-json-tools": "^0.9.1",
+    "usfm-alignment-remover": "^0.1.6"
+  }
+}

package/src/cli.js

@@ -0,0 +1,93 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { createRequire } from 'node:module';
+import { usfmToHtml } from './index.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
+const usage = `usfm2html <usfm file path> [options]\n\nOptions:\n  -o, --out <path>   Write output to a file instead of stdout\n  -h, --help         Show this help message\n  -v, --version      Show version`;
+
+const parseArgs = (argv) => {
+  const args = [...argv];
+  const positional = [];
+  let outPath = null;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '-o' || arg === '--out') {
+      if (i + 1 >= args.length) {
+        throw new Error('Missing value for -o/--out.');
+      }
+      outPath = args[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg === '-h' || arg === '--help') {
+      return { help: true };
+    }
+
+    if (arg === '-v' || arg === '--version') {
+      return { version: true };
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    positional.push(arg);
+  }
+
+  return { positional, outPath };
+};
+
+const readInput = async (inputPath) => {
+  if (inputPath === '-') {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+  }
+
+  return fs.readFile(inputPath, 'utf8');
+};
+
+const writeOutput = async (outPath, html) => {
+  if (!outPath) {
+    process.stdout.write(html);
+    return;
+  }
+
+  await fs.mkdir(path.dirname(outPath), { recursive: true });
+  await fs.writeFile(outPath, html, 'utf8');
+};
+
+export const run = async () => {
+  const { positional, outPath, help, version: showVersion } = parseArgs(process.argv.slice(2));
+
+  if (help) {
+    console.log(usage);
+    return;
+  }
+
+  if (showVersion) {
+    console.log(version);
+    return;
+  }
+
+  if (!positional || positional.length === 0) {
+    throw new Error('Missing USFM input path.');
+  }
+
+  if (positional.length > 1) {
+    throw new Error('Only one USFM input path can be provided.');
+  }
+
+  const inputPath = positional[0];
+  const usfm = await readInput(inputPath);
+  const html = usfmToHtml(usfm, { sourcePath: inputPath });
+  await writeOutput(outPath, html);
+};

package/src/index.js

@@ -0,0 +1,548 @@
+import { Proskomma } from 'proskomma-core';
+import { SofriaRenderFromProskomma, render } from 'proskomma-json-tools';
+import { removeAlignments } from 'usfm-alignment-remover';
+import { renderers } from './renderer/sofria2html.js';
+
+const defaultFlags = {
+  showWordAtts: false,
+  showTitles: true,
+  showHeadings: true,
+  showIntroductions: true,
+  showFootnotes: true,
+  showXrefs: true,
+  showParaStyles: true,
+  showCharacterMarkup: true,
+  showChapterLabels: true,
+  showVersesLabels: true,
+};
+
+const renderFlags = {
+  showWordAtts: false,
+  showTitles: true,
+  showHeadings: true,
+  showFootnotes: true,
+  showXrefs: true,
+  showChapterLabels: true,
+  showVersesLabels: true,
+  showCharacterMarkup: true,
+  showParaStyles: true,
+  selectedBcvNotes: [],
+};
+
+const extraCss = `
+pre {
+  font-family: inherit;
+  font-size: inherit;
+  padding-left: 2rem;
+  background-color: #f8f8f8;
+  border-radius: 4px;
+  overflow-x: auto;
+  border: 1px solid #e9ecef;
+  margin: 1em 0;
+}
+
+pre code {
+  border-radius: unset;
+  background: inherit;
+  padding: 0;
+  margin: 0;
+  font-family: inherit;
+  font-size: inherit;
+  color: inherit;
+}
+
+code {
+  background-color: #f4f4f4;
+  padding: 2px 6px;
+  border-radius: 3px;
+  font-family: 'Courier New', monospace;
+  font-size: 0.9em;
+  color: #d63384;
+}
+
+ol {
+  list-style: decimal;
+}
+
+ol ol {
+  list-style: upper-alpha;
+}
+
+ol ol ol {
+  list-style: upper-roman;
+}
+
+ol ol ol ol {
+  list-style: lower-roman;
+}
+
+ol ol ol ol ol {
+  list-style: lower-alpha;
+}
+
+ul, ol {
+  margin: 1em 0;
+  padding-left: 2em;
+}
+
+li {
+  margin: 0.5em 0;
+}
+
+blockquote {
+  margin-left: 40px;
+  margin-right: 40px;
+  color: #333;
+  padding: 1.5em;
+  line-height: 1.6;
+  border-left: 4px solid #ccc;
+  background-color: #f9f9f9;
+}
+
+blockquote cite {
+  display: block;
+  text-align: right;
+  font-size: 0.9em;
+  color: #666;
+  margin-top: 1em;
+}
+
+blockquote p {
+  margin: 0.5em 0;
+}
+
+blockquote p:first-child {
+  margin-top: 0;
+}
+
+blockquote p:last-child {
+  margin-bottom: 0;
+}
+
+table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 1.5em 0;
+  border: 1px solid #dee2e6;
+}
+
+th, td {
+  border: 1px solid #dee2e6;
+  padding: 8px 12px;
+  text-align: left;
+}
+
+th {
+  background-color: #f8f9fa;
+  font-weight: bold;
+  color: #495057;
+}
+
+tbody tr:nth-child(even) {
+  background-color: #f9f9f9;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  color: #495057;
+  margin-top: 1.5em;
+  margin-bottom: 0.5em;
+  font-weight: bold;
+  line-height: 1.2;
+}
+
+h1 {
+  font-size: 2em;
+  padding-bottom: 0.3em;
+}
+
+h2 {
+  font-size: 1.5em;
+}
+
+h3 {
+  font-size: 1.25em;
+}
+
+p {
+  margin: 1em 0;
+  line-height: 1.6;
+}
+
+a {
+  color: #007acc;
+  text-decoration: none;
+}
+
+a:hover {
+  text-decoration: underline;
+}
+
+a.internal-link {
+  color: #007acc;
+  cursor: s-resize;
+}
+
+a.external-link {
+  position: relative;
+  font-weight: bold !important;
+  color: #666 !important;
+  border-bottom: dashed 1px #666 !important;
+  text-decoration: none !important;
+  cursor: ne-resize !important;
+}
+
+a.external-link::after {
+  content: ' [link]';
+  font-size: 0.8em;
+  vertical-align: super;
+}
+
+.back-refs a {
+  position: relative;
+  cursor: n-resize;
+}
+
+.verse-ref {
+  font-weight: bold;
+  color: #0066cc;
+  text-decoration: none;
+}
+
+.verse-ref:hover {
+  text-decoration: underline;
+}
+
+.translation-note {
+  background-color: #fff3cd;
+  border: 1px solid #ffeaa7;
+  padding: 1em;
+  margin: 1em 0;
+  border-radius: 4px;
+  border-left: 4px solid #ffc107;
+}
+
+.note-header {
+  font-weight: bold;
+  color: #856404;
+  margin-bottom: 0.5em;
+}
+
+.cross-ref {
+  font-size: 0.9em;
+  color: #6c757d;
+  font-style: italic;
+}
+
+.original-text,
+.hebrew-text {
+  font-family: "Ezra", "SBL Hebrew", "Times New Roman", serif;
+  font-size: 1.1em;
+  font-weight: normal;
+  direction: rtl;
+}
+
+.greek-text {
+  font-family: "CharisSIL", "SBL Greek", "Gentium Plus", "Times New Roman", serif;
+  font-size: 1.1em;
+  direction: ltr;
+}
+
+.strongs {
+  font-size: 0.8em;
+  color: #6c757d;
+  font-weight: normal;
+}
+
+strong, b {
+  font-weight: bold;
+}
+
+em, i {
+  font-style: italic;
+}
+
+hr {
+  border: none;
+  height: 1px;
+  background-color: #dee2e6;
+  margin: 2em 0;
+}
+
+mark, .highlight {
+  background-color: #fff3cd;
+  padding: 1px 2px;
+  border-radius: 2px;
+}
+
+img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  margin: 1em auto;
+}
+
+dl {
+  margin: 1em 0;
+}
+
+dt {
+  font-weight: bold;
+  margin-top: 1em;
+  color: #495057;
+}
+
+dd {
+  margin-left: 2em;
+  margin-bottom: 0.5em;
+}
+
+.footnote {
+  font-size: 0.9em;
+  color: #6c757d;
+  border-top: 1px solid #dee2e6;
+  padding-top: 0.5em;
+  margin-top: 2em;
+}
+
+h1 {
+  column-span: all;
+}
+
+.new-page {
+  break-after: page;
+  column-span: all;
+}
+
+.header-link {
+  text-decoration: none;
+  color: inherit;
+}
+
+.web-preview .paras_usfm_f {
+  padding-left: 0.5em;
+  padding-right: 0.5em;
+  background-color: #ccc;
+  margin-top: 1em;
+  margin-bottom: 1em;
+}
+
+.paras_usfm_fq, .paras_usfm_fqa {
+  font-style: italic;
+}
+
+.implied-word-text {
+  color: #999;
+  font-weight: bold;
+  font-size: 0.9em;
+}
+
+:root {
+  --chapter-gutter: 4.5em;
+  --verse-gutter: -2em;
+  --label-gap: 1em;
+  --chapter-nudge: 4em;
+  --poetry-gutter: calc(var(--chapter-gutter) + var(--verse-gutter) + var(--label-gap));
+  --q2-extra: 2em;
+  --q3-extra: 3.5em;
+  --q4-extra: 5em;
+  --chapter-raise: 1em;
+  --label-top: 0.4em;
+  --chapter-break: 1.2em;
+}
+
+p.paras_usfm_q,
+p.paras_usfm_q2,
+p.paras_usfm_q3,
+p.paras_usfm_q4 {
+  position: relative !important;
+  text-indent: 0 !important;
+}
+
+p.paras_usfm_q {
+  padding-left: var(--poetry-gutter) !important;
+}
+
+p.paras_usfm_q2 {
+  padding-left: calc(var(--poetry-gutter) + var(--q2-extra)) !important;
+}
+
+p.paras_usfm_q3 {
+  padding-left: calc(var(--poetry-gutter) + var(--q3-extra)) !important;
+}
+
+p.paras_usfm_q4 {
+  padding-left: calc(var(--poetry-gutter) + var(--q4-extra)) !important;
+}
+
+p.paras_usfm_q > .marks_chapter_label,
+p.paras_usfm_q2 > .marks_chapter_label,
+p.paras_usfm_q3 > .marks_chapter_label,
+p.paras_usfm_q4 > .marks_chapter_label,
+p.paras_usfm_q > .marks_verses_label,
+p.paras_usfm_q2 > .marks_verses_label,
+p.paras_usfm_q3 > .marks_verses_label,
+p.paras_usfm_q4 > .marks_verses_label {
+  position: absolute !important;
+  float: none !important;
+  display: block !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  white-space: nowrap !important;
+  line-height: 1 !important;
+  z-index: 2 !important;
+}
+
+p.paras_usfm_q > .marks_chapter_label,
+p.paras_usfm_q2 > .marks_chapter_label,
+p.paras_usfm_q3 > .marks_chapter_label,
+p.paras_usfm_q4 > .marks_chapter_label {
+  left: calc(-1 * var(--chapter-nudge)) !important;
+  top: var(--label-top) !important;
+  width: var(--chapter-gutter) !important;
+  text-align: right !important;
+  transform: translateY(calc(-1 * var(--chapter-raise))) !important;
+  transform-origin: top right;
+}
+
+p.paras_usfm_q > .marks_verses_label,
+p.paras_usfm_q2 > .marks_verses_label,
+p.paras_usfm_q3 > .marks_verses_label,
+p.paras_usfm_q4 > .marks_verses_label {
+  left: calc(var(--chapter-gutter) + var(--label-gap) - var(--chapter-nudge)) !important;
+  top: var(--label-top) !important;
+  width: var(--verse-gutter) !important;
+  text-align: right !important;
+}
+
+p.paras_usfm_q > .marks_chapter_label a,
+p.paras_usfm_q2 > .marks_chapter_label a,
+p.paras_usfm_q3 > .marks_chapter_label a,
+p.paras_usfm_q4 > .marks_chapter_label a,
+p.paras_usfm_q > .marks_verses_label a,
+p.paras_usfm_q2 > .marks_verses_label a,
+p.paras_usfm_q3 > .marks_verses_label a,
+p.paras_usfm_q4 > .marks_verses_label a {
+  display: inline !important;
+  float: none !important;
+  position: static !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  text-decoration: none;
+}
+
+p.paras_usfm_q:has(> .marks_chapter_label) {
+  margin-top: var(--chapter-break) !important;
+  padding-top: calc(var(--chapter-raise) * 0.6) !important;
+}
+
+@supports not selector(p:has(> span)) {
+  p.paras_usfm_q > .marks_chapter_label::before {
+    content: "";
+    display: block;
+    height: var(--chapter-break);
+  }
+}
+
+.implied-word-start,
+.implied-word-end {
+  display: none;
+}
+`;
+
+const buildCss = () => {
+  const baseCss = render.sofria2web.renderStyles.styleAsCSS(render.sofria2web.renderStyles.styles);
+  return `${baseCss}\n${extraCss}`;
+};
+
+const stripTags = (input) => input.replace(/<[^>]*>/g, '');
+
+const escapeAttribute = (input) =>
+  input
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+
+const parseHtml = (html, book, titleText, showChapters = true) => {
+  const titleMatch = html.match(/<p [^>]*>(.*?)<\/p>/);
+  const rawTitle = titleText || (titleMatch ? stripTags(titleMatch[1]) : '');
+  const safeTitle = escapeAttribute(rawTitle);
+  let updated = html.replace(/<p /, `<p id="nav-${book}" `);
+
+  updated = updated.replaceAll(
+    /<span id="chapter-(\d+)-verse-(\d+)"([^>]*)>(\d+)<\/span>/g,
+    `<span id="nav-${book}-$1-$2"$3><a href="#nav-${book}-$1-$2" class="header-link">$4</a></span>`
+  );
+
+  updated = updated.replaceAll(
+    /<span id="chapter-(\d+)"([^>]+)>([\d]+)<\/span>/gi,
+    `<span id="nav-${book}-$1"${showChapters && safeTitle ? ` data-toc-title="${safeTitle} $1"` : ''}$2><a href="#nav-${book}-$1-1" class="header-link">$3</a></span>`
+  );
+
+  updated = updated.replace(/<span([^>]+style="[^">]+#CCC[^">]+")/gi, '<span$1 class="footnote"');
+  updated = updated.replace(/[\u00A0\u202F\u2009 ]+/g, ' ');
+  updated = updated.replace(/(\d{1,3})(?:\s*,\s*\d{3})+\b/g, (m) => m.replace(/\s*,\s*/g, ','));
+
+  const footnotes = updated.match(/<span class="footnote">/g);
+  if (footnotes) {
+    footnotes.forEach((footnote, index) => {
+      const footnoteId = `footnote-${index}`;
+      const anchor = `<a href="#${footnoteId}">${index + 1}.</a>`;
+      updated = updated.replace(footnote, `${footnote}<span id="${footnoteId}">${anchor}</span>`);
+    });
+  }
+
+  return `\n<div class="section bible-book" id="nav-${book}"${safeTitle ? ` data-toc-title="${safeTitle}"` : ''}>\n${updated}\n</div>\n`;
+};
+
+const normalizeUsfm = (usfm) => {
+  const withoutBom = usfm.replace(/^\uFEFF/, '');
+  const withoutAlignments = removeAlignments(withoutBom);
+  return withoutAlignments.replace(/\\s5\s*\n/g, '').replace(/\r\n/g, '\n');
+};
+
+const extractBookId = (usfm) => {
+  const idMatch = usfm.match(/^\\id\s+([A-Za-z0-9]{3})\b/m);
+  return idMatch ? idMatch[1].toLowerCase() : 'book';
+};
+
+const extractTitle = (usfm) => {
+  const titleMatch = usfm.match(/^\\h\s+(.+)$/m) || usfm.match(/^\\toc1\s+(.+)$/m);
+  return titleMatch ? titleMatch[1].trim() : 'USFM Render';
+};
+
+export const usfmToHtml = (usfm, options = {}) => {
+  const pk = new Proskomma();
+  const normalized = normalizeUsfm(usfm);
+  const bookId = options.bookId || extractBookId(normalized);
+  const title = options.title || extractTitle(normalized);
+
+  const result = pk.importDocument({ lang: 'xxx', abbr: 'XXX' }, 'usfm', normalized);
+  if (!result?.id) {
+    throw new Error('Unable to import USFM into Proskomma.');
+  }
+
+  const config = {
+    ...defaultFlags,
+    ...renderFlags,
+    selectedBcvNotes: [],
+    renderers,
+  };
+
+  const renderer = new SofriaRenderFromProskomma({
+    proskomma: pk,
+    actions: render.sofria2web.renderActions.sofria2WebActions,
+  });
+
+  const output = {};
+  renderer.renderDocument({
+    config,
+    docId: result.id,
+    output,
+  });
+
+  const body = parseHtml(output.paras, bookId, title, true);
+  const css = buildCss();
+
+  return `<!doctype html>\n<html lang="en">\n<head>\n<meta charset="utf-8">\n<title>${title}</title>\n<style>\n${css}\n</style>\n</head>\n<body class="web-preview">\n${body}\n</body>\n</html>\n`;
+};

package/src/renderer/sofria2html.js

@@ -0,0 +1,78 @@
+const renderers = {
+  text: (text) =>
+    text
+      .replace(/{/g, '<span class="implied-word"><span class="implied-word-start">{</span><span class="implied-word-text">')
+      .replace(/}/g, '</span><span class="implied-word-end">}</span></span>'),
+  chapter: '0',
+  chapter_label(number) {
+    this.chapter = number;
+    return `<span id="chapter-${this.chapter}" class="marks_chapter_label">${number}</span>`;
+  },
+  verses_label(number) {
+    return `<span id="chapter-${this.chapter}-verse-${number}" class="marks_verses_label">${number}</span>`;
+  },
+  paragraph: (subType, content, footnoteNo) => {
+    const paraClass = subType.split(':')[1];
+    let paraTag = 'p';
+    if (['f', 'x'].includes(paraClass)) {
+      paraTag = 'span';
+    } else if (['s', 'ms', 'imt', 'imte', 'mt'].includes(paraClass)) {
+      paraTag = 'h1';
+    } else if (['s2', 'ms2', 'imt2', 'imte2', 'mt2', 'mr', 'sr'].includes(paraClass)) {
+      paraTag = 'h2';
+    } else if (['s3', 'ms3', 'imt3', 'imte3', 'mt3', 'r', 'd'].includes(paraClass)) {
+      paraTag = 'h3';
+    } else if (['s4', 'ms4', 'imt4', 'imte4', 'mt4'].includes(paraClass)) {
+      paraTag = 'h4';
+    }
+
+    const idAttr = paraClass === 'f' ? `id="footnote-${footnoteNo}" ` : '';
+    return `<${paraTag} ${idAttr}class="paras_usfm_${paraClass}">${content.join('')}</${paraTag}>`;
+  },
+  wrapper: (atts, subType, content) => {
+    if (subType === 'cell') {
+      if (atts.role === 'body') {
+        return `<td colspan=${atts.nCols} style="text-align:${atts.alignment}">${content.join('')}</td>`;
+      }
+      return `<th colspan=${atts.nCols} style="text-align:${atts.alignment}">${content.join('')}</th>`;
+    }
+
+    return `<span class="wrappers_usfm_${subType.split(':')[1]}">${content.join('')}</span>`;
+  },
+  wWrapper: (atts, content) => {
+    const safeContent = Array.isArray(content) ? content.join('') : content;
+    if (Object.keys(atts).length === 0) {
+      return safeContent;
+    }
+
+    return `<span
+          style={{
+              display: "inline-block",
+              verticalAlign: "top",
+              textAlign: "center"
+          }}
+      >
+      <div>${safeContent}</div>${Object.entries(atts)
+          .map(
+            (a) =>
+              `<div
+                          style={{
+                              fontSize: "xx-small",
+                              fontWeight: "bold"
+                          }}
+                      >
+                      {${a[0]} = ${a[1]}} 
+                      </div>`
+          )
+          .join('')
+        }</span>`;
+  },
+  milestone: () => '',
+  startChapters: (nCols) => `<section class="chapters" style="columns: ${nCols}">`,
+  endChapters: () => '</section>',
+  mergeParas: (paras) => paras.join('\n'),
+  row: (content) => `<tr>${content.join('')}</tr>`,
+  table: (content) => `<table border>${content.join(' ')}</table>`,
+};
+
+export { renderers };