A starter block theme for WordPress 5.9+.
- Node 16.x.x
- npm 7.x.x
- WordPress 5.9+
- Forum One Block Library (Optional)
npm ci- [Optional] Rename the theme with
npm run rename npm run dev- Enable the theme
To build the theme for production (or to get your local up and running if you will not be working on the theme itself):
npm cinpm run build
Gesso utilizes theme.json file for setting theme defaults and variables. Colors, font families, font sizes, individual block styles and custom values like layout constrain widths are included. For more about what can be configured with theme.json, see the Block Editor Handbook.
Sass can be compiled as part of the global styles.css file or to individual CSS files for use in a block style.
@use is used to import Sass variables, mixins, and/or functions into individual SCSS files. @import is discouraged by the Sass team and will eventually be phased out. This means that most files will start with @use '00-config' as ;. This allows you to use functions and mixins provided by Gesso throughout your SCSS files. Note that to avoid namespace collisions, only mixins, and functions should be used with.
All Sass files that are compiled to individual CSS files must have a unique filename, even if they are in different directories.
Prefix the name of your Sass file with _, e.g. _card.scss. Add it to the appropriate aggregate file (i.e. _components.scss).
DO NOT prefix the name of your Sass file with _, e.g. menu.scss.
Import the config and global aggregate files. Add your CSS file to the
wp_next_theme_block_assets function inside functions.php:
wp_enqueue_block_style('f1-block-library/standalone-link', [
'handle' => 'wp-next-theme-standalone-link',
'src' => get_theme_file_uri('build/css/standalone-link.css'),
'path' => get_theme_file_path('build/css/standalone-link.css')
]);Omit the path line if the WordPress should not be able to choose whether
to inject the styles via a <style></style> tag instead of loading an external
file. You may need to remove that line if you find that image paths break when the
CSS is injected. See the WordPress dev note for more on loading block styles.
Block Styles can be registered or unregistered in the source/editor-styles.js. This script is loaded whenever the Block Editor is loaded. For more about Block Styles, see the Block Editor Handbook.
Linting is done with Prettier, ESLint, and Stylelint. Linting follows the WordPress standards, with some rules disabled where needed to resolve conflicts between tools (mostly Prettier and Stylelint) or between linting standards and the theme design tokens.
Gesso uses CSS variables generated from theme.json. You can view the list of all available variables generated by theme.json using your browser's inspector tools. Select the <body> tag for the page and in the styles tab you can view a list of all available CSS variables.
var(---wp--preset--color--brand-primary) Output the primary brand color.
example:
background-color: var(---wp--preset--color--brand-primary);
You can use the values of custom properties in JavaScript just like standard properties.
For example say you have added a custom variable for breakpoints. You cna use it in your scripts like:
const body = document.querySelector('body');
const desktopBreakpoint = getComputedStyle(body).getPropertyValue(
'--wp--custom--breakpoint--desktop'
);
if (window.matchMedia(`min-width: ${desktopBreakpoint}`).matches) {
// Some script that should only run on larger screens.
}
Gesso uses custom mixins to specify viewport width based media queries:
breakpoint: min-width queriesbreakpoint-max: max-width queriesbreakpoint-min-max: queries with both a min and max width
Each mixin takes one or two
width parameters, which can be a straight value (e.g., 800px, 40em) or a design
token value called using the gesso-breakpoint function (e.g.,
gesso-breakpoint(tablet-lg)). The breakpoint-max and breakpoint-min-max
mixins can also take an optional parameter to subtract one pixel from the
max-width value, which can be useful when you want your query to go up to the
value but not to include it, such as when using WordPress breakpoint variables.
You can also use the width-based breakpoint mixins defined in @wordpress/base-styles, alongside the breakpoint variables. We recommend using those instead of defining your own for consistency between theme styling and plugin styling.
$break-huge: 1440px;
$break-wide: 1280px;
$break-xlarge: 1080px;
$break-large: 960px; // admin sidebar auto folds
$break-medium: 782px; // adminbar goes big
$break-small: 600px;
$break-mobile: 480px;
$break-zoomed-in: 280px;@include breakpoint($width) { // styles }
Output a min-width based media query.
examples:
@include breakpoint(800px) {
display: flex;
}
@include breakpoint($break-medium) {
display: none;
}
@include break-small {
display: grid;
}
@include breakpoint-max($width, $subtract_1_from_max) { // styles }
Output a max-width based media query. The optional $subtract_1_from_max
parameter will subtract 1px from the width value if set to true
(default: false).
examples:
@include breakpoint-max(900px) {
display: block;
}
@include breakpoint-max($break-small, true) {
display: none;
}
@include breakpoint-min-max($min-width, $max-width, $subtract_1_from_max) { // styles }
Output a media query with both a min-width and max-width. The optional
$subtract_1_from_max parameter will subtract 1px from the max-width value if
set to true (default: false).
examples:
@include breakpoint-min-max(400px, 700px) {
display: flex;
}
@include breakpoint-min-max($break-small, $break-medium, true) {
display: block;
}
In previous versions of Gesso, constrain classes were used to apply max-width and inline padding at the same time. As of 6.1, WordPress can now generate most of these styles automatically, and Gesso opts into this via theme.json. settings.useRootAwarePadding is set to true, and the spacing value is set at styles.spacing.padding. If you're not getting the padding you expect, check the layout settings on your blocks. More details can be found in the documentation.
Gesso uses custom mixins to specify container queries:
container-query: min-width container queriescontainer-query-max: max-width container queriescontainer-query-min-max: container queries with both a min and max width
Each mixin takes one or two width parameters, which can be a straight value
(e.g., 800px, 40em) or a design token value called using the gesso-breakpoint
function (e.g., gesso-breakpoint(tablet-lg)). The container-max and
container-min-max mixins can also take an optional parameter to subtract one
pixel from the max-width value, which can be useful when you want your query to
go up to the value but not to include it, such as when using Gesso breakpoint
token values.
In order for container queries to work, you need to set a containment context on a parent element.
container-type: inline-size;container: container-name / inline-size;Output a min-width based media query.
@include container-query(800px) {
display: flex;
}
@include container-query($break-xlarge) {
display: none;
}Output a max-width based container query. The optional $subtract_1_from_max
parameter will subtract 1px from the width value if set to true (default:
false).
@include container-query-max(900px) {
display: block;
}
@include container-query-max($break-small, true) {
display: none;
}Output a container query with both a min-width and max-width. The optional
$subtract_1_from_max parameter will subtract 1px from the max-width value if
set to true (default: false).
@include container-query-min-max(400px, 700px) {
display: flex;
}
@include container-query-min-max(
$break-small,
$break-xlarge,
true
) {
display: block;
}The gesso theme has been structured to not leverage the Wordpress Full Site Editor at this time. It does, however, leverage template parts, allowing the block editor management of templates and their structural parts. A suite of baseline template parts have been created for each of the base PHP templates within the theme and can be found in the parts/ folder.
If you wish to leverage the Full Site Editor functionality, you can make the following modifications to the gesso theme structure. Please note that at this time, there are concerns around certain aspects of deployment procedures with database specific references (such as navigation blocks). Unless there is a strong case to leverage FSE, it is advised to opt for just leveraging the template parts at this time.
To leverage the Full Site Editor:
- Create a directory in the root of the gesso theme named
templates - Copy all html files from within the
partsdirectory (with the exception of header.html and footer.html) and move them into your newtemplatesdirectory. You will need to reference theheader.htmlandfooter.htmlparts within your html files now in thetemplatesfolder. You can do this in the UI. - Create a new file called
index.htmland place it within thetemplatesdirectory. - All PHP files corresponding to one within the
templatesorpartsdirectories, located in theme root, can be deleted. - Remove
add_theme_support('menus');andadd_theme_support( 'block-template-parts' );within functions.php
Gesso now also supports the template structure to automatically pull in rendered Block Patterns. When creating a Block Patter, you can store the markup and block definitions as individual files within the 'pattern' directory.
By default WordPress core block patterns are disabled. To re-enable, remove the following from functions.php:
remove_theme_support( 'core-block-patterns' );
When starting your new Wordpress project, you may have a need to register custom blocks for your site's theme. Prior to starting new, first take a look at the available blocks located within the f1-block-library. If the blocks there do not suffice, the Forum One github repository also contains a starter block plugin that you can install and use to house all custom blocks.