trek 0.1.21 → 0.1.22

data/docs/.vitepress/config.mjs

@@ -0,0 +1,133 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Trek",
+  description: "A modern content management & back-office system for Ruby on Rails",
+  lang: 'en-US',
+  lastUpdated: true,
+  themeConfig: {
+    logo: { src: '/logo.svg', width: 24, height: 24 },
+
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/what-is-trek' },
+      { text: 'Reference', link: '/reference/' }
+    ],
+
+    sidebar: {
+      '/': [
+        {
+          text: 'Introduction',
+          items: [
+            { text: "What's Trek?", link: '/what-is-trek' },
+            { text: 'Getting started', link: '/getting-started' }
+          ]
+        },
+        {
+          text: 'Guides',
+          items: [
+            { text: 'How to customize Trek', link: '/customize' }
+          ]
+        },
+        {
+          text: 'Reference',
+          items: [
+            { text: 'Reference manual', link: '/reference/' }
+          ]
+        }
+      ],
+
+      '/reference/': [
+        { text: 'Overview', link: '/reference/' },
+        {
+          text: 'Generators',
+          collapsed: false,
+          items: [
+            { text: 'Installer', link: '/reference/generators/install' },
+            { text: 'Admin user', link: '/reference/generators/admin-user' },
+            { text: 'Scaffold', link: '/reference/generators/scaffold' },
+            { text: 'Taxonomies', link: '/reference/generators/taxonomies' }
+          ]
+        },
+        {
+          text: 'Models',
+          collapsed: false,
+          items: [
+            { text: 'Page', link: '/reference/models/page' },
+            { text: 'PageVersion', link: '/reference/models/page-version' },
+            { text: 'PagePath', link: '/reference/models/page-path' },
+            { text: 'Fragment', link: '/reference/models/fragment' },
+            { text: 'MenuNode', link: '/reference/models/menu-node' },
+            { text: 'ExternalLink', link: '/reference/models/external-link' },
+            { text: 'User', link: '/reference/models/user' },
+            { text: 'Tag & taxonomy', link: '/reference/models/tag' },
+            { text: 'Current', link: '/reference/models/current' }
+          ]
+        },
+        {
+          text: 'Concerns',
+          collapsed: false,
+          items: [
+            { text: 'Translatable', link: '/reference/concerns/translatable' },
+            { text: 'Contentable', link: '/reference/concerns/contentable' },
+            { text: 'Formattable', link: '/reference/concerns/formattable' },
+            { text: 'Fragmentable', link: '/reference/concerns/fragmentable' },
+            { text: 'Pageable', link: '/reference/concerns/pageable' },
+            { text: 'Sluggable', link: '/reference/concerns/sluggable' },
+            { text: 'Pathable', link: '/reference/concerns/pathable' },
+            { text: 'SearchEngineOptimizable', link: '/reference/concerns/search-engine-optimizable' },
+            { text: 'Versionable', link: '/reference/concerns/versionable' },
+            { text: 'Sectionable', link: '/reference/concerns/sectionable' },
+            { text: 'Orderable', link: '/reference/concerns/orderable' },
+            { text: 'Keyable', link: '/reference/concerns/keyable' },
+            { text: 'Searchable', link: '/reference/concerns/searchable' },
+            { text: 'Taggable', link: '/reference/concerns/taggable' },
+            { text: 'Phonable', link: '/reference/concerns/phonable' }
+          ]
+        },
+        {
+          text: 'Back-office',
+          collapsed: false,
+          items: [
+            { text: 'Controllers', link: '/reference/controllers' },
+            { text: 'Forms', link: '/reference/forms' },
+            { text: 'Formatters', link: '/reference/formatters' },
+            { text: 'Policies', link: '/reference/policies' },
+            { text: 'Uploaders', link: '/reference/uploaders' }
+          ]
+        },
+        {
+          text: 'Front-end',
+          collapsed: false,
+          items: [
+            { text: 'Components', link: '/reference/components' },
+            { text: 'Icons', link: '/reference/icons' }
+          ]
+        },
+        {
+          text: 'Configuration',
+          collapsed: false,
+          items: [
+            { text: 'Environment variables', link: '/reference/environment-variables' }
+          ]
+        }
+      ]
+    },
+
+    search: {
+      provider: 'local'
+    },
+
+    socialLinks: [
+      { icon: { svg: "<svg height='800' preserveAspectRatio='xMidYMid' viewBox='-18.5 0 293 293' width='800' xmlns='http://www.w3.org/2000/svg'><path d='m76.7478977 97.4337652-.1626607-.1626607-36.1106776 36.1106775 87.6741226 87.511462 36.110678-35.948017 51.563445-51.563445-36.110678-36.1106775v-.1626607h-103.12689z'/><path d='m127.823361.97596426-127.6886576 73.19731944v146.3946393l127.6886576 73.197319 127.688657-73.197319v-146.3946393zm103.28955 205.60313774-103.28955 59.533819-103.2895511-59.533819v-118.7423187l103.2895511-59.5338198 103.28955 59.5338198z'/></svg>" }, link: 'https://rubygems.org/gems/trek' },
+      { icon: 'npm', link: 'https://www.npmjs.com/package/trek' }
+    ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © Etamin Studio'
+    }
+  }
+})

data/docs/.vitepress/theme/index.js

@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import './style.css'
+
+/** @type {import('vitepress').Theme} */
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  }
+}

data/docs/.vitepress/theme/style.css

@@ -0,0 +1,139 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ * 
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+ :root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: var(--vp-c-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #bd34fe 30%,
+    #41d1ff
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #bd34fe 50%,
+    #47caff 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}
+

data/docs/customize.md

@@ -1,15 +1,71 @@
-## How to customize Trek
+# How to customize Trek
 
-### Admin panel branding
+Trek is designed to get you started fast with useful conventions, then get out of the way: most of the generated code lives in your application, so customizing it is just regular Rails work. Here are the most common entry points.
+
+## Admin panel branding
 
 You can pick the title and subtitle used in the admin panel header.
 
 ```yml
 # config/locales/en.yml
-admin:
-  brand:
-    title: My Awesome Project
-    subtitle: Back-office
+en:
+  admin:
+    brand:
+      title: My Awesome Project
+      subtitle: Back-office
+```
+
+## Favicon & logo
+
+Replace Trek's favicon with your own:
+
+- in SVG format at `app/assets/images/favicon.svg`
+- in PNG format (512 × 512 px) at `public/favicon.png`
+
+## Components
+
+Trek's UI components accept options where it matters:
+
+- **`Trek::Form::ActionsComponent`** — pick an `aspect` and add your own `classnames` to restyle form action bars.
+- **`Trek::DialogComponent`** — set the `title` and the buttons of modal dialogs.
+- **`Trek::Form::ContentEditorComponent`** — toggle the `nodes`, `blocks` and `floating` options to slim down the editor where full rich text isn't needed:
+
+```ruby
+f.content_editor :intro, nodes: false, floating: false
 ```
 
-Place your custom icon in `app/assets/favicon.svg` to use it in place of Trek's favicon.
+- **`Trek::LayoutComponent`** — use the `panel` slot to add your own side panel to admin screens.
+
+## Models
+
+The models generated by the installer and the scaffold are plain Active Record models in your `app/models`. Enable the commented-out hooks to opt into Trek features, for instance:
+
+```ruby
+class Book < ApplicationRecord
+  include Trek::Formattable
+  format_attributes Trek::TypographyFormatter, :title
+
+  include Trek::Translatable
+  translate_attributes :title
+
+  include RecordImageUploader::Attachment(:image)
+end
+```
+
+See the [concerns reference](/reference/) for the full list.
+
+## Policies
+
+Each scaffolded resource gets its own policy in `app/policies/admin`. Adjust the rules and `permitted_attributes` per role — the [policies reference](/reference/policies) shows the generated default.
+
+## Theming
+
+Trek's admin supports light, dark and auto themes, selectable per user. The design tokens are based on [Radix colors](https://www.radix-ui.com/colors); override the CSS custom properties in your own stylesheet to adapt the palette.
+
+## Dependencies configuration
+
+The installer configures Shrine, Postmark, Sorcery, ActionPolicy, Mobility and friends with sensible defaults — through initializers generated **in your app**. You can edit them at any time:
+
+- `config/initializers/shrine.rb` — storage backends, upload limits
+- `config/credentials.yml.enc` — Postmark API token (`EDITOR="code --wait" bin/rails credentials:edit`)
+- `config/i18n-tasks.yml` — locale management rules

data/docs/getting-started.md

@@ -0,0 +1,160 @@
+# Getting started
+
+This guide takes you from an empty directory to a working Rails application with a Trek back-office.
+
+## Prerequisites
+
+Make sure the following are installed:
+
+- Ruby 3.1+
+- Rails 7.0+
+- PostgreSQL 12+
+- Node 20+
+- Yarn 3.x
+- libvips
+
+Check your Rails version:
+
+```sh
+rails -v
+```
+
+If it's older than 7.0, run `gem install rails` to upgrade.
+
+Check your Yarn version:
+
+```sh
+yarn -v
+```
+
+If it's not a 3.x version, run:
+
+```sh
+corepack enable
+corepack install --global yarn@3
+```
+
+## Create your Rails project
+
+Replace `helloworld` with your own project name:
+
+```sh
+export TREK_PROJECT_NAME=helloworld
+rails new $TREK_PROJECT_NAME -j esbuild -d postgresql \
+  --skip-action-mailbox --skip-action-text --skip-action-cable \
+  --skip-active-storage --skip-jbuilder --skip-test --skip-system-test
+cd $TREK_PROJECT_NAME
+```
+
+## Get access to Trek
+
+Trek is distributed as a gem and an NPM package from Etamin Studio's GitLab. [Create a deploy token](https://git.etaminstud.io/etaminstudio/trek/-/settings/repository#js-deploy-tokens) associated to the Trek project:
+
+- **Name**: your project name (e.g. `helloworld`)
+- **Username**: your project name (e.g. `helloworld`)
+- **Scopes**: `read_repository`, `read_package_registry`
+
+Export the generated token (replace `XXXXXXXXXXX`):
+
+```sh
+export TREK_DEPLOY_TOKEN=XXXXXXXXXXX
+```
+
+## Install the gem
+
+Add the deploy token to your project's local Bundler config:
+
+```sh
+bundle config git.etaminstud.io $TREK_PROJECT_NAME:$TREK_DEPLOY_TOKEN
+```
+
+Install the gem and add it to your `Gemfile`:
+
+```sh
+bundle add trek --git https://git.etaminstud.io/etaminstudio/trek.git --branch main
+```
+
+Prepare the NPM package installation:
+
+```sh
+export NPM_AUTH_TOKEN=$TREK_DEPLOY_TOKEN
+```
+
+## Run the installer
+
+```sh
+rails g trek:install
+```
+
+The installer will:
+
+- install all dependencies ([see the full list](/what-is-trek#what-you-get))
+- create the `User` model and include Trek's concerns
+- create the `Page`, `PagePath` and `PageVersion` models and include Trek's concerns
+- create the `Fragment` model and include Trek's concerns
+- create the relevant policies
+- generate and run the relevant migrations
+- set up authentication (Sorcery), authorization (ActionPolicy), uploads (Shrine), emails (Postmark), i18n, linting, CI and more
+
+### Configure Postmark (optional)
+
+If you already know your [Postmark](https://postmarkapp.com) credentials, define this ENV variable **before** running the installer so it gets injected into the credentials file automatically:
+
+```sh
+export POSTMARK_API_TOKEN=YOUR_TOKEN
+```
+
+You can also do it manually afterwards:
+
+```sh
+EDITOR="code --wait" bin/rails credentials:edit
+```
+
+### Configure DeepL (optional)
+
+DeepL is used to translate locale files automatically when running the scaffold generator. To enable it, define this ENV variable before running the installer:
+
+```sh
+export DEEPL_AUTH_KEY=YOUR_TOKEN
+```
+
+Without it, translations won't happen automatically and you will have to edit each non-English locale file by hand.
+
+## Create an admin user
+
+Set `ADMIN_EMAIL` and `ADMIN_PASSWORD` in your `.env`, then run:
+
+```sh
+rails g trek:admin:user
+```
+
+## Start the server
+
+```sh
+bin/dev
+```
+
+Open `http://localhost:3000/admin` and sign in with your admin credentials. Welcome to your back-office! 🏔
+
+## Scaffold your first resource
+
+Trek's scaffold generator creates everything an admin panel needs for a model:
+
+```sh
+rails g trek:scaffold Book title:string intro:text
+```
+
+This generates, in a single command:
+
+- the `Book` model and migration (calling the Rails `model` generator behind the scenes)
+- the `Admin::BooksController` based on `Trek::ResourceController`
+- the index, show, new, edit views and form partial
+- the `Admin::BookPolicy` with role-based permissions
+- the admin routes
+- the locale files (auto-translated via DeepL if configured)
+- a menu entry in the admin dashboard
+
+Next steps:
+
+- [Customize Trek](/customize) — branding, favicon, components
+- [Reference manual](/reference/) — generators, models, components and more

data/docs/index.md

@@ -0,0 +1,39 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Trek"
+  text: "Take the easy path"
+  tagline: "A modern content management & back-office system for Ruby on Rails"
+  image:
+    src: /logo.svg
+    alt: Trek
+  actions:
+    - theme: brand
+      text: What's Trek?
+      link: /what-is-trek
+    - theme: alt
+      text: Quick start
+      link: /getting-started
+
+features:
+  - icon: 🚀
+    title: Ready out of the box
+    details: One installer sets up authentication, authorization, file uploads, emails, i18n and a polished admin UI — with sensible conventions you can override later.
+  - icon: 📝
+    title: Modern content editing
+    details: A Tiptap-based rich text editor, hierarchical pages with versioning and SEO-friendly paths, plus reusable content fragments.
+  - icon: 🛠
+    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.
+  - icon: 🌍
+    title: Multilingual by default
+    details: Content and admin UI translations powered by Mobility and i18n-tasks, with optional automatic translation via DeepL.
+  - icon: 🔐
+    title: Roles & policies built in
+    details: Sorcery authentication and ActionPolicy authorization with admin, editor, user, reader and guest roles, enforced across every panel.
+  - icon: 🧩
+    title: Hotwire-native UI
+    details: ViewComponents, Stimulus and Turbo under the hood, with light & dark themes, Radix colors and a customizable design system.
+---

data/docs/public/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" x="0" y="0" style="enable-background:new 0 0 512 512" version="1.1" viewBox="0 0 512 512"><path d="M0 0h512v512H0z" style="fill:#6ae5ac"/><path d="M201.9 93.5v91h-91c0 50.2 40.7 91 91 91v52c0 50.2 40.7 91 91 91v-325h-91zM292.9 184.5c0 50.2 40.7 91 91 91v-91h-91z" style="fill:#2d2d2d"/><path d="M292.9 418.5v-91h91c-.1 50.2-40.8 91-91 91z" style="fill:#fff"/></svg>

data/docs/reference/components.md

@@ -0,0 +1,40 @@
+# Components
+
+Trek's admin UI is built with [ViewComponent](https://viewcomponent.org), [Stimulus](https://stimulus.hotwired.dev) and [Turbo](https://turbo.hotwired.dev), styled with PostCSS and [Radix colors](https://www.radix-ui.com/colors), with light & dark themes.
+
+## UI components
+
+The main building blocks, all in the `Trek::` namespace:
+
+| Component | Purpose |
+| --- | --- |
+| `LayoutComponent` | admin layout, with header, menu and panel slots |
+| `HeaderComponent` | top navigation bar |
+| `MenuComponent` | sidebar navigation, with polymorphic slots |
+| `BrandComponent` | logo, title & subtitle area |
+| `DialogComponent` | modal dialogs, with configurable title and buttons |
+| `TabsComponent` | tabbed interfaces |
+| `ButtonComponent` | buttons & button-styled links |
+| `ListComponent` | record lists |
+| `PropertiesComponent` | key-value property display |
+| `PaginationComponent` | Kaminari-backed pagination |
+| `ToasterComponent` / `ToastComponent` | flash notifications |
+| `HeadingComponent` | headings |
+| `GateComponent` | authorization-based visibility gate |
+| `IconComponent` | SVG [icon](/reference/icons) renderer |
+
+## Form components
+
+Rendered by the [form builder](/reference/forms) helpers, under `Trek::Form::`:
+
+`GroupComponent`, `FieldsetComponent`, `ActionsComponent` (configurable aspect & classnames), `ErrorsComponent`, `TextFieldComponent`, `ImageFieldComponent`, `SoundFieldComponent`, `SwitchBoxComponent`, `CollectionSelectComponent`, `GroupedCollectionSelectComponent`, `LinkSelectComponent` and `ContentEditorComponent`.
+
+## 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:
+
+```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).

data/docs/reference/concerns/contentable.md

@@ -0,0 +1,28 @@
+# 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).
+
+## Methods
+
+| Method | Returns |
+| --- | --- |
+| `parsed_content` | the content as a hash (parsing JSON strings if needed) |
+| `formatted_content` | safe HTML, rendered through the [ProseMirror pipeline](/reference/formatters) |
+| `content_text` | plain text extracted from all text nodes |
+| `prosemirror_content?` | whether `content` is a valid ProseMirror document |
+
+## Usage
+
+```ruby
+class Page < ApplicationRecord
+  include Trek::Contentable
+end
+
+page.formatted_content # => "<p>Hello <strong>world</strong></p>"
+page.content_text      # => "Hello world"
+```
+
+## Requirements
+
+- A `content` jsonb column
+- Used by [Page](/reference/models/page), [PageVersion](/reference/models/page-version) and [Fragment](/reference/models/fragment)

data/docs/reference/concerns/formattable.md

@@ -0,0 +1,24 @@
+# Trek::Formattable
+
+Applies formatters to attributes before validation — out of the box, [`Trek::TypographyFormatter`](/reference/formatters#typographyformatter) and its French typography rules.
+
+## API
+
+```ruby
+class Page < ApplicationRecord
+  include Trek::Formattable
+  format_attributes Trek::TypographyFormatter, :title, :description
+end
+```
+
+`format_attributes(formatter_class, *attr_names)` registers the attributes; a `before_validation` callback runs the formatter on each of them.
+
+## Usage
+
+```ruby
+page = Page.new(title: "Un titre: voici...")
+page.valid?
+page.title # => "Un titre : voici…"
+```
+
+Works on plain strings **and** on ProseMirror documents (only `text` nodes are touched; the structure is preserved).