Feature: Block Based Theme Training

.gitignore

@@ -19,3 +19,6 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+# Cursor
+.cursor

reference/04-Patterns/block-bindings-api.md

@@ -239,17 +239,14 @@ Below is the full code from our example Call to Action.
 Here we can see that our Call to Action will display a nice fallback should our post meta fields be missing.
 
 ![Call to action with default settings applied](../../static/img/block-pattern-call-to-action-example.jpg)
-<br/>
 *Call to action with default settings applied*
 
 If we have our all of our desired data, we will display our custom content.
 
 ![An example of our populated post meta fields](../../static/img/block-pattern-bindings-post-meta-example.jpg)
-<br/>
 *An example of our populated post meta fields*
 
 ![Our dynamic Call to Action populated with our post meta fields](../../static/img/block-pattern-bindings-finished-example.jpg)
-<br/>
 *Our dynamic Call to Action populated with our post meta fields*
 
 ## Further reading

reference/04-Patterns/synced-pattern-overrides.md

@@ -47,7 +47,6 @@ When an Override enabled block is selected, after editing a **Reset** control is
 When the pattern itself *or* any of its Override enabled innerblocks are selected, the usual block Inspector Control "Settings" panel is replaced by a "Content" panel where we can select the blocks that allow for editing.
 
 ![The updated block settings for an override enabled Synced Pattern](../../static/img/block-pattern-synced-override-enabled.jpg)
-<br/>
 *The updated block settings for an override enabled Synced Pattern*
 
 On the next page, we'll take a look at what's going on under the hood of a Synced Pattern and learn how we can apply our own logic to manage the content of our Patterns using the Block Bindings API.

reference/04-Patterns/synced-patterns.md

@@ -9,7 +9,6 @@ Block Patterns are an excellent way to quickly add common components across our
 This is where Synced Patterns shine.  We can create a global component which can be edited once to then update across all instances where it is used.  For example an info card, a grid of logos, or perhaps a simple call to action are all excellent candidates which may require such a feature.  We will use the latter in our examples.
 
 ![Call to action example pattern](../../static/img/block-pattern-call-to-action-example.jpg)
-<br/>
 *A simple Call to Action block pattern*
 
 :::caution
@@ -29,7 +28,6 @@ To mark a pattern as Synced, you would follow these steps:
 That's it!  You can now find your component via the block inserter under the Patterns tab > My Patterns *(and any other categories you declared in step 3)*.
 
 ![The modal window for adding a new Pattern](../../static/img/block-pattern-add-new-modal.jpg)
-<br/>
 *The modal window for adding a new Pattern*
 
 ## Updating a Synced Pattern
@@ -43,7 +41,6 @@ To edit your Synced Pattern, you would do the following:
 5. You can return to the page you were editing using the **Back** button located near the title in the upper center of the screen.
 
 ![The block toolbar to edit your Synced Pattern](../../static/img/block-pattern-synced-edit-original.jpg)
-<br/>
 *The block toolbar to edit your Synced Pattern*
 
 ## Creating Synced Patterns for Theme Authors

src/css/docs-content.css

@@ -11,3 +11,8 @@
 main > .container {
 	margin-bottom: 4rem;
 }
+
+main img:has(+ em) {
+	display: block;
+	margin-block-end: 4px;
+}

training/Block-Based-Themes/01-overview.md

@@ -1,16 +1,21 @@
-# Lesson 1: Anatomy of a block based theme
+---
+sidebar_label: 1. Anatomy of a Block Based Theme
+sidebar_position: 1
+---
 
-Block Based Themes _(sometimes referred to as Full Site Editing or FSE for short)_ are a new way of building WordPress themes. Instead of using PHP templates, you build your theme using blocks. This means that everything in your theme is a block, from the header to the footer, and everything in between.
+# 1. Anatomy of a Block Based Theme
 
-In this lesson, we'll take a look at the anatomy of a block based theme, and how you can start building your own.
+Block Based Themes (sometimes referred to as Full Site Editing or FSE for short) are a new way of building WordPress themes. Instead of using PHP templates, you build your theme using blocks. This means that everything in your theme is a block, from the header to the footer, and everything in between.
+
+In this lesson, we'll take a look at the anatomy of a block based theme and how you can start building your own.
 
 ## The Basics
 
-Even though it might seem like a big change, building a block based theme is not that different from building a traditional theme. The main difference is that instead of using PHP templates, you HTML template files that contain block markup. These files are stored in a `templates` folder in your theme.
+Even though it might seem like a big change, building a block based theme is not that different from building a traditional theme. The main difference is that instead of using PHP templates, you use HTML template files that contain block markup. These files are stored in a `templates` folder in your theme.
 
-Everything else is pretty much the same. Any theme still requires a `style.css` file for the theme metadata, and a `functions.php` file for any custom functions or hooks, and so on.
+Everything else is pretty much the same. Any theme still requires a `style.css` file for the theme metadata and a `functions.php` file for any custom functions or hooks.
 
-You can think of block based themes as a superset on top of traditional themes. If you look at the template hierarchy in WordPress (e.g. `index.php`, `single.php`, `page.php`, etc.), the introduction of block based themes doesn't change that. Instead of `index.php`, you now have `templates/index.html`, and so on. The same rules apply, but instead of PHP files, you use HTML files. The cool part here is that technically speaking you can even still use PHP files. The template hierarchy will look for `.html` files first, and then fall back to `.php` files if it can't find an `.html` version.
+You can think of block based themes as a superset on top of traditional themes. If you look at the template hierarchy in WordPress (`index.php`, `single.php`, `page.php`, etc.), the introduction of block based themes doesn't change that. Instead of `index.php`, you now have `templates/index.html`, and so on. The same rules apply, but instead of PHP files, you use HTML files. Technically you can even still use PHP files: the template hierarchy will look for `.html` files first, and then fall back to `.php` files if it can't find an `.html` version.
 
 ![Block Based Theme File Structure](../../static//img/fse-template-hierarchy.png)
 
@@ -53,7 +58,7 @@ $footer_template = do_blocks( $footer_template->content );
 
 		<main class="is-layout-constrained">
 			<h1><?php the_title(); ?></h1>
-			
+
 			<?php
 			// do custom work here
 			?>
@@ -93,7 +98,7 @@ You **cannot use arbitrary HTML** in a block template. **It needs to be valid bl
 
 If you need custom markup that isn't already available via any of the core blocks you can create it as a custom block. You can learn more about how to do that in the [Blocks section](../Blocks/01-overview.md).
 
-Block based themes don't mean that we no longer write custom blocks. But rather that the custom blocks we do build are much more atomic rather that the big monolithic blocks that we might have built in the past.
+Block based themes don't mean that we no longer write custom blocks, but rather that the custom blocks we do build are much more atomic rather than the big monolithic blocks we might have built in the past.
 
 ![Monolithic vs. Atomic blocks](../../static/img/atomic-blocks.png)
 
@@ -105,29 +110,29 @@ No one should have to hand author the block markup in the `.html` files. The edi
 
 ## The Site Editor
 
-We just mentioned the site editor, and it's a key part of building block based themes. The site editor is where you create and edit your block templates and template parts. It's a visual editor that lets you see how your changes will look on the frontend in real-time.
+We just mentioned the Site Editor, and it's a key part of building block based themes. The Site Editor is where you create and edit your block templates and template parts. It's a visual editor that lets you see how your changes will look on the frontend in real time.
 
-We should think of the site editor as a kind of visual IDE for developing WordPress themes. It is a development feature rather that something we would expect end users to use.
+We should think of the Site Editor as a kind of visual IDE for developing WordPress themes. It is a development feature rather than something we would expect end users to use.
 
 ## Theme.json
 
 There is a myth out there that you don't wite any CSS in a block based theme and instead do everything in the `theme.json` file. **This is not true.**
 
-Whilst you may find core themes such as twentytwentyfive to strive for _zero css_ that is not at all a requirement and I would even go so far as to say it is only really something you should consider if you are building a theme for the WordPress theme directory.
+Whilst you may find core themes such as Twenty Twenty-Five striving for "zero CSS," that is not at all a requirement. It is really only something you should consider if you are building a theme for the WordPress theme directory.
 
-For custom built themes for client projects it brings very little value and adds a lot of complexity in terms of fighting with WordPress cores stylesheet specificity.
+For custom-built themes on client projects, it brings very little value and adds a lot of complexity in terms of fighting with WordPress core's stylesheet specificity.
 
 :::tip
-A rule of thumb is that you should `theme.json` as the source of truth for all your design tokens and settings. But any actual styles should be written in CSS files.
+A rule of thumb is that you should use `theme.json` as the source of truth for all your design tokens and settings. But any actual styles should be written in CSS files.
 :::
 
 ## Styles
 
-One of the nice benefits of block based themes where everything is made out of blocks is, that only the styles for the blocks that are actually used on the page are loaded. So you WordPress essentially does some code splitting for you.
+One of the nice benefits of block based themes where everything is made out of blocks is that only the styles for the blocks actually used on the page are loaded. WordPress essentially does some code splitting for you.
 
-Whats even more interesting is that on top of just code splitting, WordPress also does some light critical CSS extraction for you.
+What's even more interesting is that on top of code splitting, WordPress also does some light critical CSS extraction for you.
 
-When a page is loaded WordPress parses the blocks from top to bottom. And any time it encounters a block it will try to load all the styles associated with that block. As it does that it has a little buffer where instead of loading the individual css file, it will take the styles and actually inline them into the head of the document. WordPress will to that until that buffer is full and then it will start loading the css remaining CSS files separately. That way the blocks at the top of the page should have all their styles already present on the page when they are rendered.
+When a page is loaded, WordPress parses the blocks from top to bottom. Any time it encounters a block, it tries to load all the styles associated with that block. It has a small buffer where instead of loading the individual CSS file, it inlines the styles directly into the `<head>` of the document. WordPress does that until the buffer is full, and then it starts loading the remaining CSS files separately. That way the blocks at the top of the page should have all their styles already present when they are rendered.
 
 ![Diagram how WordPress parses blocks top to bottom](../../static/img/block-css-inlining.png)
 
@@ -143,12 +148,11 @@ Our theme scaffold is already setup for this and has a special `assets/css/block
 
 ## Takeaways
 
-- Block based themes are a new way of building WordPress themes that use blocks instead of PHP templates.
-- Block templates are HTML files that contain block markup. They need to be stored in a `templates` folder in your theme.
-- The site editor is where you create and edit your block templates and template parts.
-- You should use the site editor to create your block templates, rather than hand-authoring the block markup in the `.html` files.
+- Block based themes use blocks instead of PHP templates. Everything from the header to the footer is a block.
+- Block templates are HTML files that contain block markup, stored in a `templates` folder in your theme.
+- The Site Editor is where you create and edit your block templates and template parts.
+- Author templates in the Site Editor, not by hand. No one should have to hand-author block markup in `.html` files.
 - You can still use PHP templates in a block based theme, but it's recommended to stick with `.html` files as much as possible.
-- You should use the `theme.json` file as the source of truth for your design tokens and settings, but write your styles in CSS files.
-- You should write your CSS for individual blocks in separate CSS files in the `assets/css/blocks` folder.
-- WordPress does some code splitting and critical CSS extraction for you in block based themes.
-- The [Create Block Theme plugin](https://wordpress.org/plugins/create-block-theme/) is a must-have for building block based themes.
+- Use the `theme.json` file as the source of truth for your design tokens and settings, but write your actual styles in CSS files.
+- Write CSS for individual blocks in separate files in the `assets/css/blocks` folder. WordPress code-splits these automatically.
+- WordPress does code splitting and critical CSS extraction for you in block based themes.

training/Block-Based-Themes/02-using-10up-block-theme.md

@@ -0,0 +1,143 @@
+---
+sidebar_label: "2. Orientation: The 10up Block Theme"
+sidebar_position: 2
+---
+
+# 2. Orientation: The 10up Block Theme
+
+If your environment is [set up as outlined in the overview](./index.md#getting-started), let's take a quick look at the 10up Block Theme scaffold and what it provides on top of a vanilla block theme.
+
+## Learning Outcomes
+
+1. Know what the 10up WP Scaffold adds beyond a standard block theme.
+2. Be able to run the build pipeline and see the result.
+
+## What the scaffold provides
+
+We'll be using the [10up WP Scaffold](https://github.com/10up/wp-scaffold) as our starting point. Beyond a standard block theme, it includes:
+
+- **10up-toolkit**: a zero-config webpack-based build pipeline that handles CSS and JS compilation, block asset detection, and hot reloading.
+- **Auto-enqueue block CSS**: drop a CSS file into `assets/css/blocks/{namespace}/{block-name}.css` and it loads only when the block is present on the page.
+- **Auto-register custom blocks**: create a folder with a `block.json` in `blocks/` and it's automatically registered.
+- **PostCSS with globals and mixins**: custom media queries and mixins are available across all style entry points without manual imports.
+- **10up WP framework integration**: uses the [10up WP Framework](https://github.com/10up/wp-framework) pattern for organized, auto-discovered PHP modules.
+- **Sensible CSS architecture**: organized into base, blocks, components, globals, mixins, templates, and utilities.
+- **A must use plugin**: a place to register post types, taxonomies, or other non-theme specific features.
+
+We'll explore the CSS architecture, JS entry points, editor style scopes, and PHP module system in detail as we encounter them in later lessons. For now, the goal is to understand the high-level structure and prove the build pipeline works.
+
+## Theme structure
+
+```bash
+cd themes/10up-block-theme
+```
+
+<details>
+<summary>View tree</summary>
+
+```bash
+10up-block-theme/
+├── composer.json
+├── functions.php
+├── package.json
+├── style.css
+├── theme.json
+├── assets/
+│   ├── css/
+│   │   ├── base/
+│   │   ├── blocks/
+│   │   │   └── core/
+│   │   ├── components/
+│   │   ├── editor-canvas-style-overrides.css
+│   │   ├── editor-frame-style-overrides.css
+│   │   ├── frontend.css
+│   │   ├── globals/
+│   │   ├── mixins/
+│   │   ├── templates/
+│   │   └── utilities/
+│   ├── js/
+│   │   ├── block-extensions.js
+│   │   └── frontend.js
+│   └── fonts/
+├── blocks/
+├── parts/
+│   ├── footer.html
+│   ├── header.html
+│   ├── site-footer-legal-navigation-area.html
+│   └── site-header-navigation-area.html
+├── patterns/
+│   └── card.php
+├── src/
+│   ├── Assets.php
+│   ├── Blocks.php
+│   ├── TemplateTags.php
+│   └── ThemeCore.php
+├── styles/
+│   ├── surface-primary.json
+│   ├── surface-secondary.json
+│   └── surface-tertiary.json
+└── templates/
+    ├── 404.html
+    ├── index.html
+    ├── single.html
+    └── singular.html
+```
+
+</details>
+
+The key directories to know right now:
+
+| Directory | Purpose |
+|-----------|---------|
+| `templates/` | HTML template files (block markup) following the WordPress template hierarchy |
+| `parts/` | Reusable template parts (header, footer, navigation areas) |
+| `patterns/` | PHP-based block patterns |
+| `theme.json` | Design tokens, settings, and layout configuration |
+| `assets/css/` | CSS source files, organized by purpose |
+| `assets/js/` | JS entry points for frontend and editor |
+| `blocks/` | Custom block source files (auto-registered) |
+| `src/` | PHP modules (auto-discovered via the 10up WP Framework) |
+| `styles/` | Style variation JSON files |
+
+We'll dig into each of these as we work with them in upcoming lessons.
+
+## Task: Verify the build pipeline
+
+Let's do one quick exercise to prove the build pipeline works.
+
+The 10up Block Theme contains an opinionated modification to the block editor Post Title text input wrapper.  Typically this appears as part of the content area of the post, however this can often times feel undesirable when using Page Header or Hero type blocks that display the title as it does on the frontend.  Our theme modification makes this appear as part of the standard editor UI, providing a bit more visual clarity.
+
+![Screenshot of the unmodified post title wrapper](../../static//img/training/editor-post-title-wrapper-unmodified.png)
+*The unmodified Post Title wrapper*
+
+![Screenshot of the 10up Block Theme modified post title wrapper](../../static//img/training/editor-post-title-wrapper-modified.png)
+*The 10up Block Theme modified Post Title wrapper*
+
+1. Open `assets/css/editor-canvas-style-overrides.css`.
+
+2. Find the `background-color` declaration and change it from `#fff` to `pink`:
+
+```css
+.editor-styles-wrapper .editor-post-title {
+    background-color: pink;
+}
+```
+
+3. Run the build:
+
+```bash
+npm run build
+```
+
+4. Open any post in the editor. The title area should now have a pink background.
+
+![Screenshot of the 10up Block Theme modified post title wrapper with pink background](../../static//img/training/editor-post-title-wrapper-pink.png)
+
+5. Revert the change back to `#fff` and rebuild.
+
+That's it. The build pipeline compiles CSS and JS from `assets/` into `dist/`, and WordPress loads the output. We'll explore how that enqueuing works in [Lesson 5](./05-styles.md) when we dive into the CSS architecture.
+
+## Takeaways
+
+- The 10up scaffold provides a build pipeline, CSS architecture, PHP module system, and auto-registration for blocks and block CSS out of the box.
+- We'll explore each of these systems in depth as we use them in later lessons.