{Site Name} Theme

A theme supporting the block editor based on _s but with a tremendous number of changes 😃.

See Also

There are other README.md files in this theme in specific folders where explanations of rationale and structure are useful. e.g. src/scss/blocks/ describes when to make a partial for a block and when to compile it into the main stylesheet.

Quick Start

Clone or download this repository and it's submodules:

$ git clone --recursive https://github.com/mrwweb/hybrid-starter-theme.git <THEME_FOLDER_NAME>

Update theme details in style.css and set new 1200x900 screenshot.png.

Finally, do a six-step find and replace on the name in all the templates.

1. Search for '_MRW\ (uppercase) to capture namespaces replace with: THEME_PREFIX_.
2. Search for '_mrw' (inside single quotations) to capture the text domain and replace with: 'theme-prefix'.
3. Search for "_mrw" (double quotes) to capture phpcs ruleset and replace with "theme-prefix"
4. Search for _mrw_ (lowercase) to capture all the functions names and replace with: theme_prefix_.
5. Search for _mrw (with a space before it) to capture DocBlocks and replace with: Theme_Prefix. {{< // >}}
6. Search for _mrw- to capture prefixed handles and replace with: theme-prefix-.

Build Process

This site uses a SASS build process in order to support SASS with autoprefixer.

Edit CSS files in /src/scss/

See package.json for details.

To install build from /wp-content/themes/{themename}/

$ npm install
$ npm audit fix

To run build for development:

$ npm run sass:watch

To build prefixed and minified CSS for release:

$ npm run sass:build

To compile scripts that run in the Block Editor with entry point of /src/js/editor/index.js:

$ npm run wp-scripts

To concatenate and uglify JS files in /src/js/*.js:

$ npm run js:build

Expected Icons in assets/images/svg

• logo.svg for logo
• Right-pointing arrow.svg for dropdown menu item indicator
• search.svg for search button icon
• Right-pointing chevron.svg for paging links
• close.svg for menu toggle button
• menu.svg for menu toggle button

Notable Changes from _s Theme

• Lots of block-first development things including:
  • theme.json
  • Maps SASS variables to theme.json custom properties so theme.json is the "source of truth" (Notable downside of this technique: cannot perform SASS calculations on custom properties.)
  • Block-specific SCSS partials
  • Stylesheets for less-used blocks are enqueued per-block, though consider potential downsides of really tiny files when it comes to gzip and network requests and how good gzip is. Right now, loading separate stylesheets in a hybrid theme incurs a performance penalty for Content Layout Shift.
  • Uses Block Template Parts instead of widgets for the footer, sidebar, and 404 page
  • PHP used to set a few default variations for core WordPress blocks
  • Example of custom block style ready to go in /inc/block-editor-config.php
  • Uses template parts instead of most template tags
• Uses clicky-menus script for click-triggered dropdown navigation submenus
• Includes a toggle script (assets/js/toggle.js) to quickly build accessible toggles
• Custom toggle script for mobile menu and any other toggles you need
• Fixes search forms not having unique IDs if more than one is on the page
• Custom template tag to get SVGs (props @aurooba Inline SVG Helper function)
• Expects usage of MRW Simplified Editor, The Events Calendar, Gravity Forms (affiliate link), and PublishPress Authors
  • Recommended: Use The Events Calendar Reset for better theme style inheritance

Dev Environment

Autoformatting/linting:

• .editorconfig
• .stylelintrc.json
• .eslintrc
• .phpcs.xml.dist
• prettier configured in package.json

Make sure your editor supports .editorconfig for some very basic coding standards autoformatting.

Other Notes

See /wp-content/mu-plugins/ non-theme related site changes. (not included in the Github repository)

Credit & Contact

Mark Root-Wiley, MRW Web Design https://MRWweb.com/contact