PHPackages amazingbv/statamic-gutenberg - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. amazingbv/statamic-gutenberg ActiveLibrary amazingbv/statamic-gutenberg ============================ Block editor addon for Statamic. 1.1.0(1mo ago)042GPL-2.0-onlyPHP Since Jul 6Pushed 1mo agoCompare [ Source](https://github.com/AmazingBV/statamic-gutenberg)[ Packagist](https://packagist.org/packages/amazingbv/statamic-gutenberg)[ RSS](/packages/amazingbv-statamic-gutenberg/feed)WikiDiscussions master Synced 1w ago READMEChangelog (4)Dependencies (4)Versions (7)Used By (0) Block Editor for Statamic ========================= [](#block-editor-for-statamic) A Statamic addon for editing and rendering WordPress-compatible block content inside a Laravel + Statamic installation. The addon adds a `gutenberg` fieldtype to the Statamic Control Panel. Editors open a full-size Block Editor overlay from an entry, edit Gutenberg blocks, use Statamic Assets for media, and save the result as normal Gutenberg serialized HTML: ``` Example content ``` On the frontend the addon parses that saved HTML and renders supported blocks through Blade mappings, sanitized static block HTML, synced patterns, and project-local custom blocks. What It Does ------------ [](#what-it-does) - Adds the `gutenberg` fieldtype to Statamic. - Stores content in WordPress-compatible serialized block HTML. - Opens the editor as a full-size overlay over Statamic, while keeping the Statamic top bar and sidebar visible. - Provides Statamic Asset browsing and uploading for image, cover, audio, file, video, gallery, and media/text blocks. - Supports the standard Gutenberg inserter, block toolbar, inspector, patterns, reusable/synced patterns, alignment controls, text colors, theme palettes, font sizes, spacing, and layout widths where supported by the bundled blocks. - Renders frontend block output through `{{ content }}` augmentation or through the `Gutenberg` facade. - Provides frontend tags for the required block styles and scripts. - Loads optional project-local `theme.json` settings and styles. - Loads optional project-local icon definitions for the Icon block. - Loads optional project-local custom blocks from WordPress-compatible `block.json` folders. - Provides optional Statamic-managed Patterns through a collection and taxonomy. The addon is not a full WordPress runtime. It uses WordPress block editor packages in the Control Panel, but media, patterns, rendering, and custom block assets are handled by Laravel and Statamic. Content Field, Not An Entry Editor ---------------------------------- [](#content-field-not-an-entry-editor) Block Editor for Statamic is a body-content fieldtype. It does not replace the Statamic entry editor or move entry metadata into the Block Editor. Keep the title, slug, publication status, date, taxonomies, SEO fields, revisions, and separate cover fields in Statamic. A practical blueprint keeps the title and body content in the **Main** tab and places supporting metadata in Statamic's **Sidebar** or dedicated SEO tabs: ``` tabs: main: display: Main sections: - fields: - handle: title field: type: text required: true - handle: content field: type: gutenberg display: Body content sidebar: display: Sidebar sections: - fields: - handle: topics field: type: terms taxonomies: - topics - handle: cover_image field: type: assets container: assets max_files: 1 ``` Statamic continues to provide slug, date, status, revisions, permissions, and publishing controls around that blueprint. Render the entry title in the Statamic template, or add a Heading block when the title should be part of the body content. The addon does not automatically add an entry title above the Block Editor canvas. Requirements ------------ [](#requirements) - Laravel + Statamic 6 project. - PHP and Composer compatible with the host Statamic project. - A Statamic asset container, by default `assets`. Installation In A Statamic Project ---------------------------------- [](#installation-in-a-statamic-project) Install the addon from the root of your Laravel + Statamic project: ``` cd /path/to/laravel-statamic-project composer require amazingbv/statamic-gutenberg ``` Publish the addon config and Control Panel assets, then clear the application cache: ``` php artisan vendor:publish --tag=statamic-gutenberg --force php artisan optimize:clear ``` The addon should now appear in Statamic as the `gutenberg` fieldtype. The distributed package already contains the built editor and frontend assets, so Node.js is not required to install or use the addon. Updating The Addon In A Project ------------------------------- [](#updating-the-addon-in-a-project) Update the package and refresh the published assets from the Statamic project root: ``` cd /path/to/laravel-statamic-project composer update amazingbv/statamic-gutenberg php artisan vendor:publish --tag=statamic-gutenberg --force php artisan optimize:clear ``` Basic Field Usage ----------------- [](#basic-field-usage) Add a `gutenberg` field to a collection blueprint: ``` tabs: main: display: Main sections: - fields: - handle: title field: type: text required: true - handle: content field: type: gutenberg display: Content assets_container: assets render_mode: blade allow_unknown_blocks: false sanitize_html: true ``` Per field you can override: - `allowed_blocks`: block names that may be inserted, for example `core/paragraph`, `core/heading`, `core/image`, or a project custom block. - `assets_container`: the Statamic Asset container used by the media picker and upload flow. - `render_mode`: `blade` for parsed block rendering, or `raw` for sanitized saved HTML. - `allow_unknown_blocks`: whether unsupported blocks may render their saved HTML. - `sanitize_html`: whether saved/static HTML is cleaned before output. If a field omits these options, the values from `config/statamic-gutenberg.php` are used. Frontend Usage -------------- [](#frontend-usage) In most Statamic templates, output the augmented field normally: ``` {{ content }} ``` Add the frontend block styles and scripts to the layout: ``` {{ gutenberg:styles }} {{ template_content }} {{ gutenberg:scripts }} ``` Available tags: - `{{ gutenberg }}` or `{{ gutenberg:assets }}` outputs both styles and scripts. - `{{ gutenberg:styles }}` outputs frontend CSS, theme.json CSS, and custom block frontend styles. - `{{ gutenberg:scripts }}` outputs frontend JS and custom block frontend scripts. Use `.sgb-content` around rendered content. It provides the expected WordPress layout behavior for content width, wide/full alignment, grid/flex helpers, block spacing, and frontend interaction hooks. Rendering From PHP ------------------ [](#rendering-from-php) You can render stored Gutenberg content manually with the facade: ``` use Gutenberg; echo Gutenberg::render($entry->get('content')); ``` Register or override a block renderer from a service provider: ``` use Gutenberg; Gutenberg::block('project/notice', [ 'view' => 'blocks.notice', ]); Gutenberg::block('custom/notice', function ($block, string $inner, $renderer): string { return view('blocks.notice', [ 'attrs' => $block->attributes(), 'inner' => $inner, ])->render(); }); ``` Configured Blade views receive: - `$block`: the parsed block object. - `$attrs`: block attributes. - `$inner`: already-rendered inner block HTML as an `HtmlString`. Configuration ------------- [](#configuration) Publish the config with: ``` php artisan vendor:publish --tag=statamic-gutenberg --force ``` The published file is: ``` config/statamic-gutenberg.php ``` Main options: OptionPurpose`allowed_blocks`Global default allowlist for blocks in the editor and renderer.`assets_container`Default Statamic Asset container for media browse/upload.`icons_path`PHP file in the host project with Icon block definitions, defaulting to `resources/vendor/statamic-gutenberg/icons.php`.`theme_json_path`Optional project-local `theme.json` path.`custom_blocks_path`Folder where project-local custom blocks live.`patterns`Collection, taxonomy, and field handles used for Statamic-managed patterns.`icons`Inline icon definitions, useful for small sets or tests.`render_mode``blade` or `raw`.`allow_unknown_blocks`Whether unsupported blocks can render saved HTML.`sanitize_html`Whether rendered static/raw HTML is sanitized.`blocks`PHP renderer mappings for built-in or custom block names.Custom block names discovered from `custom_blocks_path` are automatically added to the editor allowlist. `core/block` is also kept internally available because Gutenberg uses it for synced pattern insertion. Supported Default Blocks ------------------------ [](#supported-default-blocks) The default allowlist is defined in `config/statamic-gutenberg.php`. It includes: ``` core/accordion core/audio core/block core/button core/buttons core/code core/column core/columns core/cover core/details core/embed core/file core/gallery core/group core/heading core/icon core/image core/list core/list-item core/math core/media-text core/more core/nextpage core/paragraph core/preformatted core/pullquote core/quote core/separator core/spacer core/table core/verse core/video ``` Some internal child blocks are also listed where Gutenberg requires them, such as accordion item/panel blocks. You can remove blocks from the global config or override the allowlist per field. Embed Providers --------------- [](#embed-providers) `core/embed` is available for URL embeds, but the add-on intentionally supports only iframe-based video/audio providers that can be rendered safely without loading external provider scripts: - YouTube - Vimeo - Spotify - SoundCloud The editor and frontend both use the same iframe-based provider handling. YouTube and Vimeo are rendered as responsive video embeds. Spotify and SoundCloud are rendered as rich/audio embeds with explicit preview heights, so they stay visible in Gutenberg's sandboxed editor preview as well as on the frontend. Other Gutenberg oEmbed variations, such as X/Twitter, Facebook, Instagram, Reddit, Pinterest, document providers, Maps, and generic rich/social embeds are hidden from the inserter. If an unsupported URL is pasted into `core/embed`, the editor uses Gutenberg's normal failed-embed flow and the frontend falls back to the sanitized saved URL/HTML instead of rendering a custom iframe. Block Supports -------------- [](#block-supports) The bundled editor registers Gutenberg's native support controls for the default allowlisted blocks. Supported controls include wide/full alignment, anchors, custom classes, text/background/link colors, gradients, typography, spacing, borders, dimensions, shadows, background images, and layout controls where they make sense for that block type. The frontend renderer reads the same saved block attributes and applies matching classes/styles through the addon wrapper helpers. Static saved markup is also enriched from the block comment attributes when needed, so editor and frontend output stay aligned even when a block's saved HTML does not already contain all wrapper classes or inline styles. Project-local custom blocks should declare their own WordPress-compatible `supports` in `block.json`. The addon keeps those declarations authoritative and only adds the attributes required for Gutenberg to persist the selected support values, such as `style`, `align`, `textColor`, `backgroundColor`, `fontSize`, `fontFamily`, and `borderColor`. Media And Assets ---------------- [](#media-and-assets) The editor uses Statamic Assets, not WordPress media storage. The addon exposes a small WordPress-compatible media adapter internally so Gutenberg components that request `/wp/v2/media` can list, search, upload, read, and update Statamic assets without requiring a real WordPress media library. The media picker is opened from supported media blocks and shows a file browser for Statamic asset containers the current Control Panel user may view. Search can run across all visible containers. Uploads default to the field's configured asset container, or to the container currently selected in the picker, and go through Statamic authorization, container validation rules, safe filenames, and type checks. The detail panel writes attachment metadata changes for alt text, title, and caption back to the Statamic asset metadata. Existing block attributes still store a `statamicId` alongside Gutenberg's numeric attachment id, so saved content can be reopened without losing the Statamic asset identity. Block type filters: - Image blocks show images and SVGs. - Cover and Media & Text show images, SVGs, and videos. - Audio blocks show audio. - Video blocks show video. - File blocks allow files. The v1 media adapter intentionally does not implement destructive WordPress media operations or image editing features such as crop, rotate, and replace original. Use Statamic's normal Assets screen for those workflows. Configure the default container: ``` // config/statamic-gutenberg.php 'assets_container' => 'assets', ``` Override it per field if a specific collection should use another container: ``` content: type: gutenberg assets_container: downloads ``` Editor And Live Preview Workflow -------------------------------- [](#editor-and-live-preview-workflow) From a normal entry form, the field opens as a full-size body-content editor while Statamic's top bar and navigation stay available. When opened inside Statamic Live Preview, the addon uses an integrated split view. The Block Editor stays inside the resizable editor pane and the preview iframe remains visible beside it. List View starts closed, and compact panes show List View and Block settings as temporary drawers. - **Apply and save** applies the block content and requests an entry save. - **Apply and close** applies the content and closes the editor. - **Apply** applies the content and refreshes Live Preview without saving the entry. - **Close** discards unapplied changes after confirmation. Theme JSON ---------- [](#theme-json) Place an optional `theme.json` in the host Statamic project: ``` cd /path/to/laravel-statamic-project mkdir -p resources/vendor/statamic-gutenberg $EDITOR resources/vendor/statamic-gutenberg/theme.json ``` Default path: ``` resources/vendor/statamic-gutenberg/theme.json ``` If the file exists, the addon loads its settings into the Gutenberg editor and generates scoped CSS for the editor and frontend. If the file is missing, the addon does nothing extra. Common things to customize in `theme.json`: - `settings.color.palette` - `settings.color.gradients` - `settings.typography.fontSizes` - `settings.typography.fontFamilies` - `settings.spacing.spacingSizes` - `settings.spacing.units` - `settings.layout.contentSize` - `settings.layout.wideSize` - `styles` - `styles.elements` - `styles.blocks` - `styles.css` Example: ``` { "version": 3, "settings": { "layout": { "contentSize": "720px", "wideSize": "1180px" }, "color": { "palette": [ { "name": "Brand", "slug": "brand", "color": "#003f5c" }, { "name": "Accent", "slug": "accent", "color": "#ef5675" } ] }, "typography": { "fontSizes": [ { "name": "Small", "slug": "small", "size": "0.875rem" }, { "name": "Large", "slug": "large", "size": "2rem" } ] } }, "styles": { "elements": { "heading": { "typography": { "fontWeight": "700" } } } } } ``` ### Fonts And Theme Files [](#fonts-and-theme-files) Files referenced from `theme.json` can live next to that file, for example: ``` resources/vendor/statamic-gutenberg/theme.json resources/vendor/statamic-gutenberg/assets/fonts/proxima/proxima-400.woff2 ``` Reference them with WordPress-style `file:./...` URLs: ``` { "settings": { "typography": { "fontFamilies": [ { "name": "Proxima", "slug": "proxima", "fontFamily": "\"Proxima\", sans-serif", "fontFace": [ { "fontFamily": "\"Proxima\"", "fontStyle": "normal", "fontWeight": "400", "fontDisplay": "swap", "src": [ "file:./assets/fonts/proxima/proxima-400.woff2" ] } ] } ] } } } ``` Variable fonts split across Unicode subset files can use multiple `fontFace`records with the same family, style, and weight range: ``` { "version": 3, "settings": { "typography": { "fontFamilies": [ { "name": "Project Mono", "slug": "project-mono", "fontFamily": "\"Project Mono\", monospace", "fontFace": [ { "fontFamily": "\"Project Mono\"", "fontStyle": "normal", "fontWeight": "100 900", "fontDisplay": "swap", "unicodeRange": "U+0000-00FF", "src": [ "file:./assets/fonts/project-mono-latin.woff2" ] }, { "fontFamily": "\"Project Mono\"", "fontStyle": "normal", "fontWeight": "100 900", "fontDisplay": "swap", "unicodeRange": "U+0100-024F, U+1E00-1EFF", "src": [ "file:./assets/fonts/project-mono-extended.woff2" ] } ] } ] } } } ``` Supported `fontFace` descriptors are `ascentOverride`, `descentOverride`, `fontDisplay`, `fontFamily`, `fontFeatureSettings`, `fontStyle`, `fontStretch`, `fontVariationSettings`, `fontWeight`, `lineGapOverride`, `sizeAdjust`, `src`, and `unicodeRange`. The addon serves those files through: ``` /vendor/statamic-gutenberg/theme/... ``` Block Styles ------------ [](#block-styles) Block styles are native Gutenberg style variations. They appear in the standard Gutenberg Styles UI for the selected block. When an editor chooses a style, the saved block receives WordPress' normal `is-style-{name}` class. The addon renders the matching CSS in both the editor and frontend, scoped to the Block Editor roots. The default project-local file path is: ``` resources/vendor/statamic-gutenberg/block-styles.php ``` Create it in the host Statamic project: ``` cd /path/to/laravel-statamic-project mkdir -p resources/vendor/statamic-gutenberg $EDITOR resources/vendor/statamic-gutenberg/block-styles.php ``` Example file: ```