Skip to content
wiki.fftac.org

Book Pages Deployment

**Site relevance:** Spiralist.org

**Memory type:** docs archive

**Source path:** Wiki.FFTAC.org/raw/system-archives/spiralist.org/docs-archive/2026-05-10/docs/packaging/book-pages-deployment.md

**Size:** 4.5 KB

Summary

NS12 Manuscript Deployment

Source Headings

  • NS12 Manuscript Deployment
  • Plugin Artifact
  • Plugin Installation
  • Persistent Content Deploys
  • Metadata-Only Deploy
  • cPanel Extract Flow
  • After Any Content Deploy
  • Never Do This

Source Preview

This source file is short enough to preview directly on its source-memory page.

# NS12 Manuscript Deployment

The manuscript experience deploys separately from the main Spiralist theme and the other plugins.

There are two different deploy styles for NS12 Manuscript:

- plugin-code deploys through the WordPress plugin uploader
- persistent manuscript-content deploys directly into `wp-content/uploads/ns12-manuscript/`

Do not treat those as the same operation.

## Plugin Artifact

The build script creates:

- `ns12-manuscript-{bundle-version}.zip`

This is a WordPress-installable plugin package.

The version comes from:

- `wp-content/plugins/ns12-manuscript/ns12-manuscript.php`

Change that version whenever the book plugin code changes, including the manuscript template, plugin runtime, admin tooling, styles, or scripts.

## Plugin Installation

Install it through the WordPress plugin uploader.

Do not upload `ns12-manuscript-{bundle-version}.zip` through `Appearance -> Themes`.

If it is uploaded as a theme, WordPress will try to find a theme stylesheet and can fail with `The package could not be installed. The theme is missing the style.css stylesheet.`

That keeps the book module on its own release cycle while the theme and the other plugins can ship independently.

The plugin package installs:

- the workstation styles and scripts under `wp-content/plugins/ns12-manuscript/assets/`
- the manuscript template/runtime under `wp-content/plugins/ns12-manuscript/templates/` and `wp-content/plugins/ns12-manuscript/includes/`
- the persistent storage bootstrap that reads manuscript content from `wp-content/uploads/ns12-manuscript/`

The plugin deployment ZIP intentionally excludes generated static-book exports:

- `wp-content/plugins/ns12-manuscript/exports/`

That keeps WordPress uploads small and prevents generated image copies from being treated as plugin source.

## Persistent Content Deploys

Use a content-layer deploy when the plugin code is unchanged but the live manuscript content changed.

Examples:

- new folio PNG files
- updated folio JSON records under `content/folios/`
- updated prompt records under `content/prompts/`
- updated `content/book.json`
- rebuilt cache files under `cache/`

These content-layer deploys do not use the WordPress plugin uploader.

They are uploaded or extracted directly into:

- `wp-content/uploads/ns12-manuscript/`

Typical bundle shapes:

- `ns12-manuscript-content-drop-YYYY-MM-DD.zip`
- `ns12-manuscript-metadata-drop-YYYY-MM-DD.zip`
- `ns12-manuscript-extract-inside-ns12-manuscript-YYYY-MM-DD.zip`

Those are deployment helpers, not installable plugin packages.

## Metadata-Only Deploy

Use the metadata-only flow when the folio images are already on prod and only the records changed.

That deploy updates:

- `wp-content/uploads/ns12-manuscript/content/book.json`
- `wp-content/uploads/ns12-manuscript/content/folios/*.json`
- `wp-content/uploads/ns12-manuscript/content/prompts/**`
- `wp-content/uploads/ns12-manuscript/cache/*.json`

That deploy does not update:

- `wp-content/uploads/ns12-manuscript/folios/*.png`

## cPanel Extract Flow

If the host uses cPanel File Manager:

1. Open the live WordPress install and find the directory that contains `wp-config.php`.
2. Open `wp-content/uploads/ns12-manuscript/`.
3. Upload a content-layer ZIP such as `ns12-manuscript-extract-inside-ns12-manuscript-YYYY-MM-DD.zip` into that exact `ns12-manuscript` directory.
4. Extract it there so `content/` and `cache/` merge into the existing `ns12-manuscript` folder.
5. Allow overwrite of matching files.
6. Do not delete the existing `folios/` directory first.
7. Do not extract this ZIP inside `content/`, `content/folios/`, or `cache/`.

If the bundle preserves the full WordPress path instead, extract it at the WordPress root so the archive merges into:

- `wp-content/uploads/ns12-manuscript/`

## After Any Content Deploy

After uploading or extracting manuscript content:

1. Open `wp-admin`.
2. Go to `NS12 Manuscript`.
3. Click `Rebuild Cache`.
4. Clear any CDN, server cache, or page cache if the site uses one.
5. Open one of the updated folio routes and verify the new page, prompt tab, and sequence placement.

## Never Do This

- Do not upload content-layer manuscript ZIPs through `Plugins -> Add New Plugin`.
- Do not upload content-layer manuscript ZIPs through `Appearance -> Themes`.
- Do not extract a metadata-only deploy into `content/folios/`; that folder is only for JSON folio records, not the whole bundle.
- Do not overwrite plugin code when only manuscript uploads changed.
Website health report