trek 0.1.21 → 0.1.22

data/docs/reference/models/fragment.md

@@ -0,0 +1,28 @@
+# Fragment
+
+Reusable chunks of content — a footer text, a hero tagline, a contact blurb — editable from the admin and usable anywhere in your views. Fragments are grouped by `namespace` and identified by `key`.
+
+## Columns
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `key` | string | unique within its namespace |
+| `namespace` | string | grouping (e.g. `footer`, `home`) |
+| `title` | jsonb | translated label |
+| `content` | jsonb | ProseMirror document |
+| `position` | integer | ordering within the namespace |
+
+## Behavior
+
+- Includes [Contentable](/reference/concerns/contentable), [Translatable](/reference/concerns/translatable) (`title`, `content`), [Keyable](/reference/concerns/keyable) and `strip_attributes`
+- `acts_as_list scope: [:namespace]` with an `ordered` scope
+- `to_s` returns `"namespace.key"`
+
+## Usage
+
+```ruby
+fragment = Fragment.find_by(namespace: "footer", key: "tagline")
+fragment.formatted_content # => safe HTML
+```
+
+Pages can also be composed from fragments via the [Fragmentable](/reference/concerns/fragmentable) concern and the `page_fragments` configuration matrix.

data/docs/reference/models/menu-node.md

@@ -0,0 +1,30 @@
+# MenuNode
+
+Hierarchical menu builder: each node links to a [Page](/reference/models/page), an [ExternalLink](/reference/models/external-link), or any custom linkable model.
+
+## Columns
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `key` | string | unique within its parent, optional |
+| `title` / `label` | jsonb | translated texts |
+| `parent_id` | bigint | tree hierarchy |
+| `position` | integer | ordering among siblings |
+| `linkable_type` / `linkable_id` | string / bigint | polymorphic target |
+| `icon_key` | string | optional [icon](/reference/icons) |
+| `modifiers` | string | styling flags |
+
+## Behavior
+
+- `has_closure_tree` for the hierarchy, [Orderable](/reference/concerns/orderable) for positions
+- `belongs_to :linkable, polymorphic: true, optional: true`
+- Includes [Translatable](/reference/concerns/translatable) and `strip_attributes`
+
+## Notable methods
+
+| Method | Returns |
+| --- | --- |
+| `to_s` | title, label or key |
+| `to_param` | key or id |
+| `icon?` / `icon` | whether an icon is set / the `IconComponent` for it |
+| `external_link?` | whether the target is an `ExternalLink` |

data/docs/reference/models/page-path.md

@@ -0,0 +1,19 @@
+# PagePath
+
+Stable, translatable URLs for [pages](/reference/models/page). Trek keeps every path a page has ever had, so old URLs keep working (redirecting to the current one) after a page is renamed or moved.
+
+## Columns
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `page_id` | bigint | required |
+| `path` | jsonb | translated full path (e.g. `services/design`) |
+
+## Behavior
+
+- `belongs_to :page` — all historical paths of the page
+- `has_one :current_page` — the page this path is the *current* path for (via `pages.current_path_id`)
+- Includes [Translatable](/reference/concerns/translatable) — paths are localized per locale
+- Records are created and updated automatically by the page's `after_save_commit` callback; you never manage them by hand
+
+See [Pathable](/reference/concerns/pathable) for the page-side API (`full_path`, `find_at_full_path`…).

data/docs/reference/models/page-version.md

@@ -0,0 +1,30 @@
+# PageVersion
+
+Version history for [pages](/reference/models/page): every snapshot of a versioned page's content and image. There is always exactly one *current* version per page; the others are archived.
+
+## Columns
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `page_id` | bigint | required |
+| `name` | string | version label, auto-generated from the page title and date |
+| `content` | jsonb | ProseMirror content snapshot |
+| `image_data` | jsonb | Shrine attachment snapshot |
+| `current_since` | datetime | set ⇔ this is the current version |
+
+## Behavior
+
+- `belongs_to :page` — with `Page#versions` ordered most recent first
+- Validations guarantee **one and only one** current version per page
+- `after_initialize` sets a default name like `"Page title (2026-06-10)"`
+- Includes [Sectionable](/reference/concerns/sectionable), `RecordImageUploader::Attachment(:image)` and `strip_attributes`
+
+## Notable methods
+
+| Method | Returns |
+| --- | --- |
+| `current?` | whether this version is the live one |
+| `other_versions` | the page's other versions |
+| `current_image` / `current_image_url` | this version's image |
+
+See [Versionable](/reference/concerns/versionable) for the page-side API (`create_current_version_from_page!`, `current_content`…).

data/docs/reference/models/page.md

@@ -0,0 +1,48 @@
+# Page
+
+Hierarchical, translatable content pages with SEO metadata, versioning and stable URL paths. Generated into `app/models/page.rb`.
+
+## Columns
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `key` | string | internal identifier, optional |
+| `slug` | jsonb | translated URL slug |
+| `title` | jsonb | translated title |
+| `description` | jsonb | translated description |
+| `content` | jsonb | ProseMirror document |
+| `pageable_type` / `pageable_id` | string / bigint | polymorphic link to a content model |
+| `parent_id` | bigint | tree hierarchy |
+| `position` | integer | ordering among siblings |
+| `image_data` | jsonb | Shrine attachment |
+| `versioned` | boolean | enables [versioning](/reference/concerns/versionable), default `false` |
+| `sectioned` | boolean | enables [sections](/reference/concerns/sectionable), default `false` |
+| `current_path_id` | bigint | current [PagePath](/reference/models/page-path) |
+
+## Included concerns
+
+[Translatable](/reference/concerns/translatable) (`slug`, `title`, `description`), [Formattable](/reference/concerns/formattable), [Contentable](/reference/concerns/contentable), [Fragmentable](/reference/concerns/fragmentable), [Orderable](/reference/concerns/orderable), [Pathable](/reference/concerns/pathable), [SearchEngineOptimizable](/reference/concerns/search-engine-optimizable), [Sectionable](/reference/concerns/sectionable), [Sluggable](/reference/concerns/sluggable), [Versionable](/reference/concerns/versionable), [Keyable](/reference/concerns/keyable), plus `RecordImageUploader::Attachment(:image)` and `strip_attributes`.
+
+## Associations
+
+- `has_closure_tree` — parent/children hierarchy (siblings, ancestors, descendants)
+- `belongs_to :pageable, polymorphic: true, optional: true` — the content model this page represents (see [Pageable](/reference/concerns/pageable))
+- `has_many :versions` → [PageVersion](/reference/models/page-version)
+- `has_many :paths` and `belongs_to :current_path` → [PagePath](/reference/models/page-path)
+- `has_many :menu_nodes, as: :linkable` → [MenuNode](/reference/models/menu-node)
+
+## Validations & scopes
+
+- `title` presence; `slug` presence (unless root) and uniqueness within the parent
+- `alpha_ordered` — orders by translated title in the current locale
+
+## Notable methods
+
+| Method | Returns |
+| --- | --- |
+| `full_path` | the page's current URL path |
+| `find_at_full_path(path)` | class method — page lookup by path |
+| `parsed_content` / `formatted_content` / `content_text` | ProseMirror content as hash / HTML / plain text |
+| `current_version` / `current_content` / `current_image` | versioned content accessors |
+| `seo_values` / `meta_tags` | SEO metadata with fallbacks |
+| `fragments` | the [fragments](/reference/models/fragment) attached to this page key |

data/docs/reference/models/tag.md

@@ -0,0 +1,41 @@
+# Tag, TagCategory & Tagging
+
+The taxonomy models, installed by the [taxonomies generator](/reference/generators/taxonomies). Make any model taggable with the [Taggable](/reference/concerns/taggable) concern.
+
+## Tag
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `key` | string | required, unique within its category |
+| `name` | string | required display name |
+| `category_id` | bigint | optional [TagCategory](#tagcategory) |
+| `position` | integer | ordering within the category |
+| `taggings_count` | integer | counter cache |
+
+- `belongs_to :category`, `has_many :taggings`, `has_many :taggables, through: :taggings`
+- Scopes: `ordered`, `in_category(key)`, `in_categories(keys)`
+
+## TagCategory
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `key` | string | required, unique |
+| `name` | string | required display name |
+| `position` | integer | ordering |
+| `tags_count` | integer | counter cache |
+
+- `has_many :tags` (ordered)
+- Scopes: `ordered`, `with_tags`
+
+## Tagging
+
+The polymorphic join between a `Tag` and any taggable record, unique per (`taggable`, `tag`) pair, with counter caches on both sides.
+
+```ruby
+class Article < ApplicationRecord
+  include Trek::Taggable
+end
+
+article.tags << Tag.in_category("topics").first
+article.tag_names # => ["Ruby"]
+```

data/docs/reference/models/user.md

@@ -0,0 +1,65 @@
+# User
+
+The host application's `User` model, into which Trek injects authentication (Sorcery), roles, theme & locale preferences and the invitation workflow.
+
+## Columns added by Trek
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `name` | string | display name |
+| `role` | integer | enum, default `guest` |
+| `theme` | integer | enum, default `auto` |
+| `locale` | string | admin UI language |
+
+Plus the Sorcery authentication columns (`email`, `crypted_password`, reset tokens…).
+
+## Roles
+
+`Trek::Users::Roles` defines the role enum and access levels:
+
+```ruby
+enum :role, { admin: 5, editor: 4, user: 3, reader: 2, guest: 1 }, default: "guest"
+```
+
+- `privileged?` — `true` for `admin` and `editor`; this is what the default [policies](/reference/policies) check
+- `User.human_roles` — translated role names for form selects
+
+## Themes
+
+`Trek::Users::Themes` lets each user pick the admin theme:
+
+```ruby
+enum :theme, { auto: 0, light: 1, dark: 2 }, default: "auto"
+```
+
+`User.human_themes` returns translated theme names.
+
+## Locales
+
+`Trek::Users::Locales` provides `User.human_locales` — the available admin UI languages with translated labels, sourced from `I18n.available_locales`.
+
+## Invitations
+
+`Trek::Users::Invitable` adds a transient `send_invite` flag: when set on creation, the user receives an invitation email with a password-reset link.
+
+```ruby
+User.create(email: "new@example.com", role: :editor, send_invite: true)
+```
+
+## Validations
+
+`Trek::Users::Validations` enforces:
+
+- `email` — presence, uniqueness, valid format
+- `password` — minimum 8 characters (on creation or password change)
+
+## Scopes
+
+`Trek::Users::Scopes` adds `User.ordered` — alphabetical by name, then email.
+
+## Form models
+
+Two non-persisted `ActiveModel::Model` companions handle the auth flows:
+
+- **`Trek::UserSession`** — `email` + `password`, used by the login form
+- **`Trek::UserPasswordReset`** — `email`, looks up the `user` to send a reset link to

data/docs/reference/policies.md

@@ -0,0 +1,30 @@
+# Policies
+
+Authorization relies on [ActionPolicy](https://actionpolicy.evilmartians.io). Trek provides `Trek::ApplicationPolicy`, `Trek::ResourcePolicy` and policies for its own models (`PagePolicy`, `FragmentPolicy`, `UserPolicy`).
+
+Scaffolded policies inherit from `Trek::ResourcePolicy` and control access per [role](/reference/models/user#roles):
+
+```ruby
+module Admin
+  class BookPolicy < Trek::ResourcePolicy
+    def index? = user.privileged?
+    def create? = user.privileged?
+    def manage? = user.privileged?
+    def destroy? = user.privileged?
+
+    def permitted_attributes
+      user.privileged? ? %i[title intro] : []
+    end
+
+    relation_scope do |relation|
+      next relation if user.privileged?
+
+      relation.none
+    end
+  end
+end
+```
+
+- `permitted_attributes` doubles as strong parameters: `Trek::ResourceController` only permits what the policy allows for the current user.
+- `relation_scope` filters index queries per role.
+- `user.privileged?` is true for the `admin` and `editor` roles.

data/docs/reference/uploaders.md

@@ -0,0 +1,19 @@
+# Uploaders
+
+File uploads are handled by [Shrine](https://shrinerb.com), with Uppy on the front-end:
+
+- `ImageUploader` — base image uploader
+- `RecordImageUploader` — attach an image to any record: `include RecordImageUploader::Attachment(:image)`
+- `ModelImageUploader` — model-level image uploader (used by content editor images)
+
+## Storage
+
+Configured per environment in the generated Shrine initializer (`config/initializers/shrine.rb`):
+
+| Environment | Storage |
+| --- | --- |
+| production | S3 (via the [`S3_*` ENV variables](/reference/environment-variables)) |
+| development | local filesystem (`public/uploads/`) |
+| test | in-memory |
+
+Image processing uses libvips, blurhash placeholders are generated for progressive loading, and direct uploads go through the Shrine `upload_endpoint` (20 MB max).

data/docs/what-is-trek.md

@@ -0,0 +1,37 @@
+# What's Trek?
+
+Trek is a modern content management & back-office system for Ruby on Rails, built by [Etamin Studio](https://etamin.studio). It is designed to get you started fast with useful conventions, then let you customize the back-office to your project's needs.
+
+Trek ships as a Rails engine (a gem plus an NPM package) that integrates into your own Rails application. Unlike hosted CMSs, your content lives in your database, your models stay plain Active Record, and everything remains customizable with regular Rails code.
+
+## What you get
+
+- **A complete admin panel** — layout, navigation, search, pagination, light & dark themes, all built with [ViewComponent](https://viewcomponent.org), [Stimulus](https://stimulus.hotwired.dev) and [Turbo](https://turbo.hotwired.dev).
+- **Pages** — hierarchical, translatable pages with version history, SEO metadata and stable, redirect-aware URL paths.
+- **Fragments** — reusable chunks of content (a footer text, a hero tagline…) editable from the admin and usable anywhere in your views.
+- **A rich text editor** — based on [Tiptap](https://tiptap.dev), with image uploads (Uppy), link insertion and content stored as structured ProseMirror JSON.
+- **Authentication & authorization** — [Sorcery](https://github.com/Sorcery/sorcery)-based sign in, password resets, invitations, and [ActionPolicy](https://actionpolicy.evilmartians.io) policies with `admin`, `editor`, `user`, `reader` and `guest` roles.
+- **Internationalization** — content translations with [Mobility](https://github.com/shioyama/mobility), locale management with [i18n-tasks](https://github.com/glebm/i18n-tasks), and optional automatic translation through DeepL.
+- **File uploads** — [Shrine](https://shrinerb.com)-backed attachments with S3 or local storage, image processing via libvips, and blurhash placeholders.
+- **Generators** — an installer that sets up everything above, and a scaffold generator that creates a full admin panel for any model in one command.
+
+## Philosophy
+
+Trek follows the Rails way:
+
+- **Convention over configuration.** The installer makes opinionated choices (PostgreSQL, Slim, esbuild, PostCSS, RSpec, Standard…) so you don't have to. Every choice can be revisited afterwards — the generated code lives in your application.
+- **Code generation over runtime magic.** Models like `User`, `Page` or `Fragment` are generated into your app with their concerns included, rather than hidden inside the engine. You can read them, edit them, and remove what you don't need.
+- **Progressive customization.** Start with the defaults, then override views, components, policies or styles as your project grows.
+
+## Requirements
+
+| Dependency | Version |
+| --- | --- |
+| Ruby | 3.1+ |
+| Rails | 7.0+ |
+| PostgreSQL | 12+ |
+| Node | 20+ |
+| Yarn | 3.x |
+| libvips | — |
+
+Ready to try it? Head over to the [quick start](/getting-started).

data/esbuild.config.js

@@ -7,7 +7,9 @@ if (process.env.NODE_ENV === undefined) {
   process.env.NODE_ENV = process.env.RAILS_ENV || "development";
 }
 
-let config = esbuild.build({
+const watch = process.argv.includes("--watch");
+
+const options = {
   plugins: [
     rails(),
     postCssPlugin({
@@ -17,8 +19,7 @@ let config = esbuild.build({
   entryPoints: glob("app/javascript/*.*"),
   bundle: true,
   platform: "browser",
-  watch: process.argv.includes("--watch"),
-  sourcemap: !process.argv.includes("--watch"),
+  sourcemap: !watch,
   outdir: "app/assets/builds",
   loader: {
     ".png": "file",
@@ -28,9 +29,11 @@ let config = esbuild.build({
   },
   logLevel: "debug",
   minify: process.env.NODE_ENV === "production",
-  define: { DEBUG: process.env.NODE_ENV !== "production" },
-});
+  define: { DEBUG: JSON.stringify(process.env.NODE_ENV !== "production") },
+};
 
-if (!process.argv.includes("--watch")) {
-  config.catch(() => process.exit(1));
+if (watch) {
+  esbuild.context(options).then((ctx) => ctx.watch());
+} else {
+  esbuild.build(options).catch(() => process.exit(1));
 }

data/lib/trek/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Trek
-  VERSION = "0.1.21"
+  VERSION = "0.1.22"
 end

data/netlify.toml

@@ -0,0 +1,4 @@
+# Node version is read from .node-version
+[build]
+  command = "yarn docs:build"
+  publish = "docs/.vitepress/dist"

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etaminstudio/trek",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "A modern CMS for Ruby on Rails",
   "main": "app/javascript/trek.js",
   "repository": {
@@ -30,8 +30,7 @@
     "tom-select": "^2.2.2"
   },
   "devDependencies": {
-    "esbuild": "^0.15.18",
-    "esbuild-plugin-import-glob": "^0.1.1",
+    "esbuild": "^0.28.0",
     "esbuild-rails": "^1.0.7",
     "esbuild-style-plugin": "^1.6.3",
     "eslint": "^8.49.0",
@@ -48,7 +47,13 @@
     "prettier": "2.8.8",
     "stylelint": "^15.11.0",
     "stylelint-config-standard": "^31.0.0",
-    "stylelint-order": "^6.0.4"
+    "stylelint-order": "^6.0.4",
+    "vitepress": "^1.6.4"
   },
-  "packageManager": "yarn@3.8.0"
+  "packageManager": "yarn@3.8.0",
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  }
 }

data/renovate.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["local>devops/renovate-runner"]
+}