@gentbajko/slopify 3.0.0 → 3.0.2

package/dist/tutorials/Costs-and-Run-Cost.md

@@ -0,0 +1,136 @@
+# Costs and Run Cost
+
+Slopify shows what a run is likely to cost before you start it, what it actually cost once it ran, and, for runs on a command-line plan, what the same work would have cost with API keys and how much of your plan it used. All figures are in US dollars, from the providers' published prices.
+
+**Where to find it:** Play → **Estimated cost** in the right rail; a project → **Run cost** tab; Home → **This week**; Settings → **Usage**.
+
+## Where costs come from
+
+- Every successful provider call is recorded against its project with what it used: tokens in and out (and how many were cached) for text, characters for narration, images per model, seconds of animated video, and how long the call took.
+- Each call is priced when it finishes, from the model catalogue (see [Models](Models)). The rates are stored with the call, so a later price change never rewrites a finished run.
+- A model the catalogue has no price for, or a call whose provider reported no usage, is counted as unknown, never as free. Per-minute voices are left unpriced rather than guessed.
+- Failed calls are not charged here. Taxes and credits included in your provider plan are not counted.
+
+Your provider bills you directly; Slopify never handles payment. The figures are for planning and checking, not a bill.
+
+## Command-line runs: $0 on your plan
+
+Claude Code, Codex and Gemini bill your subscription, not per call. So their calls show as **$0 on your plan**. Beside that, Slopify shows what the same tokens would have cost through the API ("via API"), priced as the same model from the catalogue: Claude models as Anthropic's, Codex models as OpenAI's, Gemini models as Google's.
+
+There is no API figure for a model the catalogue does not list, for a CLI's default model, or for Codex images. The screens say so ("no API price is listed", "API price unknown").
+
+See [AI-CLIs](AI-CLIs#plan-limits-and-waiting-them-out) for the plan limits themselves.
+
+## Before you start: Estimated cost on Play
+
+The right rail on Play shows **Estimated cost** once the setup is complete. Until then it says "The estimate appears once the setup is complete."
+
+| Part | What it shows |
+|---|---|
+| **Estimated total** | The likely range for this run (or all the runs on the page), for example "$0.42 – $0.61". |
+| **Known subtotal** | Shown instead of the total when some stage has no price; a line below says how many stage charges have unavailable pricing. |
+| **Cost by stage** | Fold-out list: each stage's range and what it assumes. A CLI stage reads "$0 on your plan · ~$X via API". |
+| CLI steps line | "CLI steps: $0 on your plan · ~$X via API" for everything on a plan. |
+| Catalogue date | "Catalogue verified <date>". With several videos, rows show combined costs. |
+
+**Expected article words per video** drives the estimate for generated articles (and how many images **More images for long videos** adds). About 150 words is one minute. Default: 1500. Once the article is written, its real length is used.
+
+The estimate is what the providers are likely to charge, from their published prices. Actual usage can differ, and the estimate does not cap spending.
+
+## While a run is going: Cost so far
+
+On a running project, the side panel shows **Cost so far**:
+
+- **spent**: what has been paid to providers so far ("known, spent" when some calls have no price).
+- **same work via API**: the API equivalent of the CLI calls.
+- One meter per plan window a CLI reported, such as "Codex: 14% of your weekly limit". The meter turns amber once the plan is at 80% or more.
+
+When a CLI's plan is used up, the run waits instead of failing: the status reads **Waiting for limits**, for example "Waiting for Codex limits (resets at 14:00)". The run carries on by itself when the plan resets.
+
+## After a run: the run cost line
+
+When a run has ended, one line at the top of its project page, under the title, sums it up: for example `This run cost $0.42 · ~$3.10 via API · 12 min end to end`. A failed or cancelled run says **Spent so far**, and calls without a known price add "plus unpriced calls". **See cost by stage** opens the full breakdown below. The line doesn't show while the run is going, or when it spent nothing.
+
+## After a run: the Run cost tab
+
+1. Open the project from **Projects** or **Home**.
+2. Choose **Cost** in the section rail (or **See cost by stage** on the run cost line).
+
+If nothing has been spent yet, it says "Nothing has been spent yet. The cost of each provider call appears here as the run makes it."
+
+### Summary
+
+| Figure | What it is |
+|---|---|
+| **paid to providers** | The total cost of this project's calls. Reads "known cost, paid to providers" when some calls have no price, with a line "Plus N calls the model catalogue has no price for." |
+| **same work via API** | The API equivalent of the calls that ran on a CLI plan. |
+| Plan meters | One per plan window a CLI reported, for example "3% of weekly Codex limit". Hover or read the line below for the level it is at now. |
+| **end to end** | How long the whole run took. |
+
+Lines under the summary:
+
+- "CLI calls: $0 on your plan · ~$1.20 via API", when any call ran on a plan.
+- "This run used ~3% of your weekly Codex limit (now at 41%, resets Mon 09:00)." Codex reports whole percents, so a short run can read "under 1%".
+- When a CLI reported nothing (Gemini, or a Docker host helper older than the app), it says the share is not known.
+
+### By stage
+
+**Cost by stage**: what each stage has cost so far, from every provider call it made, retries and remakes included.
+
+| Column | What it shows |
+|---|---|
+| **Stage** | Research, Article, Audio, Images, Thumbnail, Video, Document. |
+| **Cost** | What you paid. "$0 on plan" for CLI stages; "Unknown" when no call in it has a price; "$0.40 + unknown" when some do not. |
+| **Via API** | The API equivalent for CLI calls, or "No API price". |
+| **Usage** | Tokens in and out (and cached), characters, images, seconds of video. |
+| **Time** | How long the stage ran. |
+
+### By model
+
+**Cost by model**: the same spending split by provider and model, with **Cost**, **Via API**, **Usage** and **Calls**. A CLI model shows the API model it was priced as, in brackets after "as". The CLI's own default model shows as "default model".
+
+The last lines give the total usage and stage time, and "Priced from the model catalogue of <date> when each call finished."
+
+## Across all projects: Home → This week
+
+Home's **This week** section, since Monday:
+
+- **videos made**.
+- **spent**, followed by "· ~$X via API" and "· N calls without a price" when they apply.
+- One bar per CLI plan: how much of its weekly limit is used, from the tool's last reading. The bar turns amber at 80%.
+
+It includes calls that belong to no project: a schedule's topic suggestions, a channel's episode summaries and a cast member's picture. These never appear on a project's Run cost tab. The channel picker at the top of Home narrows the numbers to one channel. See [Home-and-Projects](Home-and-Projects).
+
+## Your usage totals: Settings → Usage
+
+Settings → **Usage** shows this install's own counters, worked out on this computer from its event log:
+
+| Counter | What it counts |
+|---|---|
+| **Videos made** | Videos finished. |
+| **Hours of audio** | Narration made, in hours. |
+| **Images made** | Images drawn. |
+| **Tokens used** | Text tokens, in and out. |
+| **Projects** | Projects made. |
+
+Below them, **Tokens by stage** lists **Stage**, **Provider · model**, **Tokens in** and **Tokens out**. A fresh install says "Numbers appear after your first run." The last line shows the install's machine ID and Slopify version.
+
+The same counters, anonymised, feed the public totals on slopify.stream. They never include your keys, prompts, keywords, titles, text or files.
+
+To jump there, press `Ctrl+K` and run **Open usage and costs**. The old `/usage` address also opens this section.
+
+## Tips
+
+- Set **Expected article words per video** close to what your prompt really writes; it is the biggest lever on the estimate for a generated article.
+- Compare the **Via API** column with your plan's price to see whether a subscription or a key is cheaper for how you work.
+- If a total says "known cost", check which model has no price in [Models](Models) and add one to your catalogue file if you know it.
+
+## Related pages
+
+- [Models](Models)
+- [AI-CLIs](AI-CLIs)
+- [Providers-and-Keys](Providers-and-Keys)
+- [Play-Outputs](Play-Outputs)
+- [Project-Page](Project-Page)
+- [Home-and-Projects](Home-and-Projects)
+- [Settings-Reference](Settings-Reference)

package/dist/tutorials/Docker.md

@@ -0,0 +1,171 @@
+# Docker
+
+On Linux you can have Slopify run in Docker in the background, restarting whenever Docker does. One command installs it, one command updates it, and your project files stay in a normal folder on your computer.
+
+**Where to find it:** a terminal, `npx @gentbajko/slopify@latest --docker`. Inside the app, Settings → **Backup & storage** → **Your files** and Settings → **General** show the Docker-specific parts.
+
+## What you need
+
+- Linux with Docker Engine and the Docker Compose plugin.
+- Node 26 or newer on the host, to run the installer.
+- Your normal user account, with access to Docker. Don't run the installer with `sudo`. If Docker says permission denied, add yourself to the `docker` group (`sudo usermod -aG docker $USER`), then log out and back in.
+
+Refused setups: Docker Desktop, a remote Docker daemon, and rootful Docker with `userns-remap`. Rootless Docker works; the container then runs as user `0:0`, which is you on the host.
+
+On Windows, macOS or anything else, run Slopify without Docker ([Install](Install)), or run the compose file yourself ([below](#run-the-compose-file-yourself)).
+
+## Install Slopify in Docker
+
+1. Open a terminal as your normal user.
+2. Run `npx @gentbajko/slopify@latest --docker`.
+3. If Claude Code, Codex or Gemini CLI is installed on this computer, the installer asks once whether Slopify may use them (see [The host CLI bridge](#the-host-cli-bridge)). Answer `y` to allow it, or anything else to stop without changing anything. To use API keys only, run the command with `--host-cli=off` instead.
+4. It asks `Start Slopify when you log in? (Y/n)` once. See [Start at Login](Start-at-Login#docker).
+5. When it finishes it prints:
+   - `Slopify 3.0.0 is running at http://127.0.0.1:6969`
+   - `Project files on this machine:` your Projects folder
+   - `Backups on this machine:` your Backups folder, on a new install
+   - which AI tools it will use (the host CLIs, or API keys only)
+6. Open `http://127.0.0.1:6969` in your browser and continue with [First Launch and Welcome](First-Launch-and-Welcome).
+
+Running the same command again with nothing changed does nothing, apart from starting the container if it was stopped.
+
+## What gets installed
+
+| Part | What it is |
+| --- | --- |
+| Image | `ghcr.io/gentbajko/slopify:<version>`, pinned to the version of the installer you ran. It runs as a non-root user and already contains ffmpeg, the caption model and eSpeak NG, so the [System voice](Providers-and-Keys#the-system-voice) can narrate with no key. A healthcheck asks the app whether it is up. |
+| Compose file | Copied to `~/.local/share/slopify/docker/slopify/` with a private `.env` beside it. One service, `slopify`, with `restart: unless-stopped`. |
+| Port | `127.0.0.1:6969` on the host, localhost only. |
+| Data volume | `slopify-data`, mounted at `/data`. It holds the database, provider keys, settings, logs and staging. It is declared external, so `docker compose down` (even with `-v`) never deletes it. |
+| Projects folder | A folder on your computer, mounted at `/data/projects`. |
+| Backups folder | A folder on your computer for scheduled backups, mounted at `/data/backups` (new installs from 3.0). |
+| Host CLI bridge | Optional. A small helper that lets the container use your AI command-line tools. |
+| `install.json` | In the same folder as the compose file. Records the version, port, project folder, user and whether the bridge is on. |
+
+## Where your files go
+
+| Install | Projects | Backups |
+| --- | --- | --- |
+| New install (3.0 and later) | `<Documents>/Slopify/Projects` | `<Documents>/Slopify/Backups` |
+| Installed before 3.0 | `~/Slopify/Projects` (kept as it was) | `~/Slopify/Projects/Backups` |
+
+`<Documents>` is what `xdg-user-dir DOCUMENTS` answers, then `XDG_DOCUMENTS_DIR` in `~/.config/user-dirs.dirs`, then `~/Documents`.
+
+Everything else (database, keys, logs) stays private in the `slopify-data` volume. See [Where Your Files Live](Where-Your-Files-Live).
+
+## Change a setting
+
+Run the install again with the setting you want. Settings you leave out are remembered from `install.json`.
+
+| Option | What it does |
+| --- | --- |
+| `--port <number>` | Serves Slopify on another host port, still on `127.0.0.1`. |
+| `--projects-dir <folder>` | Uses another folder for project files. The files are copied and checked first; the old folder is left as it was. The new folder must be empty. A `~/` at the start is understood. |
+| `--projects-dir documents` | Moves an existing install's projects to `<Documents>/Slopify/Projects`. |
+| `--host-cli=off` | Turns the host CLI bridge off; Slopify uses API keys only. `off` is the only accepted value. |
+| `--accept-host-cli` | Approves the host CLI bridge without the question, for scripts. |
+| `--autostart` / `--no-autostart` | Answers the start-at-login question without asking. |
+
+`--host` and `--data-dir` can't be combined with `--docker`.
+
+For several Docker installs on one machine, give each its own `SLOPIFY_DOCKER_NAME` and `SLOPIFY_DOCKER_VOLUME` (letters, digits, dots, dashes and underscores). A second install's Documents folder is `<Documents>/Slopify/<name>/Projects`.
+
+## Move your projects into Documents
+
+A container can't move its own mounted folder, so the installer does it from the host.
+
+1. Open Settings → **Backup & storage**. Under **Your files** you see the command to run, with **Copy command**.
+2. On the computer running Docker, run `npx @gentbajko/slopify@latest update --docker --projects-dir documents`. For another folder, use `--projects-dir <folder>`.
+3. The installer waits for running work to finish, copies the folder, checks the copy and remounts the new folder.
+4. The old folder is left as it was. Once your projects open fine, you can delete it.
+
+Backups stay where they were (`Projects/Backups` on an older install).
+
+## Update the Docker install
+
+Run `npx @gentbajko/slopify@latest update`. With a Docker install on your user account, `update` goes to it automatically (`update --docker` is the same). The **Update** button inside the Docker app shows this command, because a container can't replace itself.
+
+The update is one transaction:
+
+1. It waits until nothing is generating. Pressing `Ctrl+C` while it waits changes nothing.
+2. It stops the container and copies the whole data volume into a recovery volume, `slopify-data-recovery-<id>`, checked file by file.
+3. It starts the new version and waits up to 2 minutes for it to answer as that version.
+4. On success it records the new version and removes the older recovery volume, so only the newest one is kept.
+5. If the new version doesn't answer, it removes it, copies your data back from the recovery volume and starts the previous version with its previous settings.
+
+If an install or update is cut off (`Ctrl+C`, a reboot), the next run first finishes putting things back, then continues.
+
+The recovery volume covers the database and settings, not your Projects folder. When you make your own backups, keep both the `slopify-data` volume and your Projects folder, or use [Backups](Backups).
+
+## The host CLI bridge
+
+If Claude Code, Codex or Gemini CLI is installed on the host, Slopify in Docker can use them with the logins you already have. Nothing about your logins is copied into Docker.
+
+- With your OK, the installer sets up a small helper, at the same version as the image, and keeps it in step on every install and update.
+- The helper runs as the systemd user service `slopify-cli-bridge.service`, as you. User lingering is turned on so it runs at boot and after you log out.
+- It talks to the container through a private socket in `~/.local/share/slopify/host-cli/share/`, with a token. There is no network port. Only that `share` folder is mounted into the container, read-only.
+- Codex images, run cost and plan-limit readings work the same as without Docker.
+- The helper only opens folders inside your Projects folder when you press **Open folder**.
+- With the bridge off, Settings shows the CLIs as unavailable, and API keys still work.
+
+Check or turn it off:
+
+```sh
+systemctl --user status slopify-cli-bridge.service
+systemctl --user disable --now slopify-cli-bridge.service
+```
+
+Turning it off leaves Docker, your API providers, your data and your host logins as they are. Run the install again after installing or moving a CLI.
+
+If the installer can't ask (no interactive terminal), it stops and tells you to rerun with `--accept-host-cli` or `--host-cli=off`. Using the bridge needs systemd user services (`systemctl --user`); without them, use `--host-cli=off`.
+
+## Coming from 2.5.0 or earlier
+
+The first run of the new installer takes your existing installation over:
+
+- It reuses the `slopify-data` volume by name; it is never deleted or recreated. A container on another volume is refused, with the `SLOPIFY_DOCKER_VOLUME` value to use.
+- It keeps the project folder the old container used (`~/Slopify/Projects`, or your `--projects-dir`). A plain `docker run` container that kept projects inside the volume gets them copied, checked, to `~/Slopify/Projects`; the copy in the volume stays.
+- The old container is stopped and renamed `slopify-previous-<id>` while the new one starts. If the new one fails, the old one is put back exactly as it was. It is removed once the new one is committed.
+- If a 2.5.0 launcher update was left unfinished, nothing is changed. Run `npx @gentbajko/slopify@2.5.0 --docker` once so it finishes or undoes it, then install again.
+
+## Run the compose file yourself
+
+Without the installer (any OS with Docker Compose), with API keys only, from a folder containing Slopify's `compose.yaml`:
+
+```sh
+docker volume create slopify-data
+mkdir -p ~/Documents/Slopify/Projects
+SLOPIFY_PROJECTS_DIR=~/Documents/Slopify/Projects SLOPIFY_USER="$(id -u):$(id -g)" \
+  docker compose -f compose.yaml up -d
+```
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `SLOPIFY_PROJECTS_DIR` | none, required | The host folder for project files. |
+| `SLOPIFY_IMAGE` | `ghcr.io/gentbajko/slopify:latest` | The image to run. |
+| `SLOPIFY_PORT` | `6969` | The host port, bound to `127.0.0.1`. |
+| `SLOPIFY_USER` | `1000:1000` | The user id the container runs as, so project files belong to you. |
+| `SLOPIFY_VOLUME` | `slopify-data` | The data volume's name. It must exist (`docker volume create`). |
+| `SLOPIFY_BACKUPS_DIR` | empty | The host folder for scheduled backups. Without it, backups stay in `Projects/Backups`. |
+| `SLOPIFY_HOST_CLI_SHARE` | empty | The host CLI bridge's share folder, if you set one up. |
+| `SLOPIFY_NAME` | `slopify` | The compose project and container name. |
+
+Update by changing `SLOPIFY_IMAGE` and running `docker compose up -d` again. This way has no automatic recovery copy or rollback, and Settings → General can't tell whether Docker starts at login.
+
+Keep the `127.0.0.1` binding. Anyone who reaches Slopify's port controls the app and its provider keys.
+
+## Tips
+
+- Settings → **General** shows **Starts with Docker: yes / no / unknown**, read by the installer. Run the install command again after changing Docker's own start-up setting so it looks again.
+- Port 6969 taken by a native Slopify? Stop the native one, or give Docker another port with `--port 7070`.
+- To stop Slopify for a while without removing anything, run `docker stop slopify`; `docker start slopify` or the install command starts it again.
+
+## Related pages
+
+- [Install](Install)
+- [Where Your Files Live](Where-Your-Files-Live)
+- [Start at Login](Start-at-Login)
+- [Updating and Patch Notes](Updating-and-Patch-Notes)
+- [Uninstalling and Moving](Uninstalling-and-Moving)
+- [AI CLIs](AI-CLIs)
+- [Backups](Backups)

package/dist/tutorials/Document-Themes.md

@@ -0,0 +1,207 @@
+# Document Themes
+
+A document theme is the look of the PDF Slopify makes from the article: paper size, colours, fonts, spacing, the title page, contents, sources and closing pages, headers and page numbers. Slopify ships a built-in **Plain** theme. Copy it to make themes of your own, with a live preview as you edit.
+
+**Where to find it:** **Library → Documents**. Pick a theme on Play's **Document** row, in **Edit project**, or as a channel's default in its brand kit.
+
+## Built-in and your own themes
+
+| List | What it holds |
+|---|---|
+| **Built-in themes** | Looks that ship with Slopify and can't be changed. **Plain** is an unbranded flat page and what a new project gets. Press **Copy theme** to make an editable copy. |
+| **Your themes** | Themes you made or copied. Each has **Edit**, **Duplicate** and **Delete**. |
+
+A project keeps its own copy of the theme's settings. Editing or deleting a theme never changes a PDF already made or queued.
+
+## Make a theme
+
+1. Open **Library → Documents**.
+2. Press **New theme** (it starts from Plain), or pick a built-in theme and press **Copy theme**, or press **Duplicate** on one of your themes.
+3. Type a **Name** (up to 80 characters). This is what the Document row on Play and Edit project shows.
+4. Open the groups on the left and change what you like (every setting is listed below). The first two groups start open.
+5. Watch the **Preview** on the right. It lays out a sample article with this theme using the same renderer that makes a project's PDF, redrawn about half a second after you stop typing. It runs on your computer and costs nothing.
+6. Press **Save**. If a setting is out of range it is highlighted, and Save says "Fix the highlighted settings first."
+
+## Use a theme
+
+- **On Play:** open the **Document** row (the PDF output) and pick the theme. See [PDF documents](PDF-Documents).
+- **On a finished project:** open **Edit project** (the **Edit settings** button), pick the theme under **Document theme**, save, and remake the document.
+- **For a channel:** set **Document theme** in the channel's brand kit. Videos whose template picks no theme get it. See [Channels](Channels).
+
+## Delete a theme
+
+Press **Delete** on the theme and confirm. Projects that used it keep their own copy of its settings. A channel whose brand kit named it skips it.
+
+## Every setting
+
+Sizes are in millimetres (mm) unless marked pt (points; 1 pt is about 0.35 mm). Defaults are the Plain theme's.
+
+### Page
+
+| Setting | What it does | Default | Range |
+|---|---|---|---|
+| **Paper size** | A4 (210 × 297 mm) for most of the world, US Letter (216 × 279 mm) for the US and Canada. | A4 | |
+| **Margins** | Blank space on every edge of each page. Wider margins mean shorter lines and more pages. | 22 mm | 5 to 60 |
+| **Text starts at** | How far from the top the text begins on pages with the running header. Raise it when text crowds the header. | 32 mm | 5 to 80 |
+| **Background** | **Parchment texture** stretches an aged-paper picture over every page. **Flat colour** fills each page with the Page colour, slightly darker at the edges. | Flat colour | |
+| **Page colour** | The page colour with Flat colour. Type a hex code or use the picker. | `#fdfaf3` (warm off-white) | |
+
+### Colours
+
+| Setting | What it colours | Default |
+|---|---|---|
+| **Heading colour** | Headings, drop caps, the brand name and links | `#1f3a5f` (dark blue) |
+| **Body text colour** | Paragraphs, lists, bold and italic text. Keep it dark against the page. | `#1a1a1a` (near black) |
+| **Muted colour** | Dates, bullets, quotes and the dotted lines on the contents page | `#555555` (mid grey) |
+| **Faint colour** | The running header and page numbers | `#888888` (light grey) |
+
+### Fonts
+
+Each font has three controls: the family, its weight or italic, and **Letter spacing (mm)** from −0.5 to 2. The families are **Cinzel** (bundled; four weights, no italics) and **Times**, **Helvetica** and **Courier** (built into every PDF reader).
+
+| Setting | Where it is used | Default |
+|---|---|---|
+| **Body font** | Paragraphs and lists | Cinzel Regular, 0.01 mm |
+| **Bold text font** | Bold words in paragraphs | Cinzel Bold, 0.02 mm |
+| **Italic text font** | Italic words in paragraphs (Cinzel has no italics, so this borrows Times) | Times Italic, 0 mm |
+| **Heading font** | The article's headings and the contents, sources and closing page titles | Cinzel Bold, 0.02 mm |
+| **Chapter numbers and brand font** | The big number in a heading like "Chapter 3:" and the brand name on the title page | Cinzel Black, 0.03 mm |
+| **Tagline and link font** | The tagline and linked line on the title page, and the link and closing line on the closing page | Cinzel Medium, 0.015 mm |
+| **Drop cap font** | The large first letter after a heading | Cinzel Black, 0 mm |
+| **Header and page number font** | The running header and page numbers | Times Regular, 0 mm |
+
+### Text sizes
+
+| Setting | What it sizes | Default | Range |
+|---|---|---|---|
+| **Title size** | The article's title on the title page | 22 pt | 6 to 72 |
+| **Brand size** | The brand name on the title page (only shown with a brand name) | 31 pt | 6 to 72 |
+| **Top-level heading size** | Top-level headings and the contents, sources and closing page titles | 19 pt | 6 to 72 |
+| **Second-level heading size** | Headings inside a top-level section | 17 pt | 6 to 72 |
+| **Third-level heading size** | Third-level and deeper headings | 13 pt | 6 to 72 |
+| **Body size** | Paragraphs, lists and closing page text. Bigger text means more pages. | 10.5 pt | 6 to 24 |
+| **Date and word count size** | The date, word count and link lines under the title | 10 pt | 5 to 24 |
+| **Header and page number size** | The running header and page numbers | 9 pt | 5 to 24 |
+
+### Spacing
+
+| Setting | What it does | Default | Range |
+|---|---|---|---|
+| **Body line height** | Distance from one body line to the next | 8 mm | 3 to 20 |
+| **Heading line height** | Between the lines of a wrapping top- or second-level heading | 11 mm | 3 to 30 |
+| **Subheading line height** | Between the lines of a wrapping third-level heading | 9 mm | 3 to 30 |
+| **After a paragraph** | Extra space after each paragraph, as a share of a body line (0.5 is half a line) | 0.5 | 0 to 3 |
+| **Before a heading** | Extra space above each heading, as a share of a body line | 1 | 0 to 5 |
+| **After a list item** | Extra space after each bulleted or numbered item | 0.2 | 0 to 3 |
+| **List indent** | How far lists are pushed in from the left margin | 6 mm | 0 to 30 |
+| **Quote indent** | How far quotes are pushed in | 8 mm | 0 to 40 |
+| **Divider width** | The width of the short centred line a `---` in the article becomes | 30 mm | 0 to 150 |
+
+### Drop caps
+
+| Setting | What it does | Default | Range |
+|---|---|---|---|
+| **Drop caps** | Starts the first paragraph after each heading with a large letter spanning several lines, as in printed books. | On | |
+| **Drop cap lines tall** | How many body lines the letter spans | 3 lines | |
+| **Drop cap letter size** | The letter's size as a multiple of the lines it spans | 3 | 1 to 5 |
+| **Gap beside the drop cap** | Space between the letter and the text beside it | 4 mm | 0 to 20 |
+| **Shortest paragraph** | A paragraph shorter than this many characters starts plainly | 50 | 0 to 2000 |
+| **Room needed** | With less than this share of the page left, a paragraph starting with a drop cap moves to the next page (0.25 is a quarter) | 0.25 | 0 to 1 |
+
+### Title page
+
+| Setting | What it does | Default | Range |
+|---|---|---|---|
+| **Brand from top** | Where the brand name sits, from the top edge | 60 mm | 10 to 200 |
+| **Tagline below brand** | Distance from the brand name down to the tagline | 10 mm | 0 to 60 |
+| **Title from top** | Where the article's title sits, from the top edge | 80 mm | 10 to 250 |
+| **Title line height** | Between the lines of a wrapping title | 10 mm | 3 to 40 |
+| **Details below title** | Distance from the title to the date and word count, when there is no cover picture | 20 mm | 0 to 100 |
+| **Details line height** | Between the date, word count and link lines | 10 mm | 3 to 30 |
+| **Show the date** | Prints "Written on" and the date the PDF was made | On | |
+| **Show the word count** | Prints the article's word count | On | |
+| **Thumbnail as cover** | Puts the project's thumbnail between the title and the date, when there is one | On | |
+| **Space around cover** | Space above and below the cover picture | 6 mm | 0 to 40 |
+| **Cover height at most** | The tallest the cover may be; it keeps its shape and shrinks when needed | 110 mm | 20 to 200 |
+
+### Branding
+
+| Setting | What it does | Default |
+|---|---|---|
+| **Brand name** | Your channel or brand, printed large at the top of the title page and before the title in the running header ("Brand \| Title"). Empty shows no brand. | Empty |
+| **Tagline** | A short line under the brand name. Empty hides it. | Empty |
+| **Website** | The address the brand name and the title-page link open when clicked in the PDF. | Empty |
+| **Link text** | The words of a linked line under the word count on the title page; it opens Website. Empty hides the line. | Empty |
+
+### Contents page
+
+| Setting | What it does | Default | Range |
+|---|---|---|---|
+| **Contents page** | Adds a table of contents after the title page, each entry a link to its page | On | |
+| **Contents page title** | The heading of the contents page (up to 300 characters) | Table of Contents | |
+| **Lists headings down to** | Top level only, second level, or third level. Deeper lists can add a page. | Second level | |
+| **Contents title position** | From the top margin to the contents title | 20 mm | 0 to 100 |
+| **First entry position** | From the top margin to the first entry | 40 mm | 0 to 150 |
+| **Contents line height** | From one entry to the next | 8 mm | 3 to 30 |
+| **Indent per level** | How much further each deeper level is indented | 5 mm | 0 to 30 |
+
+### Header and footer
+
+| Setting | What it does | Default | Range |
+|---|---|---|---|
+| **Running header** | Prints "Brand \| Title" at the top of every page after the title page | On | |
+| **Header from top** | From the top edge to the header | 15 mm | 3 to 60 |
+| **Header title at most** | A longer title is cut short in the header to fit one line | 35 characters | 5 to 200 |
+| **Page numbers** | Prints a page number at the bottom of every page after the title page | On | |
+| **Page number text** | The words around the number; `{page}` becomes the number, so `Page {page}` prints "Page 4" | `Page {page}` | |
+| **Page number from the bottom** | From the bottom edge to the page number | 10 mm | 3 to 60 |
+| **Space kept above page number** | Space kept free above the number so body text stops short of it | 15 mm | 0 to 60 |
+
+### Sources page
+
+| Setting | What it does | Default | Range |
+|---|---|---|---|
+| **Sources page** | Adds a page listing the web links the article and its research used, each clickable | On | |
+| **Sources page title** | Its heading (up to 300 characters) | Sources Consulted | |
+| **Sources title position** | From the top margin to the title | 20 mm | 0 to 100 |
+| **Sources list position** | From the top margin to the first source | 40 mm | 0 to 150 |
+| **Sources line height** | Between the lines of one source | 8 mm | 3 to 30 |
+| **Gap between sources** | Extra space between sources | 2 mm | 0 to 20 |
+
+### Closing page
+
+| Setting | What it does | Default | Range |
+|---|---|---|---|
+| **Closing page** | Adds a last page with your own text, such as an about section or a thank-you | Off | |
+| **Closing page title** | Its heading (up to 300 characters) | About | |
+| **Closing page text** | One line per row, up to 60 lines of 300 characters. A line starting with `•` becomes a muted bullet, one ending with `:` a bold label, an empty line a gap. | Empty | |
+| **Add date, word and page counts** | Adds a Document Details list: date written, total words and total pages | On | |
+| **Closing page link** | A clickable line after your text: **Link text** and **Link address**. Without an address the words show without a link. | Off | |
+| **Closing line** | A last line, such as a sign-off, in the decorative font. Empty leaves it out. | Empty | |
+| **Closing title position** | From the top margin to the title | 20 mm | 0 to 100 |
+| **Closing text position** | From the top margin to the first line | 40 mm | 0 to 150 |
+
+### PDF details
+
+These appear in a PDF reader's document properties, not on the pages.
+
+| Setting | What it does | Default |
+|---|---|---|
+| **PDF author** | The author shown in the properties. `{title}` becomes the article title. | Empty |
+| **PDF subject** | The subject shown in the properties. | `{title}` |
+| **PDF keywords** | Search words, usually separated by commas (up to 1,000 characters) | Empty |
+| **PDF creator** | The app or person shown as the creator | Empty |
+
+## Tips
+
+- Change one group at a time and watch the preview; it redraws as you type.
+- For a book-like PDF, turn on **Parchment texture**, keep drop caps on and raise **Body line height** a little.
+- For a plain handout, set Body font to Helvetica, turn drop caps off and set **Lists headings down to** top level.
+- Put your channel name in **Brand name** and your site in **Website** so every PDF links back to you.
+
+## Related pages
+
+- [PDF documents](PDF-Documents)
+- [Channels](Channels)
+- [Library overview](Library-Overview)
+- [Play outputs](Play-Outputs)