mirror of
https://github.com/garrytan/gstack.git
synced 2026-06-17 07:10:12 +02:00
docs: sync make-pdf image-policy docs with final shipped behavior (v1.58.0.0)
The docs wave (87594420) predated the final review-wave commits, so two
docs drifted from shipped behavior:
- make-pdf/SKILL.md.tmpl + generated SKILL.md: remote images are BLOCKED
with a visible placeholder (not warned-and-kept); out-of-tree reads
(including via symlink) warn and --strict makes them fatal; --strict
also covers oversized (>64MB) and non-regular files; troubleshooting
entry now names the actual "[remote image blocked]" symptom.
- docs/howto-diagrams-and-formats.md: same corrections in the image
section, CI section, and troubleshooting.
- README.md: docs/howto-diagrams-and-formats.md added to the Docs table
(was unreachable from any entry-point doc).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -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 |
|
||||
|
||||
@@ -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.
|
||||
|
||||
+17
-6
@@ -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
|
||||
|
||||
+17
-6
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user