feat(docs): generate PDF previews in the browser instead of committing them

.github/workflows/ci.yml

@@ -79,3 +79,10 @@ jobs:
       - name: Test docs examples
         run: go test ./assets/examples/...
         working-directory: docs
+
+      # docs/assets/js/paper-fs.js hand-implements the filesystem syscalls Go's
+      # js/wasm runtime calls. A regression there does not fail loudly — the
+      # renderer draws an error box and still emits a valid PDF — so it is
+      # pinned by its own tests. Node is preinstalled on ubuntu-latest.
+      - name: Test browser filesystem shim
+        run: node --test docs/assets/js/paper-fs.test.mjs

.github/workflows/pages.yml

@@ -46,14 +46,20 @@ jobs:
           cp -r docs _site
           rm -f _site/go.mod _site/go.sum
           rm -rf _site/plans
-          # Keep assets/examples/*/main.go — docsify embeds them via ':include'.
+          # Keep assets/examples/**/*.go — docsify embeds them via ':include'.
           find _site -name '*_test.go' -delete
-          mkdir -p _site/playground
-          cp examples/cmd/wasm/web/index.html      _site/playground/
-          cp examples/cmd/wasm/web/paper.wasm       _site/playground/
-          cp examples/cmd/wasm/web/wasm_exec.js     _site/playground/
+          # The docs pages generate their PDF previews in the browser, so the
+          # wasm has to be reachable from the site root as well as the
+          # playground. The playground keeps its own copy so that it stays
+          # servable standalone from examples/cmd/wasm/web.
+          mkdir -p _site/assets/wasm _site/playground
+          cp -f examples/cmd/wasm/web/paper.wasm    _site/assets/wasm/
+          cp -f examples/cmd/wasm/web/wasm_exec.js  _site/assets/wasm/
+          cp -f examples/cmd/wasm/web/index.html   _site/playground/
+          cp -f examples/cmd/wasm/web/paper.wasm    _site/playground/
+          cp -f examples/cmd/wasm/web/wasm_exec.js  _site/playground/
           touch _site/.nojekyll
-          echo "Assembled site:" && ls -1 _site && echo "playground:" && ls -1 _site/playground
+          echo "Assembled site:" && ls -1 _site && echo "wasm:" && ls -1 _site/assets/wasm && echo "playground:" && ls -1 _site/playground
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3

.gitignore

@@ -34,6 +34,22 @@ docs/plans/
 examples/cmd/wasm/web/paper.wasm
 examples/cmd/wasm/web/wasm_exec.js
 
+# Copy of the wasm the docs site serves for its in-browser PDF previews
+# (placed by `make docs` / `make site`; built, not authored)
+docs/assets/wasm/
+
+# Example PDFs are generated by `make examples` and rendered in the browser by
+# paper.wasm, so they are no longer committed. Six survive: five whose inputs are
+# impractical to ship to a browser and stay static embeds, plus paper.pdf, which
+# the mergepdf example reads as an input.
+docs/assets/pdf/*.pdf
+!docs/assets/pdf/paper.pdf
+!docs/assets/pdf/showcase.pdf
+!docs/assets/pdf/background.pdf
+!docs/assets/pdf/customfont.pdf
+!docs/assets/pdf/mergepdf.pdf
+!docs/assets/pdf/disablepagebreak.pdf
+
 # playwright-cli E2E scratch output
 .playwright-cli/
 

DEVELOPMENT.md

@@ -79,8 +79,26 @@ Tests must create mocks via constructors (`m := mocks.NewProvider(t)`);
 ## Docs site
 
 ```bash
-make docs       # docsify serve docs/ on http://localhost:3000
+make docs       # builds the wasm, copies it into docs/assets/wasm/, then
+                # docsify serve docs/ on http://localhost:3000
+make site       # assembles the full Pages site into site/ and serves :8080
 ```
 
+`make docs` depends on `make wasm` because the feature pages generate their PDF
+previews in the browser from `docs/assets/wasm/paper.wasm`; without it every
+preview renders an error box. That directory is generated and git-ignored.
+
+Example PDFs under `docs/assets/pdf/` are produced by `make examples` and are
+**not** committed, apart from six: `background`, `customfont`,
+`disablepagebreak`, `mergepdf` and `showcase` stay static embeds because their
+inputs are impractical to ship to a browser, and `paper.pdf` is an input the
+`mergepdf` example reads. Note that `paper.pdf` is generated by
+`examples/cmd/dev/pdf`, not by `make examples`.
+
+Regenerating the tracked PDFs always produces a diff even with no code change,
+because no example sets `WithDeterministic` and the embedded `CreationDate`
+moves. Check the structure fixtures under `test/paper/examples/` for real
+output changes.
+
 `docs/plans/` holds internal planning documents and is excluded from version
 control and the site.

Makefile

@@ -18,6 +18,10 @@ test:
 	go test $(GO_PATHS)
 	cd examples && go test ./...
 	cd docs && go test ./assets/examples/...
+	# The browser filesystem shim implements a Go syscall contract by hand, and a
+	# break in it renders an error box into an otherwise valid PDF rather than
+	# failing, so it gets its own tests.
+	node --test docs/assets/js/paper-fs.test.mjs
 
 .PHONY: fmt
 fmt:
@@ -44,8 +48,13 @@ mock-lint:
 install:
 	bash shell/install.sh
 
+# Serve the docs locally. Depends on wasm because the feature pages generate
+# their PDF previews in the browser from docs/assets/wasm/paper.wasm.
 .PHONY: docs
-docs:
+docs: wasm
+	mkdir -p docs/assets/wasm
+	# -f: the toolchain's wasm_exec.js is read-only (0444), so the copy is too.
+	cp -f examples/cmd/wasm/web/paper.wasm examples/cmd/wasm/web/wasm_exec.js docs/assets/wasm/
 	docsify serve docs/
 
 .PHONY: godoc
@@ -72,46 +81,49 @@ site: wasm
 	cp -r docs site
 	rm -f site/go.mod site/go.sum
 	rm -rf site/plans
-	find site -name '*.go' -delete
-	mkdir -p site/playground
-	cp examples/cmd/wasm/web/index.html examples/cmd/wasm/web/paper.wasm examples/cmd/wasm/web/wasm_exec.js site/playground/
+	# Only test files go: docsify ':include's the example sources, so deleting
+	# every *.go (as this used to) left the code samples on the site empty.
+	find site -name '*_test.go' -delete
+	mkdir -p site/assets/wasm site/playground
+	cp -f examples/cmd/wasm/web/paper.wasm examples/cmd/wasm/web/wasm_exec.js site/assets/wasm/
+	cp -f examples/cmd/wasm/web/index.html examples/cmd/wasm/web/paper.wasm examples/cmd/wasm/web/wasm_exec.js site/playground/
 	@echo "Serving site at http://localhost:8080/  (playground: http://localhost:8080/playground/)"
 	cd site && python3 -m http.server 8080
 
 .PHONY: examples
 examples:
-	go run docs/assets/examples/addpage/main.go
-	go run docs/assets/examples/autorow/main.go
-	go run docs/assets/examples/background/main.go
-	go run docs/assets/examples/barcodegrid/main.go
-	go run docs/assets/examples/billing/main.go
-	go run docs/assets/examples/bookmark/main.go
+	go run ./docs/assets/examples/addpage/cmd
+	go run ./docs/assets/examples/autorow/cmd
+	go run ./docs/assets/examples/background/cmd
+	go run ./docs/assets/examples/barcodegrid/cmd
+	go run ./docs/assets/examples/billing/cmd
+	go run ./docs/assets/examples/bookmark/cmd
 	cd examples && go run ./cmd/paper-showcase ../docs/assets/pdf/showcase.pdf
-	go run docs/assets/examples/cellstyle/main.go
-	go run docs/assets/examples/checkbox/main.go
-	go run docs/assets/examples/compression/main.go
-	go run docs/assets/examples/customdimensions/main.go
-	go run docs/assets/examples/customfont/main.go
-	go run docs/assets/examples/custompage/main.go
-	go run docs/assets/examples/datamatrixgrid/main.go
-	go run docs/assets/examples/disablepagebreak/main.go
-	go run docs/assets/examples/footer/main.go
-	go run docs/assets/examples/header/main.go
-	go run docs/assets/examples/imagegrid/main.go
-	go run docs/assets/examples/line/main.go
-	go run docs/assets/examples/list/main.go
-	go run docs/assets/examples/lowmemory/main.go
-	go run docs/assets/examples/margins/main.go
-	go run docs/assets/examples/maxgridsum/main.go
-	go run docs/assets/examples/mergepdf/main.go
-	go run docs/assets/examples/metadatas/main.go
-	go run docs/assets/examples/orientation/main.go
-	go run docs/assets/examples/pagenumber/main.go
-	go run docs/assets/examples/parallelism/main.go
-	go run docs/assets/examples/protection/main.go
-	go run docs/assets/examples/qrgrid/main.go
-	go run docs/assets/examples/signaturegrid/main.go
-	go run docs/assets/examples/simplest/main.go
-	go run docs/assets/examples/textgrid/main.go
-	go run docs/assets/examples/watermark/main.go
+	go run ./docs/assets/examples/cellstyle/cmd
+	go run ./docs/assets/examples/checkbox/cmd
+	go run ./docs/assets/examples/compression/cmd
+	go run ./docs/assets/examples/customdimensions/cmd
+	go run ./docs/assets/examples/customfont/cmd
+	go run ./docs/assets/examples/custompage/cmd
+	go run ./docs/assets/examples/datamatrixgrid/cmd
+	go run ./docs/assets/examples/disablepagebreak/cmd
+	go run ./docs/assets/examples/footer/cmd
+	go run ./docs/assets/examples/header/cmd
+	go run ./docs/assets/examples/imagegrid/cmd
+	go run ./docs/assets/examples/line/cmd
+	go run ./docs/assets/examples/list/cmd
+	go run ./docs/assets/examples/lowmemory/cmd
+	go run ./docs/assets/examples/margins/cmd
+	go run ./docs/assets/examples/maxgridsum/cmd
+	go run ./docs/assets/examples/mergepdf/cmd
+	go run ./docs/assets/examples/metadatas/cmd
+	go run ./docs/assets/examples/orientation/cmd
+	go run ./docs/assets/examples/pagenumber/cmd
+	go run ./docs/assets/examples/parallelism/cmd
+	go run ./docs/assets/examples/protection/cmd
+	go run ./docs/assets/examples/qrgrid/cmd
+	go run ./docs/assets/examples/signaturegrid/cmd
+	go run ./docs/assets/examples/simplest/cmd
+	go run ./docs/assets/examples/textgrid/cmd
+	go run ./docs/assets/examples/watermark/cmd
 	go test docs/assets/examples/unittests/main_test.go

docs/README.md

@@ -42,7 +42,7 @@ Use the row/column API when you need to mix HTML with manual components, headers
 ## Code Example
 This is part of the [simplest example](examples/simplest?id=simplest).
 
-[filename](assets/examples/simplest/main.go ':include :type=code')
+[filename](assets/examples/simplest/paper.go ':include :type=code')
 
 ## PDF Example
 This is part of the [showcase example](examples/showcase?id=showcase).

docs/assets/examples/addpage/cmd/main.go

@@ -0,0 +1,29 @@
+// Command addpage writes the addpage example's PDF into docs/assets/pdf.
+// Run it from the repository root: go run ./docs/assets/examples/addpage/cmd
+package main
+
+import (
+	"context"
+	"log"
+
+	"github.com/avdoseferovic/paper/docs/assets/examples/addpage"
+)
+
+func main() {
+	m := addpage.GetPaper()
+
+	document, err := m.Generate(context.Background())
+	if err != nil {
+		log.Fatal(err.Error())
+	}
+
+	err = document.Save("docs/assets/pdf/addpage.pdf")
+	if err != nil {
+		log.Fatal(err.Error())
+	}
+
+	err = document.GetReport().Save("docs/assets/text/addpage.txt")
+	if err != nil {
+		log.Fatal(err.Error())
+	}
+}

docs/assets/examples/addpage/main.go → docs/assets/examples/addpage/paper.go

@@ -1,10 +1,7 @@
-// Package main demonstrates adding pages explicitly, so content starts on a fresh page.
-package main
+// Package addpage demonstrates adding pages explicitly, so content starts on a fresh page.
+package addpage
 
 import (
-	"context"
-	"log"
-
 	"github.com/avdoseferovic/paper"
 	"github.com/avdoseferovic/paper/pkg/components/page"
 	"github.com/avdoseferovic/paper/pkg/components/text"
@@ -13,25 +10,7 @@ import (
 	"github.com/avdoseferovic/paper/pkg/decorator"
 )
 
-func main() {
-	m := GetPaper()
-
-	document, err := m.Generate(context.Background())
-	if err != nil {
-		log.Fatal(err.Error())
-	}
-
-	err = document.Save("docs/assets/pdf/addpage.pdf")
-	if err != nil {
-		log.Fatal(err.Error())
-	}
-
-	err = document.GetReport().Save("docs/assets/text/addpage.txt")
-	if err != nil {
-		log.Fatal(err.Error())
-	}
-}
-
+// GetPaper builds the addpage example document.
 func GetPaper() core.Paper {
 	cfg := config.NewBuilder().
 		WithPageNumber().

docs/assets/examples/addpage/main_test.go → docs/assets/examples/addpage/paper_test.go

@@ -1,4 +1,4 @@
-package main
+package addpage
 
 import (
 	"testing"

docs/assets/examples/autorow/cmd/main.go

@@ -0,0 +1,28 @@
+// Command autorow writes the autorow example's PDF into docs/assets/pdf.
+// Run it from the repository root: go run ./docs/assets/examples/autorow/cmd
+package main
+
+import (
+	"context"
+	"log"
+
+	"github.com/avdoseferovic/paper/docs/assets/examples/autorow"
+)
+
+func main() {
+	m := autorow.GetPaper()
+	document, err := m.Generate(context.Background())
+	if err != nil {
+		log.Fatal(err.Error())
+	}
+
+	err = document.Save("docs/assets/pdf/autorow.pdf")
+	if err != nil {
+		log.Fatal(err.Error())
+	}
+
+	err = document.GetReport().Save("docs/assets/text/autorow.txt")
+	if err != nil {
+		log.Fatal(err.Error())
+	}
+}

docs/assets/examples/autorow/main.go → docs/assets/examples/autorow/paper.go

@@ -1,10 +1,7 @@
-// Package main demonstrates rows that take their height from the content inside them.
-package main
+// Package autorow demonstrates rows that take their height from the content inside them.
+package autorow
 
 import (
-	"context"
-	"log"
-
 	"github.com/avdoseferovic/paper/pkg/components/code"
 	"github.com/avdoseferovic/paper/pkg/components/image"
 	"github.com/avdoseferovic/paper/pkg/components/text"
@@ -18,24 +15,7 @@ import (
 	"github.com/avdoseferovic/paper/pkg/config"
 )
 
-func main() {
-	m := GetPaper()
-	document, err := m.Generate(context.Background())
-	if err != nil {
-		log.Fatal(err.Error())
-	}
-
-	err = document.Save("docs/assets/pdf/autorow.pdf")
-	if err != nil {
-		log.Fatal(err.Error())
-	}
-
-	err = document.GetReport().Save("docs/assets/text/autorow.txt")
-	if err != nil {
-		log.Fatal(err.Error())
-	}
-}
-
+// GetPaper builds the autorow example document.
 func GetPaper() core.Paper {
 	cfg := config.NewBuilder().
 		WithDebug(true).

docs/assets/examples/autorow/main_test.go → docs/assets/examples/autorow/paper_test.go

@@ -1,4 +1,4 @@
-package main
+package autorow
 
 import (
 	"testing"

docs/assets/examples/background/cmd/main.go

@@ -0,0 +1,29 @@
+// Command background writes the background example's PDF into docs/assets/pdf.
+// Run it from the repository root: go run ./docs/assets/examples/background/cmd
+package main
+
+import (
+	"context"
+	"log"
+
+	"github.com/avdoseferovic/paper/docs/assets/examples/background"
+)
+
+func main() {
+	backgroundImage := "docs/assets/images/certificate.png"
+	m := background.GetPaper(backgroundImage)
+	document, err := m.Generate(context.Background())
+	if err != nil {
+		log.Fatal(err.Error())
+	}
+
+	err = document.Save("docs/assets/pdf/background.pdf")
+	if err != nil {
+		log.Fatal(err.Error())
+	}
+
+	err = document.GetReport().Save("docs/assets/text/background.txt")
+	if err != nil {
+		log.Fatal(err.Error())
+	}
+}