Publishing

When your book is built, Gutterpress can send it to the places readers buy it — itch.io, DriveThruRPG, Amazon KDP, a website on Azure, your Shopify store, or a folder in your own Google Drive — without leaving the app.

Two Kinds of Publishing

Direct upload — for platforms with an upload API (itch.io, Azure Static Web Apps, Shopify, Google Drive), Gutterpress pushes the file for you and gives you the link.

Guided publishing — DriveThruRPG and Amazon KDP don't offer upload APIs, so Gutterpress does everything it can: it checks your book, prepares an upload package (your PDF plus a LISTING.md sheet with your title, authors and notes), and opens the platform's upload page with a step-by-step checklist.

Setting Up a Provider

1. Press Publish in the toolbar of the desktop app.
2. Fill in the provider's settings (for itch.io that's your project as user/game; for Shopify your store domain). These are saved in manifest.yaml — safe to commit, nothing secret.
3. For direct-upload providers, click Create an API key, copy the key from the platform, paste it and press Connect. The key is verified with the platform and stored securely on your computer — never in the project folder.

# manifest.yaml — the non-secret half lives with your project
publish:
  itch:
    target: your-user/your-book

Publishing to Google Drive

Google Drive works a little differently from the other providers, because there's no API key to create or paste.

1. Press Publish in the toolbar and click Connect Google Drive. Your browser opens to Google's own sign-in page — choose your account and click Allow. That's it: nothing to copy, nothing to type back into Gutterpress.
2. Once connected, pick a Folder from the dropdown, or choose New folder… and give it a name. Gutterpress only ever sees folders it created itself — it can't browse the rest of your Drive.
3. Choose what to publish — your built PDF, or a zipped export of the website version — using the wizard's radio buttons. (From the CLI, set publish.gdrive.format to pdf or html in manifest.yaml instead.)
4. Press Publish. The file you chose lands in that folder.

Publishing again updates the same file instead of creating a duplicate, so a link you already emailed to an editor or sent to a printer keeps pointing at the newest version — you never have to resend it.

Once the folder exists, you can move it anywhere you like in your own Drive — into an existing project folder, a shared folder, wherever makes sense to you — and publishing keeps working, because Gutterpress remembers the folder, not its location.

Gutterpress never changes who can see your files. A freshly published file is only visible to you, exactly like anything else you add to Drive yourself. When you're ready to share it, open the file (or its folder) in Drive and use Drive's own Share button.

# manifest.yaml — the non-secret half lives with your project
publish:
  gdrive:
    folder: My Books
    format: pdf   # or html, for the zipped website export

gutterpress publish --provider gdrive --connect     # opens your browser once
gutterpress publish --provider gdrive               # uploads (or updates) the PDF

Publishing

Build first (Export PDF, or gutterpress build), then press Publish on the provider's card. Check readiness runs the same checks without publishing anything.

From the terminal (or CI):

gutterpress build
gutterpress publish --provider itch

Tip: DriveThruRPG has strict print requirements. Run gutterpress validate --pdf dist/my-book/my-book-pdf.pdf --target dtrpg before uploading — it checks bleed, ink density and more. Without --pdf, there's no built PDF to inspect, so those checks silently pass without measuring anything.

Books using the dtrpg preset are already set up for DriveThruRPG's print rules:

• The last page is left blank. DriveThruRPG prints its own information on a book's final page, so Gutterpress pads the book to a multiple of 4 pages and makes sure the last one is empty. The page count the build reports is the number to enter in DriveThruRPG's cover Template Generator.
• Black text prints in black ink only. In a --format pdfx build, black and near-black text goes on the black plate alone, as DriveThruRPG requires for small text. Coloured text is printed as designed.

Sharing a Folder Between Formats

gutterpress build --out <dir> writes into a plain folder instead of the project's own dist/, which is how you build a static site and its downloadable PDF into one place:

gutterpress build --format html --out ./_site
gutterpress build --format pdf --out ./_site

Each command only delivers what its own format produces, so the second command never disturbs the first's output: --format html writes book.html (with the viewer), index.html, and the referenced assets; --format pdf/pdfx adds only its own PDF. ./_site ends up with both — the paginating book.html a browser opens, and a PDF a reader can download — with neither build overwriting the other's files.

Publishing From CI

The publish command is fully headless. Set the provider's environment variable instead of connecting interactively:

gutterpress publish --provider itch --json   # machine-readable result, exit 1 on failure

Where Keys Are Stored

API keys never live in your project folder, so they can't end up in Git or a shared ZIP. The desktop app keeps them in your operating system's secure storage; the CLI keeps them in a private file in your user configuration folder. Disconnecting a provider deletes the stored key.

Google Drive is no different under the hood — there's no key to paste, but the connection is stored just as securely, and Disconnect removes it just as completely.