Block Library ![rw-book-cover](https://make.wordpress.org/core/files/2023/07/image-2.png) ## Metadata - Author: [[Make WordPress Core]] - Full Title: Block Library - Category: #articles - Document Note: --- tags: - #wordpress - #gutenberg - #block-library - #open-source - #contributor-experience - #permissions - #patterns - #theme-json - #developer-experience - #metadata Author: Make WordPress Core Source: Make WordPress Core (website) Reference: https://make.wordpress.org/core/2023/07/10/block-library/ date created: {{date:YYYY-MM-DD}} {{time:HH:mm}} --- # Title: Block Library — organizing, permissions, patterns, and APIs for Phase 3 ## Table of Contents: - [🧭 Introduction](#-introduction) - [🔐 Permissions and Roles](#-permissions-and-roles) - [⚙️ Auto-insert and Block API flows](#️-auto-insert-and-block-api-flows) - [🧩 Blocks + Meta Fields + Custom Post Types](#-blocks--meta-fields--custom-post-types) - [🗂️ Block Directory & Installation UX](#️-block-directory--installation-ux) - [🏷️ Pattern Management & Partial Sync](#️-pattern-management--partial-sync) - [🧱 theme.json Composability & Partials](#-themejson-composability--partials) - [🧾 Scope (Actionable Task List)](#-scope-actionable-task-list) - [🔗 References](#-references) ### References: - Make WordPress Core: Block Library — https://make.wordpress.org/core/2023/07/10/block-library/ ## 📝 Summary: The piece outlines next steps to evolve WordPress’s Block Library now that blocks can model entire sites. It proposes sitewide block management outside editors; more granular permissions per role and per block capability; developer hooks for auto-inserting blocks; stronger ties between blocks, post formats, CPTs, and meta fields; improved install/repair flows for third‑party blocks; richer pattern management (including categories and “partially synced patterns”); and deeper application of theme.json composability and partials for role-based and template-scoped control. Key aims: unify existing but hidden capabilities into user-facing workflows, strengthen governance (permissions), streamline discovery/installation, and bridge block attributes to structured data—all within an editor-first, extensible architecture. ## 📖 Main Content: - 🧭 Introduction - With blocks representing entire sites, users need organization and controls beyond the editors: enable/disable blocks globally and align defaults across post formats and post types. - The post notes an implicit system where default post format can pre-select an initial block (e.g., Image), suggesting a clearer UI to set default blocks per post type and connect to “quick post” workflows in the dashboard. - 🔐 Permissions and Roles - Administrators should define which blocks or capabilities are available to different roles. The composable nature of theme.json can scope tools/settings per role (e.g., an author-specific configuration). - ⚙️ Auto-insert and Block API flows - Introduce auto-insert mechanisms so plugins can add blocks to a site’s block tree in ways that respect user control, enabling opinionated experiences without overriding users. - 🧩 Blocks + Meta Fields + Custom Post Types - Formalize connections between block attributes and meta fields so CPTs can use patterns whose blocks map attributes to custom fields rather than post_content—all configured within the block editor UI. - 🗂️ Block Directory & Installation UX - Improve installation, missing block handling, reinstallation, and visualization—especially when large plugins bundle many blocks or when themes/patterns reference third‑party blocks. - 🏷️ Pattern Management & Partial Sync - Manage categories for saved patterns and expose additional pattern APIs (block type/parent dependencies). “Partially synced patterns” let layout and styles remain global while content is editable locally. - 🧱 theme.json Composability & Partials - Apply theme.json partials across groups of blocks, templates, parts, and patterns. Explore full settings objects per user role for granular, systematic control over tools, styles, and capabilities. ### 🗒️ Notes - Global block management - Add a sitewide interface (near Plugins) to enable/disable blocks outside the editor. - Clarifies distinction between user preferences vs. site governance. - Defaults and content creation flows - Make default block selection per post type visible and configurable. - Connect with dashboard “quick post” to streamline publishing flows. - Permissions and capabilities - Role-based exposure of blocks and their tools (lock, style controls, transforms). - Leverage theme.json composability for per-role settings layers. - Developer hooks & auto-insert - APIs to insert blocks automatically in templates/parts with user overrides respected. - Well-defined lifecycle so plugins can augment sites predictably. - Blocks ↔ meta fields - Map block attributes to meta for structured data, especially in CPTs. - Admins configure mapping in-editor; avoids custom UIs for meta management. - Directory & dependency flows - Better UX when themes/patterns require third-party blocks. - Clear visualization of which plugin introduced which blocks; repair missing types. - Patterns - Categorize saved patterns for discovery and reuse. - Expose type and parent dependencies; support partially synced content. - theme.json partials - Apply partials to specific scopes (templates/parts/patterns). - Explore per-role theme.json to tailor editing capabilities. ## 📖 References: - Make WordPress Core: Block Library — https://make.wordpress.org/core/2023/07/10/block-library/ ## 🗣️ Paraphrase: - Original idea: “There’s code built in that tries to coordinate what initial block to show… if the default format was Image a user would see an image block placeholder… This kind of customization is currently a bit obscure and could be more powerful… It should also connect with other workflows like ‘quick post’…” - Paraphrase: WordPress already attempts to choose an initial block based on defaults—like showing an Image block when the post format is Image—but this behavior is hidden and limited. Elevating it into a configurable feature, and tying it into quick-post experiences, would make starting content more intuitive across post types. - Original idea: “Introduce an auto-insert mechanism so that plugins can better interact with the site document (and block trees) in a way that respects user control.” - Paraphrase: Provide APIs for plugins to place blocks automatically within templates or content structures, while ensuring users retain authority to review, adjust, or disable those insertions. ## 📰 Newsletter: This week in WordPress, we’re leveling up the Block Library. With blocks now powering full sites, the roadmap emphasizes governance and great defaults: think role-based permissions via composable theme.json, a global screen to enable/disable blocks, and developer-friendly auto-insert hooks that still respect user choice. Patterns also get serious upgrades—categorization, dependency metadata, and “partially synced” designs where styles/layout stay global but content remains yours. For structured content fans, block attributes ↔ meta field mapping is on the horizon, letting CPTs use patterns that write to meta instead of post_content, all from the editor. If your theme or patterns rely on third-party blocks, better install/missing-block flows are coming too. Dive into the details on Make Core: Block Library (Make WordPress Core: Block Library). Bonus tip: start drafting role-based theme.json experiments today to future-proof your editing experience. ## ✅ Action Items: Prompt for aligning this article with your Developer Advocate and OSPO trajectory: - Positioning: Explain how global block management and role-based permissions strengthen contributor workflows, editorial governance, and enterprise adoption—key to sustainable open-source funding narratives. - Education: Outline a curriculum module for teaching theme.json composability, role-scoped capabilities, and safe auto-insert APIs to new contributors and agency teams. - Community: Propose contributor onboarding tasks around pattern categorization, dependency handling, and missing block repair, highlighting mentorship paths and transparent decision-making. - OSPO-readiness: Map these Block Library initiatives to OSPO pillars—policy (permissions), process (re - Document Tags: [[gutenberg]] [[phase 3]] [[post formats]] [[wordpress]] - Summary: The Block Library is part of the Phase 3: Collaboration roadmap for WordPress. The goal is to improve the organization, listing, and installation of blocks for users. This includes allowing the disabling of blocks globally across a site and connecting functionalities such as single blocks, post formats, and custom post types. The Block Library also aims to introduce more robust permission handling, auto-insert mechanisms for plugins, and a connection between blocks and meta fields. Additionally, improvements are needed in installing blocks from the directory, handling missing block types, and visualizing blocks introduced by larger plugins. Various tasks and API integrations are being developed to enhance the block management experience. Users are encouraged to join the conversation and provide feedback on improving block workflows. - URL: https://make.wordpress.org/core/2023/07/10/block-library/ This is part of the **Phase 3: Collaboration** roadmap. The main projects are [Real-Time Collaboration](https://make.wordpress.org/core/2023/07/03/real-time-collaboration/), [Workflows](https://make.wordpress.org/core/2023/07/04/workflows/), [Revisions](https://make.wordpress.org/core/2023/07/05/revisions/), [Media Library](https://make.wordpress.org/core/2023/07/07/media-library/), [Block Library](https://make.wordpress.org/core/2023/07/10/block-library/), and [Admin Design](https://make.wordpress.org/core/2023/07/12/admin-design/). #### Introduction Now that blocks are able to model and express an entire site, it’s important to improve the way they can be organized, listed, and installed by users. The overall goal is to improve how block management works outside the editors — for example, by allowing the disabling of blocks globally across a site, not just as user preferences. [![Wall of block icons](https://make.wordpress.org/core/files/2023/07/image-2.png)](https://make.wordpress.org/core/files/2023/07/image-2.png) We should connect functionalities that might already exist but are not fully developed as user features yet. For example, the relationship between single blocks, post formats, and custom post types. There’s code built in that tries to coordinate what initial block to show on the editor canvas by checking what’s the default post format (*paragraph* for standard posts); if the default format was *Image* a user would see an image block placeholder when creating a new post instead of an empty text prompt. This kind of customization is currently a bit obscure and could be more powerful if it allowed to more easily configure default block type across post types. It should also connect with other workflows like “quick post” interfaces in the dashboard. It also means introducing more robust permission handling across the various capabilities (block registration, locking, etc) so administrators can define what blocks are available for different user roles (or even what capabilities of individual blocks are to be exposed). The fact that `theme.json` files are inherently composable should allow for more granular handlings of capabilities in a systematic way. For example, consider a fictional `author.theme.json` that sets, disables, and controls what tools and settings are available for authors over the root config file. There are a couple important [block API items](https://github.com/WordPress/gutenberg/issues/41236) to list that can have consequences on user flows as well. One example is to introduce an auto-insert mechanism so that plugins can better interact with the site document (and block trees) in a way that respects user control. Furthermore, as part of the ongoing work on patterns, it’s time to start formalizing a [connection between blocks and meta fields](https://github.com/WordPress/gutenberg/issues/51373) to empower building flexibility while retaining user clarity. For example, it should be possible for an administrator to set up a custom post type, powered by a block pattern, where each individual block has content attributes connected to a specific meta field rather than post content. All could be accomplished within the block editor interface. Finally, it’s also important to improve how installing blocks from the directory works, how we handle missing block types and reinstallation, how themes and patterns could reference third party blocks, etc. This also implies better visualizations of blocks introduced by larger plugins. #### Scope This is a summary of the broad tasks we need to look into: * Add a section next to, or under, *plugins* to manage blocks globally. This means expanding the current block manager to allow enabling and disabling blocks across a site. * Introduce more robust permission handling so administrators can define what blocks are available for different user roles. * Create auto-insert hooks and API flows for block types. This is a developer tool with user flow implications. * Improve the mechanics of the block directory with better visualization of blocks bundled in plugins and better flows for themes and patterns using third party blocks on templates. * Develop API integrations for mapping attributes to custom fields using the editor interface. The idea being blocks can provide a native UI for managing and introducing meta data through its attributes layer. * Allow managing categories for saved patterns. Expose other pattern APIs, like block type or parent dependencies in the user flows. * Develop the concept of “partially synced patterns”. These allows the design layout and the style properties to remain global while the content can be locally customized. * Extensive application of theme.json partials on groups of blocks (control settings and styles on specific templates, parts, patterns). Explore full `theme.json` settings objects on a per user role. #### Get Involved! Join the conversation if you have thoughts or feedback about ways to improve the workflows around blocks., Block Library, Make WordPress Core, 01h5jnbnqrcvqe765cb8fk174a.