trek 2.5.0 → 2.6.0

data/docs/background-jobs.md

@@ -0,0 +1,69 @@
+# Background jobs
+
+Trek apps run Active Job on [GoodJob](https://github.com/bensheldon/good_job), installed by `rails g trek:install` (or on its own with `rails g trek:install:good_job`). GoodJob stores its queue in the application's own PostgreSQL database, so there is no second database to provision — which is why the installer removes the Solid Queue setup `rails new` generates.
+
+## What the installer sets up
+
+| Where                               | What                                                                                                      |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `Gemfile`                           | `good_job` replaces `solid_queue` (Solid Cache stays: its table lives in the primary database)            |
+| `config/application.rb`             | `config.active_job.queue_adapter = :good_job` and `config.action_mailer.delivery_job = "MailDeliveryJob"` |
+| `config/environments/production.rb` | `config.good_job.execution_mode = :async` and `config.good_job.shutdown_timeout = 25`                     |
+| `config/environments/test.rb`       | `config.active_job.queue_adapter = :test`, so specs can check what is enqueued (`have_enqueued_job`)      |
+| `config/initializers/good_job.rb`   | queues, cron, error reporting, and the dashboard guard                                                    |
+| `config/database.yml`               | a connection pool sized for the web threads **and** the job threads                                       |
+| `app/jobs/mail_delivery_job.rb`     | the delivery job every `deliver_later` email goes through                                                 |
+| `config/routes.rb`                  | `mount GoodJob::Engine => "good_job"` inside `namespace :admin`                                           |
+
+## Async in Puma, or a dedicated worker
+
+In production the jobs run in the web container's own threads (`execution_mode = :async`): nothing else to deploy, nothing else to pay for. `shutdown_timeout = 25` lets a restart drain the jobs in flight instead of dropping them.
+
+`GOOD_JOB_MAX_THREADS` sizes the job pool. It also feeds the database pool, since `config/database.yml` reserves connections for the web threads and the job threads separately:
+
+```yml
+max_connections: <%= web = ENV.fetch("RAILS_MAX_THREADS", 5).to_i; 1 + web + ENV.fetch("GOOD_JOB_MAX_THREADS", web).to_i %>
+```
+
+When the jobs outgrow the web container — long-running work, or a queue that must not compete with requests — move them to their own process: set `config.good_job.execution_mode = :external` and uncomment the worker line in the `Procfile` (`worker: bundle exec good_job start`). Note that in `:external` mode only the worker runs a scheduler, so cron then runs there and nowhere else.
+
+## Queues
+
+One scheduler serves every queue by default (`config.good_job.queues = "*"`). Give a queue its own lane when it must not wait behind the others:
+
+```ruby
+config.good_job.queues = "mailers:2;*:3"
+```
+
+The thread counts have to stay within `GOOD_JOB_MAX_THREADS` — they are database connections too.
+
+## Scheduled jobs (cron)
+
+Recurring jobs are declared in the initializer, and only run in production (a development machine should not fire them):
+
+```ruby
+config.good_job.enable_cron = Rails.env.production?
+config.good_job.cron = {
+  purge_old_sessions: {
+    cron: "0 3 * * *", # every day at 3am
+    class: "PurgeOldSessionsJob",
+    description: "Delete the user sessions that expired more than a month ago"
+  }
+}
+```
+
+## The dashboard
+
+GoodJob's dashboard is mounted at `/admin/good_job`. It sits outside `Admin::BaseController`, so it is guarded in the initializer by the same signed session cookie the admin uses: anyone who is not an administrator gets a 404 rather than a redirect, which keeps the route invisible. The installed request spec covers the three cases (administrator, privileged non-administrator, visitor).
+
+## Mail deliveries are retried
+
+GoodJob discards a failed job rather than retrying it, so a transient error from the mail service would lose the email. Every `deliver_later` goes through `MailDeliveryJob` instead, which retries five times with a growing delay:
+
+```ruby
+class MailDeliveryJob < ActionMailer::MailDeliveryJob
+  retry_on StandardError, wait: :polynomially_longer, attempts: 5
+end
+```
+
+An error raised in a scheduler thread, outside a job's own execution, has no retry handler to catch it; `config.good_job.on_thread_error` reports it through `Rails.error` like the rest of the app.

data/docs/content-editor.md

@@ -0,0 +1,219 @@
+# Content editor
+
+Trek's content editor is where the admin writes the content of pages, page versions and fragments: headings, lists, quotes, links, images and calls to action, laid out as they will read.
+
+It's built on [Tiptap](https://tiptap.dev), an editor framework on top of [ProseMirror](https://prosemirror.net). That's why the editor doesn't save HTML. It saves a structured document: a tree of typed nodes (paragraphs, headings, images…) and marks (bold, links…), each with typed attributes. The site turns that document into HTML when it shows it, with the [`prosemirror`](https://github.com/etaminstudio/prosemirror) gem.
+
+Keeping structure rather than markup lets Trek:
+
+- **render the content safely:** the HTML is built from known types, so content can't inject markup;
+- **change how a block looks** on the site without touching stored content, for example images rendered by the app's own component;
+- **keep links to pages working** when they move: a link stores the page, not its URL;
+- **read the content as data:** extract its text, search it, check it.
+
+This guide follows content from end to end:
+
+1. **Editing:** [using the editor](#using-the-editor) in admin forms, and its panels.
+2. **Storage:** [how content is stored](#how-content-is-stored), as JSON in a `jsonb` column.
+3. **Rendering:** [rendering on the site](#rendering-on-the-site), through `Trek::Content.schema`, and [customizing it](#customizing-the-rendering).
+
+## Using the editor
+
+Add it to an admin form with `f.content_editor`:
+
+```slim
+= form_with model: [:admin, @book] do |f|
+  = f.group :content
+    = f.content_editor :content
+```
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `nodes` | `true` | the toolbar's text buttons: bold, italic, link, clear formatting, line break |
+| `blocks` | `true` | the toolbar's block buttons: paragraph, headings 2 to 4, bullet list, quote, horizontal rule |
+| `floating` | `true` | the menu on an empty line, inserting an image or a prompt |
+| `autofocus` | `false` | puts the cursor at the end of the content on load |
+
+Undo and redo are always there. For a short field, such as an introduction, turn the rest off:
+
+```slim
+= f.content_editor :intro, blocks: false, floating: false
+```
+
+Tiptap's Markdown shortcuts work too: typing `1. ` starts an ordered list, and `~~text~~` strikes text through, even though the toolbar has no button for them. The site renders them like the rest.
+
+### Links
+
+The link button opens a panel to pick a page of the site, or type any URL. A link to a page is stored as its GlobalID (`gid://app/Page/12`) rather than its URL. It's turned into a URL when the content is rendered, so the link survives the page moving or changing its slug (see [Links to records with GlobalID](https://github.com/etaminstudio/prosemirror/blob/main/COOKBOOK.md#links-to-records-with-globalid) in the `prosemirror` gem's cookbook).
+
+### Images
+
+The image entry of the floating menu opens a panel to upload an image (with Uppy, stored by Shrine's `ModelImageUploader`). The panel also sets its alternative text, caption, credit and size (`default` or `larger`). The node keeps the uploaded file's data, so the image belongs to the content, not to a record.
+
+### Prompts
+
+The prompt entry inserts a call to action: a text, a link (a page or a URL, as for links), where it opens, and a title.
+
+### Panels
+
+The link, image and prompt panels are the `Admin::Panels::*` controllers that the installer generates (see [Controllers](/reference/controllers)).
+
+## How content is stored
+
+The editor saves a ProseMirror document in the form's field, as JSON, with Tiptap's camelCase type names:
+
+```json
+{
+  "type": "doc",
+  "content": [
+    { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "Opening hours" }] },
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "See the " },
+        { "type": "text", "text": "map", "marks": [{ "type": "link", "attrs": { "href": "gid://app/Page/12" } }] }
+      ]
+    },
+    { "type": "imageBlock", "attrs": { "file_data": "{\"id\":\"…\",\"storage\":\"store\"}", "alt": "The entrance", "text": "Main entrance", "credit": "Photo: A. Smith", "size": "larger" } }
+  ]
+}
+```
+
+- **Column:** Trek's models keep it in a `jsonb` `content` column. [Translatable](/reference/concerns/translatable) models hold one document per locale.
+- **Cleaning:** before saving, [Contentable](/reference/concerns/contentable) removes what rendering skips: empty paragraphs, empty list items, and lists left empty. An empty document keeps one paragraph, and whatever the schema doesn't know is kept. The editor submits the content as a JSON string, and it's stored as a document. Empty paragraphs used for spacing are removed for good.
+- **Typography:** [Formattable](/reference/concerns/formattable) works on documents, changing only their text nodes. Add `:content` to the generated `format_attributes Trek::TypographyFormatter, :title, :description` to apply French typography to it.
+- **Search:** to find content by its words, search the text nodes rather than the JSON, or every document matches `paragraph`. `content_text` gives the plain text, and `Fragment.search` shows a query in SQL (see [Fragment](/reference/models/fragment)).
+
+## Rendering on the site
+
+A model with a `content` column includes [Contentable](/reference/concerns/contentable):
+
+```slim
+/ ERB or Slim
+= @page.formatted_content
+```
+
+```ruby
+# Phlex
+render @page.content_document.to_phlex
+```
+
+For a [versioned](/reference/concerns/versionable) page, render its live version's content, `current_content`, which comes from a `PageVersion`: `Trek::Content::Document.parse(@page.current_version || @page, @page.current_content).to_html`.
+
+`formatted_content` only reads the `content` column. To render another column, such as a book's `intro`, parse it with `Trek::Content::Document`. Its first argument is the record holding the content: when that content is invalid, the error reports name the record (`trek_content: "Book#3"`, see [Invalid content](#invalid-content)), so you know which one to fix.
+
+```ruby
+Trek::Content::Document.parse(book, book.intro).to_html
+```
+
+### What the HTML contains
+
+- **Escaping:** HTML is escaped as it is built. Nothing a user types can open a tag.
+- **Attributes** are typed: a value that doesn't fit, such as a heading level of 9, is replaced by its default, or removed.
+- **URLs:** links and images only allow `http`, `https`, `mailto`, `tel` and relative URLs.
+- **Links to pages** become the page's URL, through `url_for`. The records a document links to load together, with one query per model. A link to a deleted record is removed, and its text kept.
+- **Empty nodes:** empty paragraphs, empty list items, and lists with only empty items render nothing ([Skip empty paragraphs](https://github.com/etaminstudio/prosemirror/blob/main/COOKBOOK.md#skip-empty-paragraphs)). Saving removes them from the stored content too ([cleaning](#how-content-is-stored)), but content saved before Trek did is only cleaned when it's saved again.
+- **Images** render as a `<figure>` with a `data-size` attribute, with the caption and the credit in its `<figcaption>`.
+- **Prompts** render as a link.
+- **Unknown attributes,** such as heading ids added by the editor, are kept in the JSON but never rendered. To give headings anchors, see [Heading anchors](https://github.com/etaminstudio/prosemirror/blob/main/COOKBOOK.md#heading-anchors) in the `prosemirror` gem's cookbook.
+
+### Invalid content
+
+A document that doesn't fit the schema is fixed as it's read, and each problem is reported to `Rails.error` (`handled: true`):
+
+- an attribute of the wrong type is converted when the meaning is clear, or replaced by its default, or its node or mark is removed (a link keeps its text);
+- a node of an unknown type renders only its content;
+- links to deleted records, reported as `Prosemirror::UnresolvedURL`.
+
+The report's context names the record holding the content (`trek_content: "Page#12"`), which AppSignal shows as a tag, so a problem leads back to the page to fix.
+
+## Customizing the rendering
+
+`Trek::Content.schema` is Tiptap's schema (`Prosemirror::Schema.tiptap(case: :camel)`), with Trek's own node types:
+
+| Node type | Role |
+| --- | --- |
+| `Trek::Content::Paragraph` | skips empty paragraphs |
+| `Trek::Content::ListItem` | skips empty list items, with no content or only empty paragraphs |
+| `Trek::Content::BulletList`, `OrderedList` | skip lists with only empty items |
+| `Trek::Content::ImageBlock` | renders image blocks as a `<figure>`: the image, its caption and credit |
+| `Trek::Content::PromptsBlock` | renders prompt blocks as a link |
+
+Node and mark types are [Phlex](https://www.phlex.fun) components with [Literal](https://literal.fun) properties (see the [`prosemirror` README](https://github.com/etaminstudio/prosemirror#custom-nodes-and-marks)). To change how one renders, subclass it, and put it in the schema from an initializer. The cookbook's [Render your own components](https://github.com/etaminstudio/prosemirror/blob/main/COOKBOOK.md#render-your-own-components) shows the pattern.
+
+### Images with the app's component
+
+For example, images at the app's own sizes:
+
+```ruby
+# app/content/image_block.rb
+class ImageBlock < Trek::Content::ImageBlock
+  def view_template
+    return unless image
+
+    render Components::Figure.new(
+      src: image.derivation_url(:thumbnail, 930, 1200),
+      alt: @alt,
+      caption: @text,
+      credit: @credit
+    )
+  end
+end
+```
+
+```ruby
+# config/initializers/trek.rb
+Rails.application.config.to_prepare do
+  Trek::Content.schema = Trek::Content.default_schema.with(ImageBlock)
+end
+```
+
+- **Registering:** `with` replaces the type of the same name, and keeps the others.
+- **Reloading:** the default schema is rebuilt after code reloading, so `to_prepare` sees the reloaded classes in development.
+- **Inside a node type:**
+  - the node's attributes are instance variables (`@alt`, `@text`);
+  - `image` is the uploaded file, or `nil` when the data is missing or invalid;
+  - `safe_url(url)` checks a URL against the allowed schemes.
+
+### Prompts as the app's buttons
+
+```ruby
+class PromptsBlock < Trek::Content::PromptsBlock
+  def view_template
+    href = @href.present? && safe_url(@href)
+    return if !href || @text.blank?
+
+    render Components::Button.new(href:, target: @target, title: @title) { @text }
+  end
+end
+```
+
+Register it the same way: `Trek::Content.default_schema.with(ImageBlock, PromptsBlock)`.
+
+### Node types of the app's own
+
+A node of a type the schema doesn't know renders only its content, and is reported. To render it, add a class of that name to the schema (`Callout` for `callout`):
+
+```ruby
+class Callout < Prosemirror::NodeType
+  group :block
+  content "block+"
+
+  prop :tone, _Union?("info", "warning")
+
+  def view_template(&) = aside(data_tone: @tone, &)
+end
+```
+
+Trek's editor has a fixed set of Tiptap extensions, so it can't insert such a node yet. It renders nodes that come from elsewhere: imported content, or JSON written by a script.
+
+## Importing content
+
+The `prosemirror` gem builds documents from HTML (with the `herb` gem), Markdown (with `commonmarker`) or plain text, using the schema's parse rules. To fill pages from an older site:
+
+```ruby
+document = Prosemirror.from_html(old_html, schema: Trek::Content.schema)
+page.update!(content: document.to_h)
+```
+
+`to_h` gives the JSON the editor reads, with invalid parts fixed. See the [`prosemirror` README](https://github.com/etaminstudio/prosemirror#html-import) for what each import keeps.

data/docs/customize.md

@@ -48,6 +48,8 @@ Trek's UI components accept options where it matters:
 f.content_editor :intro, nodes: false, floating: false
 ```
 
+To render content blocks with your own components, see [Customizing the rendering](/content-editor#customizing-the-rendering).
+
 - **`Trek::LayoutComponent`** — use the `panel` slot to add your own side panel to admin screens.
 
 ## Models

data/docs/deploy.md

@@ -17,7 +17,7 @@ Compared with the stock buildpacks, deploys typically go from around 3 minutes t
 Generate the Scalingo files (an `Aptfile` and a `Procfile` with the web process and post-deploy migrations):
 
 ```sh
-rails g trek:install:scalingo
+rails g trek:scalingo
 ```
 
 Then configure the Scalingo app's environment, pinning the buildpack to a release through its archive:
@@ -57,7 +57,7 @@ Before going live, check what Trek expects from the hosting: backups, a shared c
 
 Apps deployed with the stock `.buildpacks` (apt + ruby) migrate in three steps:
 
-1. delete `.buildpacks` (re-running `rails g trek:install:scalingo` does it) and check that `.node-version` exists — apps generated with `rails new -j esbuild` have it
+1. delete `.buildpacks` (re-running `rails g trek:scalingo` does it) and check that `.node-version` exists — apps generated with `rails new -j esbuild` have it
 2. set `BUILDPACK_URL` as above, and map `DATABASE_URL` if the app doesn't read it yet
 3. deploy — the first build fills the caches, the next ones benefit from them
 

data/docs/getting-started.md

@@ -132,4 +132,4 @@ Next steps:
 
 - [Customize Trek](/customize) — branding, favicon, components
 - [Reference manual](/reference/) — generators, models, components and more
-- [Deploying to Scalingo](/deploy) — `trek:install:scalingo`, a few environment variables, and the dedicated trek-buildpack handles the rest
+- [Deploying to Scalingo](/deploy) — `trek:scalingo`, a few environment variables, and the dedicated trek-buildpack handles the rest

data/docs/index.md

@@ -23,7 +23,7 @@ features:
     details: One installer sets up authentication, authorization, file uploads, emails, i18n and a polished admin UI — with sensible conventions you can override later.
   - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M6 6H30V30A12 12 0 0 1 18 42H6ZM12 14H24V18H12ZM12 22H20V26H12Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M34 6H42V32A4 4 0 0 1 34 32Z"/></svg>'
     title: Modern content editing
-    details: A Tiptap-based rich text editor, hierarchical pages with versioning and SEO-friendly paths, plus reusable content fragments.
+    details: A Tiptap-based content editor, hierarchical pages with versioning and SEO-friendly paths, plus reusable content fragments.
   - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M6 18H30V30H42V42H6Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M6 18V6A12 12 0 0 1 18 18Z"/></svg>'
     title: Scaffold-driven development
     details: One command generates the model, admin panel, views, policy, routes and locales for any resource — just like Rails scaffolding, but for your back-office.

data/docs/reference/components.md

@@ -47,10 +47,10 @@ Rendered by the [form builder](/reference/forms) helpers, under `Trek::Form::`:
 
 ## Content editor
 
-`Trek::Form::ContentEditorComponent` wraps the [Tiptap](https://tiptap.dev) editor and accepts three options — `nodes`, `blocks` and `floating` (all enabled by default) — to toggle the node toolbar, block formatting and floating menu:
+`Trek::Form::ContentEditorComponent` wraps the [Tiptap](https://tiptap.dev) editor and accepts `nodes`, `blocks` and `floating` (all enabled by default) to toggle the text buttons, the block buttons and the floating menu, and `autofocus`:
 
 ```ruby
 f.content_editor :intro, nodes: false, floating: false
 ```
 
-Content is stored as ProseMirror JSON and rendered with [`formatted_content`](/reference/concerns/contentable). Image uploads (Uppy), link insertion and prompts are served by the [panel controllers](/reference/controllers).
+Content is stored as ProseMirror JSON and rendered with [`formatted_content`](/reference/concerns/contentable). Image uploads (Uppy), link insertion and prompts are served by the [panel controllers](/reference/controllers). See the [Content editor](/content-editor) guide for its toolbar, how content is stored and rendered, and how to customize it.

data/docs/reference/concerns/contentable.md

@@ -1,6 +1,6 @@
 # Trek::Contentable
 
-Utilities for rich text stored as ProseMirror JSON in a `content` column — the format produced by Trek's [content editor](/reference/components#content-editor).
+Utilities for content stored as ProseMirror JSON in a `content` column — the format produced by Trek's [content editor](/content-editor).
 
 ## Methods
 
@@ -8,8 +8,8 @@ Utilities for rich text stored as ProseMirror JSON in a `content` column — the
 | --- | --- |
 | `parsed_content` | the content as a hash (parsing JSON strings if needed) |
 | `content_document` | the content as a `Prosemirror::Document`, to query or render it |
-| `formatted_content` | safe HTML, rendered as described in [Rich text rendering](/reference/formatters#rich-text-rendering) |
-| `content_text` | plain text extracted from all text nodes |
+| `formatted_content` | safe HTML, rendered as described in [Rendering on the site](/content-editor#rendering-on-the-site) |
+| `content_text` | the plain text of the content: blocks separated by a blank line, hard breaks by a newline |
 | `prosemirror_content?` | whether `content` is a valid ProseMirror document |
 
 ## Usage
@@ -23,7 +23,13 @@ page.formatted_content # => "<p>Hello <strong>world</strong></p>"
 page.content_text      # => "Hello world"
 ```
 
+Content in another column renders through the same schema: `Trek::Content::Document.parse(record, record.intro).to_html`. See the [Content editor](/content-editor) guide for the whole path, from the editor to the HTML.
+
+## Cleaning before saving
+
+Before validation, empty paragraphs, empty list items and lists left empty are removed from the content, as rendering skips them (`Trek::Content::Cleaner`). The document stays one the editor opens: an empty document keeps one paragraph, a list item keeps the first paragraph it needs, and node types or attributes the schema doesn't know are kept. Content submitted as a JSON string, as the content editor sends it, is stored as a document. Translated content is cleaned in the current locale.
+
 ## Requirements
 
 - A `content` jsonb column
-- Used by [Page](/reference/models/page), [PageVersion](/reference/models/page-version) and [Fragment](/reference/models/fragment)
+- Used by [Page](/reference/models/page) and [Fragment](/reference/models/fragment)

data/docs/reference/concerns/formattable.md

@@ -21,4 +21,4 @@ page.valid?
 page.title # => "Un titre : voici…"
 ```
 
-Works on plain strings **and** on ProseMirror documents (only `text` nodes are touched; the structure is preserved).
+Works on plain strings **and** on ProseMirror documents (only `text` nodes are touched; the structure is preserved), including a document submitted by the content editor as a JSON string, which comes back as a Hash.

data/docs/reference/environment-variables.md

@@ -9,5 +9,6 @@
 | `APPSIGNAL_APP_ENV` | environment name reported to AppSignal (optional, defaults to `RAILS_ENV`) |
 | `DEEPL_AUTH_KEY` | automatic locale translation in the [scaffold generator](/reference/generators/scaffold) |
 | `FEATURE_AUDIT_LOG` | `false` stops the [audit log](/reference/generators/audit-log) recording requests (on by default) |
+| `GOOD_JOB_MAX_THREADS` | number of job threads GoodJob runs, and the share of the database pool reserved for them (optional, defaults to `RAILS_MAX_THREADS`) — see [Background jobs](/background-jobs) |
 | `FEATURE_STORAGE` | `local` (development) or `s3` (production) |
 | `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BASE_URL` | S3 storage configuration for [uploads](/reference/uploaders) |

data/docs/reference/formatters.md

@@ -18,36 +18,8 @@ format_attributes Trek::TypographyFormatter, :title
 
 ## Rich text rendering
 
-`formatted_content` (from [Contentable](/reference/concerns/contentable)) renders the content editor's ProseMirror JSON to HTML with the [`prosemirror`](https://github.com/etaminstudio/prosemirror) gem. HTML is escaped as it is built, attributes are typed, and links and images only allow `http`, `https`, `mailto`, `tel` and relative URLs. Invalid content is fixed and reported to `Rails.error`.
-
-`Trek::Content.schema` is Tiptap's schema, with:
-
-| Node type | Role |
-| --- | --- |
-| `Trek::Content::Paragraph` | skips empty paragraphs |
-| `Trek::Content::ListItem` | skips empty list items, with no content or only empty paragraphs |
-| `Trek::Content::BulletList`, `OrderedList` | skip lists with only empty items |
-| `Trek::Content::ImageBlock` | renders image blocks as a `<figure>`: the image, its caption and credit |
-| `Trek::Content::PromptsBlock` | renders prompt blocks as a link |
-
-Links to records are stored as GlobalIDs (`gid://app/Page/1`). `Trek::Content::LinkResolver` turns them into the record's URL with `url_for`, loading the records of a document's links at once, with one query per model; a link to a deleted record is removed and its text kept, and reported to `Rails.error` as a `Prosemirror::UnresolvedURL`. Problems in content are reported with the record holding it in their context (`trek_content: "Page#12"`), which AppSignal shows as a tag.
+`formatted_content` (from [Contentable](/reference/concerns/contentable)) renders the content editor's ProseMirror JSON to HTML with the [`prosemirror`](https://github.com/etaminstudio/prosemirror) gem, through `Trek::Content.schema`: HTML is escaped as it is built, attributes are typed, links and images only allow safe URLs, and links to pages are resolved. See [Rendering on the site](/content-editor#rendering-on-the-site) for what the HTML contains, and how invalid content is reported.
 
 ### Custom blocks
 
-Node types are [Phlex](https://www.phlex.fun) components with [Literal](https://literal.fun) properties (see the [`prosemirror` README](https://github.com/etaminstudio/prosemirror#custom-nodes-and-marks)). To render the image block with the app's own component, subclass it and register it in an initializer:
-
-```ruby
-# app/content/image_block.rb
-class ImageBlock < Trek::Content::ImageBlock
-  def view_template
-    render Components::Figure.new(src: image&.url, alt: @alt, caption: @text, credit: @credit)
-  end
-end
-
-# config/initializers/trek.rb
-Rails.application.config.to_prepare do
-  Trek::Content.schema = Trek::Content.default_schema.with(ImageBlock)
-end
-```
-
-The same works for a node type of your own, added to the editor with a Tiptap extension.
+Trek's node types (`Trek::Content::ImageBlock`, `PromptsBlock`…) can be subclassed to render the app's own components, and registered with `Trek::Content.schema = Trek::Content.default_schema.with(…)`: see [Customizing the rendering](/content-editor#customizing-the-rendering).

data/docs/reference/forms.md

@@ -5,7 +5,7 @@ Trek ships `Trek::FormBuilder`, an extension of [`ViewComponent::Form`](https://
 | Helper | Renders |
 | --- | --- |
 | `f.group` | a label + input wrapper with errors |
-| `f.content_editor` | the Tiptap rich text editor |
+| `f.content_editor` | the [content editor](/content-editor), based on Tiptap |
 | `f.image_field` | an image uploader with thumbnail preview (Uppy + Shrine) |
 | `f.sound_field` | an audio file uploader |
 | `f.switch_box` | a toggle switch |

data/docs/reference/generators/audit-log.md

@@ -1,7 +1,7 @@
 # Audit log
 
 ```sh
-rails g trek:install:audit_log
+rails g trek:audit_log
 bin/rails db:migrate
 ```
 
@@ -108,6 +108,6 @@ The rows hold personal data: the author, the IP address, the user agent, and wha
 
 The `audit_logs` table uses the column names of the audit logs some apps wrote themselves (`actor`, `auditable`, `action`, `http_method`, `path`, `http_status`, `params`, `ip_address`, `user_agent`, `request_id`, `error_class`, `created_at`), so existing rows carry over. In such an app, skip the migration and replace the app's own files:
 
-1. Run `rails g trek:install:audit_log`, delete the generated `db/migrate/*_trek_audit_logs.rb`, and let the generator overwrite the model, controller, views and policy.
+1. Run `rails g trek:audit_log`, delete the generated `db/migrate/*_trek_audit_logs.rb`, and let the generator overwrite the model, controller, views and policy.
 2. Delete the app's `Auditable` concern, its initializer and its purge job, and update the job's cron entry to `Trek::AuditLog::PurgeJob`.
 3. Move app-specific columns (e.g. a request duration, or a denormalized foreign key) to `audit_attributes`, and their scopes and associations to the `AuditLog` model.

data/docs/reference/generators/install.md

@@ -15,6 +15,8 @@ Trek provides an install generator, that will:
 - create the relevant policies
 - generate and run the relevant migrations
 
+It ends with what to do next: create an admin user, start the server, and the generators it leaves for later, to run as the app needs them: [`trek:scaffold`](/reference/generators/scaffold), [`trek:taxonomies`](/reference/generators/taxonomies), [`trek:audit_log`](/reference/generators/audit-log), [`trek:public_accounts`](/reference/generators/public-accounts) and [`trek:scalingo`](/deploy).
+
 ## Sub-generators
 
 The installer orchestrates dedicated sub-generators, all under the `trek:install:*` namespace. Each one can also be run individually, e.g. `rails g trek:install:healthcheck`.
@@ -32,12 +34,11 @@ The installer orchestrates dedicated sub-generators, all under the `trek:install
 | Tooling | esbuild, PostCSS, EditorConfig, Procfiles, Makefile, health check endpoint |
 | Linting | Standard, ESLint, Stylelint, Prettier, Slim Lint, Lefthook git hooks |
 | Security | Brakeman, bundler-audit, ruby_audit; HTTPS only (`force_ssl`, with HSTS), a Content Security Policy and the Permissions-Policy header (`trek:install:security_headers`) — see [Security headers](/reference/generators/security-headers) |
+| Jobs | GoodJob as the Active Job backend, replacing Solid Queue — dashboard at `/admin/good_job`, cron in `config/initializers/good_job.rb`, pool sized by `GOOD_JOB_MAX_THREADS` — see [Background jobs](/background-jobs) |
 | Monitoring | AppSignal error tracking and performance monitoring — `config/appsignal.rb`, the push API key in the credentials, and the `AppsignalContext` concern tagging transactions per area and user |
 | Specs | RSpec, and specs for the models Trek installs (`trek:install:model_specs`): `spec/models/page_spec.rb` and `spec/models/user_spec.rb`, with their test data as [Oaken](https://github.com/kaspth/oaken) seed scripts — defaults in `db/seeds/setup/`, scenarios in `db/seeds/test/cases/` loaded with `seed "cases/…"`. They check Trek's behaviour in your app — slugs and paths, user validations and roles — so a customization that breaks it fails your suite; edit or remove the ones you deliberately change. Trek's own suite runs the same files |
 | N+1 detection | Prosopite (development/test), scanning every request — see [Controllers › N+1 detection](/reference/controllers#n-1-detection) |
 | CI | GitLab CI configuration: specs, linters, Brakeman, bundler-audit, and, commented out, a [Software Bill of Materials](#software-bill-of-materials) |
-| Deployment | Scalingo files (`trek:install:scalingo`, run on demand) — see [Deploying to Scalingo](/deploy) |
-| Audit log | The `AuditLog` model recording the admin's requests, and its admin list (`trek:install:audit_log`, run on demand) — see [Audit log](/reference/generators/audit-log) |
 
 ## ENV variables read by the installer