Skip to content

README.md

Latest commit

 

History

History
143 lines (93 loc) · 6.59 KB

README.md

File metadata and controls

143 lines (93 loc) · 6.59 KB

WP Site Starter

This is a custom block starter theme built by Viget. Update this file as needed for your custom theme.

Front-End Stack

Theme.json

The theme.json holds many of the core WordPress theme settings. The theme.json is built using several JS files in the /src/theme-json/ directory. Vite builds all of these files and exports a theme.json for both dev and build. Do not edit directly theme.json as it will be overwritten on build.

Several of the Tailwind variables are pulled into theme.json and Tailwind should be used as the primary method for styling. If you need to, you can add more Tailwind variables for custom styling in theme.json.

The files that create the theme.json can be used to apply custom settings for blocks, global theme styles, or define custom templates. Here are a few references:

Custom Blocks 🧱

Blocks are built using ACF and core WordPress blocks. Styles for the blocks are located within the block folders.

  • Accordion
  • Alert Banner
  • Breadcrumbs
  • CTA
  • Image w/Caption
  • Logo Grid
  • Navigation Container
  • Page Header
  • Text & Icon Cards
  • Text & Image
  • Video Embed
  • Video Player

Creating New Blocks

The theme includes plop which will auto-generate a new block based on the options you input. To create a new block, run:

ddev npm run plop block

You will be asked a few questions:

  • What is the block name? - This can be whatever you want.
  • What is your theme's text domain? - This is the text domain of your theme, which is usually the same as the theme folder name. If you are unsure of what this is, you can look at the Text Domain: value in your theme's style.css file.
  • Do you need block styles? - Adds custom class names for the block - See Block Styles
  • Do you need block variations? - Adds custom block variations - See Block Variations

Once your block is created, it is recommended you set the block's icon in block.json. You can pick from one of WordPress's Dashicons, or use your own custom SVG file.

Customizing Theme 🎨

Fonts

Fonts are pulled in by typography.js. Update the src to point to the font files in /src/fonts/ directory. For more info on setting up WordPress fonts, check out fullsiteediting.

The default font settings can be found in _index.js.

Colors

You have access to all of Tailwind's colors, but feel free to create your own custom colors in the Tailwind config.

Tailwind colors are automatically added to theme.json via settings/color.js and are available to use in WordPress. Some colors are automatically prefixed with dark- to identify automated style adjustments.

Spacing

The default spacing is fluid, meaning that it is larger on desktops and smaller on mobile screens.

Class Min Max
.fluid-xs 2px 16px
.fluid-sm 20px 40px
.fluid-md 32px 64px
.fluid-lg 56px 112px
.fluid-xl 96px 160px
.fluid-2x 144px 240px

Adjust the spacing as needed from the spacing.css config file.

Buttons

WordPress button styles are normally built in the theme.json, but because there is a limitations on hover/focus customizations on button variants, all the buttons style are built in Tailwind.

The base button styles are found in styles/core-blocks/buttons.css. By default, there are two built-in button classes:

Button Classes
.btn-default
.btn-outline

Adding more Buttons Styles

If you need to add more button styles, you can register a new block style on the core/button inside of blocks.php:

register_block_style(
	'core/button',
	[
		'name'  => 'icon-only',
		'label' => __( 'Icon Only', 'theme-slug' ),
	]
);

This will attach a class to the block in the pattern of is-style-[name]. Once you have the new button style registered you add the Tailwind style in /src/styles/core-blocks/buttons.css. It is recommended that you create descriptive button styles and not generic styles like "primary" or "secondary".

Custom Button Icons

See Viget Blocks Toolkit for more information.

Navigation

The navigation has been set up to be fully accessible and is built using Alpine with a base set of styles.

Troubleshooting

Editor Fonts

The WP Editor requires WOFF2 fonts. TTF/OTF fonts will load on render for templates/pages, but will not display correctly in the Editor view unless they’re in WOFF2 format.

Editor Styles

The Editor loads the generated Tailwind output, which means you may need to run ddev npm run build to generate CSS used by the Editor.

Disconnected Template Parts

If you edit a template part in the CMS (like the Header), WordPress will use the database version, overriding the template file in the theme. To reset to the code version:

  1. Open the template part in the Editor.
  2. Click the part name at the top of the screen to bring up the Command Palette.
  3. Type ‘Reset’ and select the command. This will remove DB modifications and reset to the code version.
  4. Alternatively, you can go to WP Admin > Appearance > Editor, locate the template, click the 3-dot menu on next to the name, then click Reset.

Trying to find a value in block.json

Not all the properties are completely documented. If you’re having trouble, check out the block schema in the main WP repository.