Expand description
rustango-cms — a multi-tenant, page-tree CMS built on rustango.
Pages live in one tenant-scoped cms_page tree (materialized path,
see tree); each page’s kind is a registered PageTypeHandler
with its own extension table, template and admin form. Every read and
write goes through the tenant’s own pool, and the bundled migrations
(see migrations) are tenant-scoped. The same source runs on
PostgreSQL, MySQL 8+ and SQLite.
§Entry points
| Surface | Where |
|---|---|
| Public site (slug resolver + Tera render, feeds, sitemap, forms) | PublicRouter, or the router() / router_at shortcuts |
Editor admin at /cms-admin/ | admin::router, gated by admin::with_login_required; templates via admin::register_templates |
| Page types | #[derive(PageType)] + PageTypeOverrides, or a hand-written PageTypeHandler + register_page_type! |
| StreamField bodies | block — the block::Block trait, #[derive(Block)] or register_block! |
| Reusable content (library / snippets) | library (LibraryTypeHandler, register_library_type!) and snippet |
Headless JSON API under /api/v2/ | api::router / api::router_with |
MCP server for AI agents at mcp::MCP_PREFIX | mcp::router |
| Per-tenant setup — page-type rows, roles, default locale, host seeders (late tenants seed on first request) | ensure_seeded |
| Extension hooks (publish, serve, admin menu, dashboard) | hooks |
§Minimal wiring
ⓘ
use std::sync::Arc;
let mut tera = tera::Tera::new("templates/**/*.html")?;
rustango_cms::admin::register_templates(&mut tera)?;
let tera = Arc::new(tera);
let cms_admin = rustango_cms::admin::with_login_required(
rustango_cms::admin::router(tera.clone()),
"/login",
);
let app = cms_admin
.merge(rustango_cms::api::router())
.merge(rustango_cms::mcp::router(&settings.mcp)) // CSRF-exempt MCP_PREFIX
.merge(rustango_cms::PublicRouter::new(tera).build());
// Hand `app` to `rustango::manage::Cli::new().tenancy().api(app)`
// and call `rustango_cms::ensure_seeded` from its `.seed(..)` hook.admin::router is unauthenticated on its own; always wrap it in
admin::with_login_required.
§Cargo features
| Feature | Effect |
|---|---|
postgres (default), sqlite, mysql | Database backend, forwarded to rustango |
storage_s3 | S3-compatible media storage for media_storage::install_from_env |
cache_cloudflare, cache_varnish, cache_cloudfront, cache_gcp, cache_azure | Front-cache purge backends (cache_invalidate) |
search_elasticsearch | Elasticsearch search backend (search_elasticsearch module) |
avif | AVIF image renditions |
test_utils | rustango’s Tenant::for_test for integration tests |
Re-exports§
pub use view_restriction::RestrictionKind;pub use view_restriction::TypeViewRestriction;pub use category::registered_handlers as registered_taxonomy_handlers;pub use category::Category;pub use category::PageCategory;pub use category::Taxonomy;pub use category::TaxonomyHandler;pub use category::TaxonomyHandlerRegistration;pub use library::ensure_library_type_row;pub use library::find_handler as find_library_handler;pub use library::registered_handlers as registered_library_handlers;pub use library::LibraryType;pub use library::LibraryTypeHandler;pub use library::LibraryTypeHandlerRegistration;pub use library::ListColumn;pub use library::ListColumnKind;pub use locale::Locale;pub use locale_mode::resolve_request_locale;pub use locale_mode::LocaleMode;pub use locale_mode::RequestLocale;pub use media::Media;pub use media::MediaCollection;pub use category_translation::CategoryTranslation;pub use menu_item_translation::MenuItemTranslation;pub use navigation::Menu;pub use navigation::MenuItem;pub use page::Page;pub use page::PageStatus;pub use page_type::all_children;pub use page_type::default_children;pub use page_type::find_handler;pub use page_type::published_children;pub use page_type::registered_handlers;pub use page_type::DisplayField;pub use page_type::ExtensionField;pub use page_type::ExtensionFieldKind;pub use page_type::InlinePanelSpec;pub use page_type::PageTypeHandler;pub use page_type::PageTypeHandlerRegistration;pub use page_type::PageTypeOverrides;pub use page_type::TabSpec;pub use page_view::Accept;pub use page_view::PageViewKind;pub use page_view::PageViewMode;pub use permissions::user_can;pub use permissions::user_can_in_collection;pub use permissions::user_can_matrix;pub use permissions::Action;pub use permissions::CollectionPermission;pub use permissions::PagePermission;pub use redirect::bump_hit_count as bump_redirect_hit_count;pub use redirect::find_for_path as find_redirect_for_path;pub use redirect::Redirect;pub use revision::Revision;pub use snippet::Snippet;pub use theme::emit_css as emit_theme_css;pub use theme::BrandColor;pub use theme::Theme;pub use theme_resolve::resolve_for_page as resolve_theme_for_page;pub use theme_resolve::ResolvedTheme;pub use theme_seed::ensure_themes_seeded;pub use translation::Translation;pub use page_type_model::PageType;pub use render::render;pub use resolver::resolve_path;pub use router::router;pub use router::router_at;pub use router::router_at_cached;pub use router::router_cached;pub use router::PublicRouter;pub use schedule::spawn_schedule_sweeper;pub use seed::ensure_seeded;pub use seed::SeedError;pub use admin::admin_page::find_admin_page;pub use admin::admin_page::registered_admin_pages;pub use admin::admin_page::AdminPageCtx;pub use admin::admin_page::AdminPageHandler;pub use admin::admin_page::AdminPageHandlerRegistration;pub use admin::admin_page::SidebarSection;pub use block::find_block;pub use block::registered_blocks;pub use block::validate_block_registry;pub use block::Block;pub use block::BlockCountConstraint;pub use block::BlockError;pub use block::BlockField;pub use block::BlockFieldMeta;pub use block::BlockRegistration;pub use block::BlockRenderCtx;pub use tree::MaterializedPath;pub use tree::PathError;pub use tree_ops::cascade_url_path_to_descendants;pub use tree_ops::compute_url_path;pub use tree_ops::rebuild_all_url_paths;pub use tree_ops::validate_child_placement;pub use tree_ops::NewPage;pub use tree_ops::TreeError;pub use widget::Widget;pub use widget::WidgetKind;
Modules§
- a11y
- Server-side accessibility heuristics.
- access
- Viewer-aware access helpers for public templates (#members).
- admin
- R-CMS admin section.
- analytics
- Default first-party web analytics (#analytics).
- api
- REST API v2 — public reads plus member login.
- auto_
menu auto_menu(parent_id=…, depth=…)Tera function — an automatic menu built from the page tree.- block
- StreamField — composable body blocks.
- breadcrumbs
- Breadcrumb engine — walks the page tree once and returns an
ordered list of
(title, url, is_current)crumbs. - cache_
azure - Azure CDN purge backend for
crate::cache_invalidate::PageCacheInvalidator. - cache_
cloudflare - Cloudflare-purge backend for
crate::cache_invalidate::PageCacheInvalidator. - cache_
cloudfront - AWS CloudFront invalidator for
crate::cache_invalidate::PageCacheInvalidator. - cache_
gcp - Google Cloud CDN purge backend for
crate::cache_invalidate::PageCacheInvalidator. - cache_
invalidate - Targeted page-cache invalidation hook.
- cache_
varnish - Varnish-purge backend for
crate::cache_invalidate::PageCacheInvalidator. - category
- Categories & taxonomies — hierarchical categorization, built the same way pages are: real migration-tracked models, not a JSON blob or a config file.
- category_
translation - Per-field, per-locale translation overrides for categories.
- children_
filtered children_filtered(...)Tera helper — a page’s live children, filtered and ordered.- collection_
view_ restriction CollectionViewRestriction— gate served media bytes behind a login requirement or group membership check.- comment
- Inline comments on the page editor.
- config
- Process configuration from the environment.
- content_
checks - Extensible content-checks framework.
- date_
filters - Tera date filters — parse stringified dates from extension / form values and re-format them for output, fail-soft on unparseable / null / empty input.
- dismissible
- Per-user persistent banner / announcement dismissals.
- editing_
session - Concurrent-editor tracking.
- embed
- Embed provider discovery + responsive render.
- error_
pages - CMS-editable error pages (404/500/…).
- feed
- Per-page-type RSS 2.0 + Atom 1.0 feeds —
“syndication on demand”, powered by
rustango::syndication. - forms
- Visual Form Builder.
- fragment_
cache - Page-keyed template-fragment caching.
- hooks
- Runtime extension-point registry.
- language_
switcher - Public language-switcher data for templates.
- library
Library— reusable content (renamed from “snippets”).- locale
Locale— per-tenant locale registry.- locale_
mode - How the public router resolves which locale a request is asking for.
- lock
PageLock— best-effort editor lock on acms_pagerow.- macros
- Declarative macro for registering a
PageTypeHandler. - markdown
- Server-side Markdown → HTML rendering for page bodies.
- mcp
- MCP engine — operate the CMS from an AI agent.
- media
Media— per-tenant uploaded files (images + documents).- media_
storage - Pluggable storage backend for CMS media.
- menu_
item_ translation - Per-field, per-locale translation overrides for menu items.
- meta_
tags - Tera helper that emits canonical
<head>meta tags for a page. - metrics
- Content metrics — word count, estimated reading time, and a readability score.
- migrations
- Embed + materialize the bundled CMS migrations.
- mysql_
text - Long content columns on MySQL.
- navigation
Navigation— tenant-managed named menus with nested items.- notification_
pref - Per-user notification preferences.
- notify
- Notifications — one delivery path, many destinations.
- page
Page— the tenant-scopedcms_pagerow every page shares, whatever its type: tree position (path,depth,parent_id), slug andurl_path,PageStatuslifecycle, SEO fields and thepage_type_idthat selects itsPageTypeHandler. Type-specific fields live in the handler’s extension table.- page_
builder - Page-type field builder — UI-defined body schemas.
- page_
log - Per-page audit log.
- page_
snippet_ m2m - Page ↔ Snippet many-to-many relations.
- page_
subscription - Per-user opt-in subscriptions to page publish events.
- page_
tag - Page tag system.
- page_
type - Page types: the
PageTypeHandlertrait every page kind implements, its inventory registry (find_handler,registered_handlers), and the editor-form types the handler returns (ExtensionField,TabSpec,InlinePanelSpec,DisplayField). - page_
type_ model PageType— the per-tenantcms_page_typerow that gives each registeredPageTypeHandlera stable id forcms_page.page_type_id. Rows are upserted byensure_seeded.- page_
url pageurl(id=N)Tera helper — resolve acms_pageid to its public URL at render time.- page_
view - What a page type serves on its public URL, and how
Acceptpicks. - pending_
change - Changes to a live page held for review.
- perf
- Request timing instrumentation — opt-in, off by default.
- permissions
- Per-page permission engine.
- preview_
token - Signed preview tokens for decoupled / headless frontends.
- preview_
url - Preview a draft in a decoupled renderer.
- redirect
- Editor-managed 301/302 redirects.
- reference_
index - Generic reference index — "what links here".
- render
- Render a resolved
Pagethrough Tera. - rendition
- Image renditions — resized variants of a
Mediarow served at/__media__/<filter_spec>/<media_id>. - rendition_
route - Public route for serving image renditions.
- resolver
- URL →
Pageresolution. - revision
Revision— versioned snapshots ofcms_pagerows.- richtext
| richtextTera filter —{{ page.body | richtext }}.- robots
/robots.txtfor the public CMS.- routable
routable_page— routable pages. A singlePagerow can serve multiple URL patterns under its canonical url_path.- router
- Public axum router that the host app mounts.
- schedule
- Background driver for scheduled publishing and expiry.
- search
- Database full-text search backend.
- search_
elasticsearch - Elasticsearch full-text
SearchBackend. - search_
promotion - Search query log + editor-pinned results.
- security_
log - Sign-in security log and account lockout (#433).
- seed
- Per-tenant
cms_page_typeseeding. - signing
- Minimal HMAC-SHA256 used across the CMS for short signed tokens (view-restriction grants, signed rendition URLs).
- site
- Sites — one tenant, several hostnames, each with its own root page.
- site_
setting - Per-tenant site settings.
- sitemap
/sitemap.xmlfor the public CMS — adoptsrustango::sitemaps.- snippet
- Library snippets — reusable, non-page content addressable by slug.
- snippet_
render snippet_html(type=…, id=N)Tera helper — per-snippet template rendering.- snippet_
translation - Per-field, per-locale translation overrides for snippets.
- task_
kind - Custom workflow task kinds.
- task_
queue - Pluggable background task queue for CMS heavy work.
- tenant_
templates - Per-tenant template overrides, resolved from disk with fallback to the global set.
- theme
- Visual themes — design tokens stored as data, rendered as CSS
variables:
a
Themeholds surface / semantic colors + typography + radii + shadows;BrandColorrows attach N named brand colors per theme, each emitting its own slug-keyed CSS variable triplet (raw / rgb / contrast) plus an auto-derived 50→950 shade scale. - theme_
resolve - Per-request theme resolution.
- theme_
seed - Bootstrap-time hydration of the six bundled themes + their brand colors into each tenant.
- translation
- Per-field, per-locale translation overrides.
- tree
- Materialized-path encoding for the page tree.
- tree_
build - Turn a flat, parent-linked row set into a nested tree.
- tree_
ops - Tree mutation + read API on top of
Page. - uploaded_
file - Scratch storage for multi-step media uploads.
- urls
- Named URL patterns + Tera helper registration.
- userbar
- On-site editor userbar.
- view_
restriction PageViewRestriction— gate published pages behind a password, a login requirement, or a group membership check.- view_
restriction_ guard - Public-renderer enforcement for
PageViewRestriction. - widget
- Widget descriptors — the single primitive both flat extension
fields (
crate::page_type::ExtensionField) and stream-block fields (crate::block::BlockField::Widget, landing in a later slice) use to describe one form input. - workflow
- Multi-step approval workflows.
- workflow_
mail - Workflow notification helpers.
Macros§
- register_
account_ settings_ panel - register_
admin_ css - Register global admin CSS.
- register_
admin_ js - Register global admin JS.
- register_
admin_ menu_ item - register_
admin_ page - Register a custom admin page. The type must implement
AdminPageHandlerandDefault. Mirrors theregister_page_type!/register_library_type!pattern — drop the macro call anywhere in the crate’s source and the page shows up at/cms-admin/x/<slug>with a sidebar entry in its declared section. - register_
admin_ search_ area - register_
after_ publish_ page - Register an
AfterPublishPagehandler at compile time. - register_
before_ serve_ page - register_
block - Register a
Blockat module-load time. Mirrors theregister_widget!/register_page_type!patterns. - register_
block_ enricher - Register a
BlockEnricherat compile time. - register_
bulk_ action - register_
chooser - Register a generic chooser for a
#[derive(Model)]type. - register_
content_ check - Register a
ContentCheckimplementation. - register_
dashboard_ widget - register_
help_ menu_ item - register_
library_ type - Register a library type at compile time. Pair with a
#[derive(Default)] impl LibraryTypeHandlerblock. Mirrorscrate::register_page_type!. - register_
model_ admin - Register a generic admin for a
#[derive(Model)]type. - register_
notification_ channel - Register a
NotificationChannelso the admin can configure it. - register_
page_ action_ menu_ item - register_
page_ header_ button - register_
page_ listing_ button - register_
page_ type - Submit a
PageTypeHandlerRegistrationfor$tyto the global inventory. - register_
report - Register a
Reportimplementation. - register_
site_ setting - Register a typed schema for a site-settings
scope. - register_
sitemap_ source - Register a
SitemapSource. Pair with aDefaultimpl. - register_
task_ kind - Macro mirror of
crate::register_block!. Hosts call this to publish a customTaskKindinto the runtime registry. - register_
taxonomy - Register a custom taxonomy / category vocabulary. The type must
implement
TaxonomyHandlerandDefault. Mirrorsregister_page_type!— drop the call anywhere in the crate’s source and the vocabulary is synced into acms_taxonomyrow at seed and shows up under the admin Taxonomies section. - register_
tenant_ seeder - Register a
TenantSeederat compile time. - register_
userbar_ item - register_
widget - Register a custom widget at module-load time. Picks up
rustango_cms::inventory(re-exported incrate) so callers don’t need their owninventorydep.
Derive Macros§
- Block
#[derive(Block)]— declarative block definition. Walks#[block(...)]+#[field(widget = …)]attrs to emit theBlocktrait impl +register_block!inventory submission in one go. Coexists with theBlocktrait through Rust’s separate macro / type namespaces (same pattern as#[derive(PageType)]alongsidePageType).#[derive(Block)]— generates therustango_cms::Blocktrait impl from#[block(...)]and#[field(...)]attributes plus a global inventory registration so the block joins the registry at link time.- Page
Type #[derive(PageType)]— declarative page-type definition. Seecrate::page_type::PageTypeOverridesfor the override trait authors implement alongside.#[derive(PageType)]— generates therustango_cms::PageTypeHandlertrait impl from#[page_type(...)]and#[field(...)]attributes plus a global inventory registration so the type is reachable fromrustango_cms::find_handler(type_name).