@markdown-viewer/documd 5.3.1 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  The official CLI of [docu.md Markdown Viewer](https://docu.md).
4
4
 
5
5
  Render Markdown, diagrams and GitBook books to **HTML, EPUB, DOCX, PDF, SVG, PNG
6
- and DrawIO** with headless Chrome — powered by the docu.md Markdown Viewer
6
+ and DrawIO** with headless Chromium — powered by the docu.md Markdown Viewer
7
7
  engine (the same renderers and exporters as the browser extension).
8
8
 
9
9
  - Website: <https://docu.md>
@@ -147,13 +147,70 @@ e.g. when a missing optional image should not stop a batch conversion.
147
147
  | `--merge-empty-cells` | Merge empty table cells (on by default) |
148
148
  | `--first-line-indent <n>` | First-line indent in characters, 0-4 (default 2) |
149
149
  | `--merge-empty-cells` | Merge empty Markdown table cells |
150
- | `--chrome <path>` | Explicit Chrome executable path |
150
+ | `--chrome <path>` | Explicit Chrome/Chromium binary (or `DOCUMD_CHROME_PATH`) |
151
+ | `--browser-arg <flag>` | Extra Chromium flag, repeatable (or `DOCUMD_CHROME_ARGS`) |
151
152
  | `--timeout <seconds>` | Render timeout (default 120) |
152
153
  | `-h, --help` | Show help |
153
154
 
155
+ ## Browser
156
+
157
+ Every export runs in a headless Chromium. Which one, in order:
158
+
159
+ 1. the binary given by `--chrome <path>` or `DOCUMD_CHROME_PATH`;
160
+ 2. Playwright's bundled Chromium (`npx playwright install chromium`) — a
161
+ headless build that needs no GUI session and no system install, so it is the
162
+ one that starts in containers and sandboxes;
163
+ 3. the installed Chrome (`channel: "chrome"`), for CLI installs that never
164
+ fetched a Playwright browser.
165
+
166
+ The browser is started headless and **sandboxless** (`--no-sandbox`) — Chromium's
167
+ own sandbox cannot nest inside the environments documd runs in (see *Sandboxed
168
+ runs* below), so the isolation is whatever the surrounding environment provides.
169
+ PDFs are printed through the inline CDP transfer, so no host temp directory
170
+ write is needed either. Before an export starts, documd checks that the browser
171
+ it picked can actually draw a page; a browser that cannot is reported and the
172
+ next candidate is tried.
173
+
174
+ Extra Chromium flags: `--browser-arg <flag>` (repeatable) and
175
+ `DOCUMD_CHROME_ARGS` (whitespace separated), e.g.
176
+ `--browser-arg --font-render-hinting=none`.
177
+
178
+ ## Sandboxed runs (CI, containers, macOS Seatbelt)
179
+
180
+ Running inside another sandbox changes two things:
181
+
182
+ - **Chromium's sandbox cannot nest.** In a macOS Seatbelt sandbox (e.g. boxsh),
183
+ a container without the sandbox privileges, or as root on Linux, the kernel
184
+ refuses to install Chromium's sandbox a second time
185
+ (`deny forbidden-sandbox-reinit`). Two symptoms: the browser aborts while
186
+ starting (`GPU process isn't usable. Goodbye`, `bootstrap_check_in …
187
+ Permission denied`), or it starts and then cannot draw a page
188
+ (`browser.newPage: Target crashed`), because the renderer is the process that
189
+ re-enters the sandbox. documd therefore starts Chromium sandboxless from the
190
+ start — no flag and no retry needed in these environments. A browser that
191
+ still cannot render is reported on stderr and the next candidate (the
192
+ installed Chrome) is tried.
193
+ - **The OS temp directory may be read-only.** The print stream Chromium writes
194
+ for `page.pdf()` lands in the OS user temp directory (`/private/var/folders/…`
195
+ on macOS — Chromium ignores `$TMPDIR`), which sandboxes refuse. documd
196
+ transfers the PDF inline over CDP instead, so rendering, HTML export,
197
+ screenshots *and* PDF all work without write access there (a document large
198
+ enough to hit the protocol message size limit falls back to the stream path).
199
+
200
+ A GUI Chrome cannot start in a sandbox without a window server at all (it aborts
201
+ in `TransformProcessType`) — that is what the bundled headless Chromium above is
202
+ for.
203
+
154
204
  ## Notes
155
205
 
156
- - Requires Chrome; pass `--chrome` to use a specific binary.
206
+ - Needs a browser: Playwright's bundled Chromium, or an installed Chrome. Pass
207
+ `--chrome` to use a specific binary.
208
+ - **Documents are treated as untrusted input.** Markup written in a document is
209
+ sanitized before it reaches the DOM (in an inert `<template>`, so nothing loads
210
+ or runs while it is cleaned), and the page every export renders in carries a
211
+ CSP without `'unsafe-inline'` scripts — so even a sanitizer gap cannot turn
212
+ document markup into code. Inline styles and the diagram engines' remote fonts
213
+ stay allowed, which is why styled HTML blocks and figures still render.
157
214
  - Themes, fonts, code highlighting, math and layout settings mirror the
158
215
  docu.md Markdown Viewer extension.
159
216
  - Report file paths go to stdout; warnings and render-error reports go to