Block Library  [[3. Resources/Readwise/Full Document Contents/Articles/Block Library|Full Document Contents]] ## Document Notes --- 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]] - [[#🔐 Permissions and Roles]] - [[#⚙️ Auto-insert and Block API flows]] - [[#🧩 Blocks + Meta Fields + Custom Post Types]] - [[#🗂️ Block Directory & Installation UX]] - [[#🏷️ Pattern Management & Partial Sync]] - [[#🧱 theme.json Composability & Partials]] - [[#🧾 Scope (Actionable Task List)]] - [[#🔗 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 > [!note]+ Document Notes > 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 > <!-- deep-read:sections start --> ## 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 (review and governance of auto-insert APIs), people (role-defined experiences), and product (pattern/metadata interoperability). - Equity & inclusion: Describe how role-based tooling and meta-mapping lower barriers for non-technical contributors, improving inclusivity and long-term project health. - Advocacy: Develop a talk track connecting these features to sustainable ecosystem economics (plugin transparency, dependency clarity) and responsible DX/UX. - Measurement: Define KPIs for contributor engagement (PRs on pattern APIs, docs improvements), editor satisfaction (task success rates), and governance adoption (sites using per-role theme.json). Use this as a conference CFP outline, an internal OSPO memo template, or a workshop agenda to merge education with community growth. ## 🧪 Hypotheses: - H1: A global block management screen reduces accidental misuse and support tickets by enabling sitewide governance. - H2: Role-based exposure of block capabilities decreases editor confusion and improves publishing velocity. - H3: Auto-insert APIs increase plugin adoption while maintaining user trust when paired with clear opt-outs. - H4: Mapping block attributes to meta fields improves data quality and interoperability for CPT-heavy sites. - H5: “Partially synced patterns” increase design consistency without sacrificing editorial flexibility. ### 📊 Methodology: - Mixed-methods UX study: task-based usability testing comparing current vs. proposed global block management and role-based setups; measure task completion, SUS, and error rates. - Telemetry (opt-in): capture frequency of missing-block repairs, auto-insert acceptance/overrides, and pattern reuse rates. - A/B rollout in Gutenberg plugin: evaluate impact of pattern categorization and partially synced content on adoption and editing time. - Content modeling audit: compare data integrity and query performance when using meta-mapped blocks vs. post_content storage across representative CPTs. - Contributor analytics: track first-time contributor success and cycle time on Block Library-related issues. ### ❓ Questions: - How should user overrides of auto-inserted blocks persist across template updates? - What is the minimal, privacy-respecting telemetry needed to detect missing-block friction? - How granular should role-based theme.json be before it becomes unmanageable? - What guardrails prevent pattern dependency “lock-in” to specific plugins? - How do we surface block-to-meta mappings clearly in the UI without overwhelming users? ### 🔮 Future Research: - Conflict resolution models for layered theme.json (role + template + site). - Standard schema for pattern dependencies and compatibility ranges. - Editorial policy UX: workflows for requesting/approving block capability changes. - Migration tooling for converting content between post_content and meta-mapped attributes. - API standards for auto-insert lifecycle events and user consent UX. ### 💡 Implications: - Stronger governance may accelerate enterprise adoption and reduce maintenance costs. - Standardized dependency metadata can improve ecosystem transparency and security. - Meta-mapped blocks could enable headless, analytics, and compliance use cases with less custom code. - Partially synced patterns may balance brand consistency with local editorial autonomy. ### 🧠 Learning Styles Assessment: - Readability: Upper-intermediate/advanced practitioner level (assumes familiarity with Gutenberg concepts). - Visual learners - Present: Conceptual structure implied; no diagrams. - Improve: Add diagrams showing data flow (block attr → meta), permission matrices, and theme.json layering. - Aural learners - Present: None. - Improve: Provide audio summary or companion podcast segment. - Verbal learners - Present: Clear conceptual framing and examples (e.g., default Image block). - Improve: Add narrative case studies from agencies/publishers. - Physical (kinesthetic) - Present: None. - Improve: Include hands-on exercises (enable/disable blocks, set role configs, map meta). - Logical (mathematical) - Present: Enumerated scope list; implicit systems thinking. - Improve: Add flowcharts, state diagrams, and dependency graphs. - Social (interpersonal) - Present: Not explicit. - Improve: Link to Make/Core discussions and calls for testing for collaborative learning. - Solitary (intrapersonal) - Present: Concept-dense; supports independent study. - Improve: Add reflection prompts and checklists. - Naturalistic - Present: None. - Improve: Use sustainability analogies around governance and ecosystem health. ### 📊 Accessibility Assessment: - Screen reader compatibility: Core site generally uses semantic HTML; article is text-heavy with headings. - Improve: Ensure any future diagrams include concise alt text and that headings follow a proper hierarchy. - Keyboard navigation: Likely supported via site theme. - Improve: Confirm focus states and skip links; ensure any future interactive examples are keyboard-usable. - Contrast and readability: Typical Make/Core styling is readable. - Improve: Maintain high contrast; support prefers-reduced-motion and scalable fonts. - Text resizing: Site is responsive. - Improve: Verify no layout breakage at 200%+ zoom; ensure code blocks and tables reflow. ### 🌍 DEIB (Diversity, Equity, Inclusion, and Belonging) Assessment: - Cultural relevance: Neutral technical content; lacks diverse perspectives. - Improve: Include case studies from global communities and varying org sizes. - Inclusive language: Generally neutral and clear. - Improve: Define jargon (auto-insert, theme.json partials) with glossaries. - Neurodiversity support: Dense paragraphs. - Improve: More subheadings, bullets, and summaries per section. - Representation: No examples highlighting diverse roles/users. - Improve: Showcase editors, site managers, and contributors from varied backgrounds. - Psychological safety: No contentious topics. - Improve: Invite feedback, provide clear contribution pathways, set expectations for respectful discussion. ### ✅ Logical validity: - Positive reasoning - Causal reasoning: “Blocks model entire sites → need organization and permissions beyond the editor.” Strengthens motivation; could add empirical evidence (support tickets, usability studies). - Logical flow: Moves from problem (hidden/obscure behaviors) to solutions (UI + APIs + governance). Add a decision tree illustrating tradeoffs. - Balanced view: Emphasizes user control in auto-insert features. Could include explicit opt-in/opt-out patterns. - Ethical reasoning: Role-based controls and transparency in dependencies. Improve by articulating privacy safeguards for any telemetry. - Potential gaps/fallacies - Hasty generalization: Assumes broad benefit without data. Remedy: add user research findings. - Appeal to intuition: “Should” statements without metrics. Remedy: define success KPIs and evaluation plans. - Tone: Professional, neutral, solution-oriented; non-adversarial. 🔍 DARVO Analysis - Deny: Not present—no denial of issues; acknowledges obscurity and missing UX. - Attack: Not present—no disparagement of users or stakeholders. - Reverse Victim and Offender: Not present—the article frames users as beneficiaries, not antagonists. - Notes: The text is technical planning, devoid of blame language or manipulative framing. ### 🔍 SEO Evaluation: - Keywords: “block library”, “WordPress blocks”, “theme.json”, “patterns”, “permissions”, “block directory” appear naturally. - Meta description: Ensure a concise summary including “WordPress Block Library,” “permissions,” and “patterns.” - Title tag: “Block Library” could be expanded to “WordPress Block Library: Permissions, Patterns, and theme.json (Phase 3)” for clarity and CTR. - Headers: Add descriptive H2s with keywords (e.g., “Global Block Management in WordPress”). - Content length: Adequate for a roadmap; could link to deeper docs. - Internal links: Link to Gutenberg docs on theme.json, patterns, and block directory. - External links: Add links to authoritative tutorials or API references as appropriate. - URL: Already concise and keyword-rich. - Images: If adding diagrams, optimize file size, alt text, and filenames. - Mobile optimization: Ensure responsive code blocks and tables. - Engagement: Add calls to action—“Test in Gutenberg Nightly,” “Join discussion thread.” - Schema: Use Article schema; consider HowTo/FAQ if adding Q&A sections. - Social: Ensure Open Graph/Twitter Cards; include a featured image for shareability. ## 🎯 Conclusion: The article sets a clear direction for maturing the Block Library: move governance outside the editor; introduce role-based capabilities; standardize developer hooks for auto-insert; connect block attributes to meta for structured content; refine third‑party block install/repair flows; elevate pattern management with categories and partial sync; and capitalize on theme.json’s composability. Collectively, these initiatives strengthen usability, governance, and extensibility—key ingredients for a sustainable, inclusive WordPress ecosystem. <!-- deep-read:sections end --> ## Highlights - 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. ([View Highlight](https://read.readwise.io/read/01h5js9e2k7d1jtar329y10z8s)) - We should connect functionalities that might already exist but are not fully developed as user features yet. ([View Highlight](https://read.readwise.io/read/01h5js9pkjcvvb2jgxc4hp71ff)) - the relationship between single blocks, post formats, and custom post types. ([View Highlight](https://read.readwise.io/read/01h5js9xjtx75tt48101eg6bds)) - 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. ([View Highlight](https://read.readwise.io/read/01h5jsa9t36bmxqfrq6jew6ntz)) - 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). ([View Highlight](https://read.readwise.io/read/01h5jsretfsn7nphgmzc05s9ta)) - formalizing a [connection between blocks and meta fields](https://github.com/WordPress/gutenberg/issues/51373) to empower building flexibility while retaining user clarity. ([View Highlight](https://read.readwise.io/read/01h5jsrvn6de5cx8zgz1a0pew0)) - 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. ([View Highlight](https://read.readwise.io/read/01h5jssmm6vr3sbq5ascgx1x4m)) - 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. ([View Highlight](https://read.readwise.io/read/01h5jsstgxfxp2n2pmez3ad6xh)) - Introduce more robust permission handling so administrators can define what blocks are available for different user roles. ([View Highlight](https://read.readwise.io/read/01h5jssz5hjf91cdnm7ka4dgw0)) - Create auto-insert hooks and API flows for block types. This is a developer tool with user flow implications. ([View Highlight](https://read.readwise.io/read/01h5jst2xv548c8rcrkmrp8b1r)) - 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. ([View Highlight](https://read.readwise.io/read/01h5jst6aqa3gtnh4wepdw8x4h)) - 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. ([View Highlight](https://read.readwise.io/read/01h5jstacf07768j84fbbw5mnd)) - Allow managing categories for saved patterns. Expose other pattern APIs, like block type or parent dependencies in the user flows. ([View Highlight](https://read.readwise.io/read/01h5jstea53h2dj8c1pe3fvyxx)) - 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. ([View Highlight](https://read.readwise.io/read/01h5jsv0bn9f5kc0ps39v8agq1)) - Note: Question: What is the goal of improving block management in the editors? Answer: 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. Question: What is the concept of "partially synced patterns"? Answer: "Partially synced patterns" allow the design layout and the style properties to remain global while the content can be locally customized. Question: What is the purpose of developing API integrations for mapping attributes to custom fields using the editor interface? Answer: The purpose is to allow blocks to provide a native UI for managing and introducing meta data through its attributes layer.