diff --git a/README.md b/README.md index 5236b2019..2a1335c97 100644 --- a/README.md +++ b/README.md @@ -431,6 +431,7 @@ Other references: [docs/gbrain-sync.md](docs/gbrain-sync.md) (sync-specific guid | Doc | What it covers | |-----|---------------| | [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill (includes Greptile integration) | +| [Diagrams & Document Formats](docs/howto-diagrams-and-formats.md) | Mermaid/excalidraw fences in PDFs, image sizing and safety defaults, `--to html\|docx`, `/diagram` triplets | | [Builder Ethos](ETHOS.md) | Builder philosophy: Boil the Ocean, Search Before Building, three layers of knowledge | | [Using GBrain with GStack](USING_GBRAIN_WITH_GSTACK.md) | Every path, flag, bin helper, and troubleshooting step for `/setup-gbrain` | | [GBrain Sync](docs/gbrain-sync.md) | Cross-machine memory setup, privacy modes, troubleshooting | diff --git a/docs/howto-diagrams-and-formats.md b/docs/howto-diagrams-and-formats.md index 383309a6b..b051a4c14 100644 --- a/docs/howto-diagrams-and-formats.md +++ b/docs/howto-diagrams-and-formats.md @@ -49,6 +49,12 @@ markdown file) and **never truncate** — every image caps at the content box. Oversized photos downscale to print resolution (300dpi at the content width), so a phone photo doesn't bloat the document. +Image safety defaults: remote (http/https) images are **blocked with a +visible placeholder** unless you pass `--allow-network`. An image path that +resolves outside the markdown's directory (even through a symlink) still +inlines but warns loudly. Files over 64MB and non-regular files (fifos, +devices) degrade to a placeholder instead of hanging the render. + Per-image directives go immediately after the image: ```markdown @@ -113,8 +119,10 @@ For documents, embed the `.mmd` source in your markdown instead of the PNG — make-pdf generate docs.md --strict ``` -Missing local images and unfetched remote images exit non-zero instead of -rendering a placeholder — for docs pipelines where a broken image should +Missing local images, blocked remote images, out-of-tree image reads (a path +or symlink resolving outside the markdown's directory), oversized files +(>64MB), and non-regular files all exit non-zero instead of degrading to a +warning or placeholder — for docs pipelines where a broken image should break the build. ## Troubleshooting @@ -127,5 +135,7 @@ break the build. trick — top-level `flowchart TB`, two subgraphs with `direction LR` and `direction RL`, connect the *subgraphs* (node-level edges across subgraph boundaries silently disable `direction`). -- **Remote images** → not fetched by default (offline posture). Pass +- **"[remote image blocked]" placeholder** → remote images are never fetched + by default (offline posture); the tag is replaced with a visible + placeholder so Chromium can't fetch it at print time either. Pass `--allow-network` to opt in. diff --git a/make-pdf/SKILL.md b/make-pdf/SKILL.md index ef235371b..bef600ae6 100644 --- a/make-pdf/SKILL.md +++ b/make-pdf/SKILL.md @@ -625,6 +625,13 @@ markdown file). Every image caps at the content box — zero truncation, ever. Oversized photos downscale to print resolution (300dpi) so payloads stay small with no visible quality loss. +Remote (http/https) images are **blocked with a visible placeholder** by +default — offline posture; pass `--allow-network` to fetch them. An image +that resolves outside the markdown's directory (even via symlink) still +inlines, but warns loudly; `--strict` makes it fatal. Files over 64MB or +non-regular files (fifos, devices) degrade to a placeholder instead of +hanging the run. + Per-image directives, written immediately after the image: ``` @@ -657,7 +664,8 @@ $P generate readme.md out.docx --to docx # Word: content fidelity (headings, ### CI mode — fail loud on missing assets ```bash -$P generate docs.md --strict # missing/remote images exit non-zero +$P generate docs.md --strict # missing, remote, out-of-tree, oversized, + # and non-regular-file images exit non-zero # instead of warn + placeholder ``` @@ -682,7 +690,8 @@ Branding: Output: --to pdf|html|docx Output format (default: pdf). html = single self-contained file; docx = content fidelity. - --strict Missing/remote images fail the run (CI mode). + --strict Missing, remote, out-of-tree, oversized, or + non-regular-file images fail the run (CI mode). --page-numbers "N of M" footer (default on) --tagged Accessible PDF (default on) --outline PDF bookmarks from headings (default on) @@ -690,8 +699,9 @@ Output: --verbose Per-stage timings Network: - --allow-network Fetch external images. Off by default - (blocks tracking pixels). + --allow-network Fetch external images. Off by default: remote + images render as a visible blocked placeholder + (no tracking pixels fetch at print time). Metadata: --title "..." Document title (defaults to first H1) @@ -719,8 +729,9 @@ If the user has a `.md` file open and says "make it look nice", propose `--no-syntax` once that flag exists. For now, remove fenced code blocks and regenerate. - Paged.js timeout → probably no headings in the markdown. Drop `--toc`. -- External image missing → add `--allow-network` (understand you're giving - the markdown file permission to fetch from its image URLs). +- "[remote image blocked]" placeholder in the output → add `--allow-network` + (understand you're giving the markdown file permission to fetch from its + image URLs). - Generated PDF too tall/wide → `--page-size a4` or `--margins 0.75in`. ## Output contract diff --git a/make-pdf/SKILL.md.tmpl b/make-pdf/SKILL.md.tmpl index 7ad10b14c..3d54870c9 100644 --- a/make-pdf/SKILL.md.tmpl +++ b/make-pdf/SKILL.md.tmpl @@ -121,6 +121,13 @@ markdown file). Every image caps at the content box — zero truncation, ever. Oversized photos downscale to print resolution (300dpi) so payloads stay small with no visible quality loss. +Remote (http/https) images are **blocked with a visible placeholder** by +default — offline posture; pass `--allow-network` to fetch them. An image +that resolves outside the markdown's directory (even via symlink) still +inlines, but warns loudly; `--strict` makes it fatal. Files over 64MB or +non-regular files (fifos, devices) degrade to a placeholder instead of +hanging the run. + Per-image directives, written immediately after the image: ``` @@ -153,7 +160,8 @@ $P generate readme.md out.docx --to docx # Word: content fidelity (headings, ### CI mode — fail loud on missing assets ```bash -$P generate docs.md --strict # missing/remote images exit non-zero +$P generate docs.md --strict # missing, remote, out-of-tree, oversized, + # and non-regular-file images exit non-zero # instead of warn + placeholder ``` @@ -178,7 +186,8 @@ Branding: Output: --to pdf|html|docx Output format (default: pdf). html = single self-contained file; docx = content fidelity. - --strict Missing/remote images fail the run (CI mode). + --strict Missing, remote, out-of-tree, oversized, or + non-regular-file images fail the run (CI mode). --page-numbers "N of M" footer (default on) --tagged Accessible PDF (default on) --outline PDF bookmarks from headings (default on) @@ -186,8 +195,9 @@ Output: --verbose Per-stage timings Network: - --allow-network Fetch external images. Off by default - (blocks tracking pixels). + --allow-network Fetch external images. Off by default: remote + images render as a visible blocked placeholder + (no tracking pixels fetch at print time). Metadata: --title "..." Document title (defaults to first H1) @@ -215,8 +225,9 @@ If the user has a `.md` file open and says "make it look nice", propose `--no-syntax` once that flag exists. For now, remove fenced code blocks and regenerate. - Paged.js timeout → probably no headings in the markdown. Drop `--toc`. -- External image missing → add `--allow-network` (understand you're giving - the markdown file permission to fetch from its image URLs). +- "[remote image blocked]" placeholder in the output → add `--allow-network` + (understand you're giving the markdown file permission to fetch from its + image URLs). - Generated PDF too tall/wide → `--page-size a4` or `--margins 0.75in`. ## Output contract