explainer-reading-site-deploy
Publish an already-built <WORK_DIR>/site/ to the shared Access-protected Cloudflare Pages library. Use when a local site exists and the user wants it online; use explainer-reading-site-initialize if hosting is not set up.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- explainer-reading-site-deploy
- description
- Publish an already-built <WORK_DIR>/site/ to the shared Access-protected Cloudflare Pages library. Use when a local site exists and the user wants it online; use explainer-reading-site-initialize if hosting is not set up.
- user-invocable
- true
03 SKILL.md 正文
Deploy Site — add a book to the hosted library
Publish a pre-built reading site (<WORK_DIR>/site/, from the matching PDF,
EPUB, or paper site consumer) by adding it as a subpath to the shared library
created by [[explainer-reading-site-initialize]], then deploying the whole library
to its one Cloudflare Pages project. The book lands at
https://<project>.pages.dev/<slug>/; earlier books stay put; the one Cloudflare
Access policy already covers it.
Kept separate from [[book-explainer-generate-site]] and the paper consumer (which
only build site/) so generated sites can be reviewed before they go online and
all hosting knowledge lives here.
The library manager (library.py) is owned by the explainer-reading-site-library-base skill; this skill runs it and drives wrangler. If explainer-reading-site-library-base is not installed, stop and say so rather than guessing a path.
When this applies
The inputs are a built <WORK_DIR>/site/ and an already-initialized library. If
site/ does not exist, run the source format's site consumer first. If the library
is not set up yet (first ever deploy), run [[explainer-reading-site-initialize]]
first — this skill only adds to an existing library.
Prerequisites
- The book site exists:
<WORK_DIR>/site/index.htmlis present. - The library is initialized:
python3 explainer-reading-site-library-base/scripts/library.py status --namespace pdf-explainer. If it prints "not initialized", stop and run [[explainer-reading-site-initialize]] first. wrangleris an essential prerequisite — this skill cannot publish without it. Verify it is authenticated (wrangler whoami); if missing or unauthenticated, stop and have the user set it up before re-running. Do not attempt a non-wrangler deploy path.
Procedure
Run both library.py and wrangler without the command sandbox (dangerouslyDisableSandbox: true). Two different reasons: wrangler needs the network, and library.py writes into the XDG library (~/.local/share/pdf-explainer/) — outside the workspace, which the sandbox denies with a PermissionError on shutil.rmtree/copytree. "Local-only" is not the same as "sandbox-safe": what decides it is where a command writes, not whether it touches the network.
library.py renders a document-type-neutral index (the deploy root is shared across studios), and the XDG library namespace is caller-chosen via --namespace (it must come after the subcommand, e.g. library.py add --namespace pdf-explainer …). These pdf-explainer skills always pass --namespace pdf-explainer, so the library stays at ${XDG_DATA_HOME:-$HOME/.local/share}/pdf-explainer/ exactly as before — no migration.
- Decide the book's slug and card text.
<slug>: the URL subpath, lowercasea-z0-9-, derived from the work dir name. For a Japanese name, propose a romanized slug and confirm it. Reusing an existing slug replaces that already-published book in place — solibrary.py addrefuses an existing slug unless--force. Checklibrary.py statusfirst; if the slug is already listed, confirm with the user that they mean to replace the published book before re-running with--force.<title>: the book's display title (fromreports/overview.md's heading).<desc>: one line for the library index card — compose a short blurb from the overview's opening (not a copied sentence).
- Add the book to the library (copies
site/intopublic/<slug>/, records it, and rebuilds the library index):
Appendpython3 explainer-reading-site-library-base/scripts/library.py \ add --namespace pdf-explainer --slug <slug> --title "<title>" --desc "<desc>" --from "<WORK_DIR>/site"--forceonly when deliberately replacing an existing slug, after the user confirmed the replace in step 1; without it,addstops rather than silently overwriting a published book. - Deploy the whole library to the recorded project:
PROJECT=$(python3 explainer-reading-site-library-base/scripts/library.py project --namespace pdf-explainer) PUBLIC=$(python3 explainer-reading-site-library-base/scripts/library.py public --namespace pdf-explainer) wrangler pages deploy "$PUBLIC" --project-name="$PROJECT" - Verify and report.
curl -sI https://<project>.pages.dev/<slug>/should return a 302 to the Access login (protected) — or 200 only if the user deliberately left Access off. Report the book URLhttps://<project>.pages.dev/<slug>/and the index URL.
Gotchas
wranglerneeds the network — run it without the command sandbox (dangerouslyDisableSandbox: true). Under the sandbox it fails with TLS/connection errors that look like auth problems.library.pyalso needs the sandbox off, for a different reason. It never touches the network, but it writes to~/.local/share/pdf-explainer/— outside the workspace the sandbox permits — so under the sandboxadddies withPermissionErrorwhile copyingsite/intopublic/<slug>/. Do not read that as a broken script or a bad path; run it unsandboxed.- Deploy always targets the whole
public/, never one book.wrangler pages deployreplaces the project's entire content with the given directory, so deploying a single book'ssite/would wipe every other book. Always deploy the library root fromlibrary.py public.library.py addis what puts the book into that root first. - Access is already handled by [[explainer-reading-site-initialize]]. It covers the whole project, so a new subpath is protected automatically — no per-book Access step. If
curlunexpectedly returns 200, Access was never enabled; point the user to initialize-site step 4. - Never report the protection state from a local file. Access lives in the Cloudflare dashboard;
library.jsondoes not record it (by design — see [[explainer-reading-site-library-base]]). The only way to know whether the site is protected is to ask the deployed URL, which is what step 4'scurl -sIdoes. Telling the user "the site is public" on the strength of a local record is how you hand them a confident falsehood. - Regenerate, then redeploy. The matching PDF, EPUB, or paper consumer rebuilds
<WORK_DIR>/site/from source; this skill copies whatever is there now. Re-run that consumer before redeploying a changed book (same slug replaces it in place — gated behind a user-confirmed--force). - Pages limits: 25 MiB per file, 20,000 files across the whole library. [[explainer-audio-narrate]]'s 64 kbps m4a (~5 MB/10 min) is fine; a hand-added WAV can exceed 25 MiB and the deploy will reject it — re-encode it.
Success criteria
- [ ]
library.py addreported the book atpublic/<slug>/, andlibrary.py statuslists it once (replacing an existing slug went through a user-confirmed--force; no duplicate slug). - [ ]
wrangler pages deploytargeted the library root (library.py public), not the book's ownsite/, so previously deployed books are still present. - [ ]
curl -sIagainst the book URL returned a 302 Access redirect (or 200 only if the user chose to keep the site public), and the state was reported. - [ ] The book URL
https://<project>.pages.dev/<slug>/was reported to the user.
04 同仓库更多 Skills
invalid-skill-frontmatter
暂无简介
pdf-explainer-summarize
Digest a book, manual, or other long non-paper PDF into a source-anchored Markdown overview. Use when the requested deliverable is only a report, digest, or summary. Use paper-explainer-summarize for academic papers, direct reading for short PDFs, and book-explainer for coordinated reports, audio, site, rebuild, or resume.
pdf-explainer-pdf-stitch
Internal Phase 2 worker invoked once by pdf-explainer-summarize after chunk extraction. Reconciles sections across chunk boundaries, deduplicates the material, and writes the canonical structural spine and outline.
pdf-explainer-pdf-extract
Internal Phase 1 worker invoked by pdf-explainer-summarize once per page chunk. Reads the chunk visually or from a faithful text layer and writes structured source material with a verbatim heading stream, not a finished report.
pdf-explainer-pdf-detail
Internal per-chapter worker invoked by book-explainer for PDF input. Re-read one resolved chapter span visually or from a faithful text layer and write a standalone detail report with [pNN] source anchors.
pdf-explainer-generate-site
Compatibility entry point for requesting a local PDF reading site from an existing work directory. Route through book-explainer so Artifact reconciliation and Planning still occur.