Documentation

Requirements

Dependency	Minimum	Tested up to
WordPress	6.5	6.7
WooCommerce	8.3	9.4
PHP	8.1	8.3

Meridian is a Full Site Editing (FSE) block theme. The Classic Editor plugin and page builders are not supported and should not be active alongside this theme.

Installation

Option A — Upload ZIP (recommended)

1. Download meridian.zip from the download link in your purchase confirmation email
2. Appearance → Themes → Add New → Upload Theme
3. Choose the ZIP → Install Now → Activate
4. Install WooCommerce if not already installed: Plugins → Add New → search “WooCommerce”
5. WooCommerce → Status → Tools → “Install WooCommerce pages”

Import demo content

To populate your store with 14 sample products, demo pages, and navigation structure:

1. Tools → Import → WordPress → upload demo/demo-content.xml
2. Map the “admin” author to your own user account
3. Click Submit — import takes ~15 seconds
4. See demo/README.md for the full post-import setup walkthrough (adding images, setting homepage, navigation)

Site Editor

Everything in Meridian is editable without code via Appearance → Editor.

Section	What you can change
Templates	Full-page layouts — homepage, shop, product, cart, etc.
Template Parts	Header and footer (reused across every template)
Patterns	Reusable sections available in the block inserter
Styles	Global colours, fonts, spacing via the Global Styles panel
Navigation	Menu structure and links for the header

Changing colours

1. Appearance → Editor → Styles (paintbrush icon, top right)
2. Click any colour swatch to change it
3. Changes apply everywhere that token is used — all buttons, headings, and backgrounds update instantly

Changing fonts

The same Styles panel lets you switch the heading or body font. Meridian ships with DM Serif Display (headings) and DM Sans (body) loaded from Google Fonts. To use local or different fonts, remove the meridian-fonts enqueue from functions.php and add @font-face declarations in assets/css/global.css.

Design Tokens

All visual values are declared in theme.json as named tokens. The Site Editor exposes them via the Global Styles panel — no code needed for colour or typography changes.

Key colour tokens

Slug	Default	CSS Custom Property	Used for
ink	#0F0F0F	--wp--preset--color--ink	Text, buttons, borders
parchment	#FAFAF7	--wp--preset--color--parchment	Page background
surface	#FFFFFF	--wp--preset--color--surface	Cards, modals, overlays
accent	#C4A882	--wp--preset--color--accent	CTAs, badges, swatch highlights
success	#3D7A5C	--wp--preset--color--success	In-stock, added-to-cart feedback
sale	#C03B31	--wp--preset--color--sale	Sale prices, error notices

The full token reference (all 13 colours, 8 fluid font sizes, 11 spacing steps, and 7 custom tokens) is in the README.md file included with the theme.

WooCommerce Setup

Block checkout

Meridian is built for the WooCommerce block cart and block checkout — not the classic shortcode checkout. Ensure your Cart and Checkout pages contain the Cart Block and Checkout Block respectively. Run WooCommerce → Status → Tools → “Install WooCommerce pages” if unsure — this recreates the pages with the correct blocks.

Product image dimensions

Name	Dimensions	Used for
Thumbnail	300 × 375px (4:5)	Product grid cards
Medium	600 × 750px (4:5)	Quick view modal
Large / Single	900 × 1125px (4:5)	Single product page

HPOS (High Performance Order Storage)

Meridian declares compatibility with WooCommerce HPOS. To enable it: WooCommerce → Settings → Advanced → Features → High-Performance Order Storage → enable. No theme changes required.

Conversion Features

Attribute Swatches

Meridian replaces the default WooCommerce colour dropdown with visual swatches for any attribute with slug pa_color or pa_colour. To set swatch colours:

1. Go to Products → Attributes
2. Click Configure terms next to your Colour attribute
3. Edit each term — a Swatch Color colour picker appears at the bottom of the form
4. Pick the hex colour for that term → Update

Sale Countdown Timer

Add a live countdown to any page or post with the shortcode:

[meridian_sale_countdown end="2025-12-31 23:59:59" label="Sale ends in"]

On a single product page, omit the end attribute to read the product’s own WooCommerce sale end date automatically. The element renders nothing if the sale has ended — no “0:00:00” flash. A ready-made block pattern Meridian → Sale Countdown Band is available in the block inserter.

Stock Badges

Products with stock management enabled automatically show a badge on their card when stock is low (≤ 5 units, configurable via the meridian_low_stock_threshold filter), on backorder, or out of stock. Enable stock management per product via Products → [Product] → Inventory → Manage stock.

Breadcrumbs

Breadcrumbs appear automatically on product, category, tag, and shop pages using WooCommerce’s native breadcrumb function. JSON-LD structured data is added to <head> automatically and is skipped if Yoast SEO, RankMath, or SEOPress is installed (they generate their own schema).

Template Reference

File	Route	Description
front-page.html	Homepage	Hero, featured products, editorial band, categories, newsletter
archive-product.html	/shop, category archives	Product grid with 3-column layout
single-product.html	/product/…	Gallery, summary, trust badges, tabs, related products
page-cart.html	/cart	Block cart + cross-sells
page-checkout.html	/checkout	Block checkout + order summary
page-account.html	/my-account	Account dashboard + sidebar nav
page-lookbook.html	Lookbook template pages	Editorial spreads with inline “Shop This Look”
page-landing.html	Landing page template	Minimal header/footer for campaign pages
page-documentation.html	Documentation template	This page
404.html	Not found	404 error page

Troubleshooting

Site Editor shows a blank screen or won’t open

• Confirm the theme is active under Appearance → Themes
• Enable WP_DEBUG in wp-config.php and check wp-content/debug.log for PHP errors
• Deactivate other plugins one-by-one to isolate a conflict

Shop page shows no products or blank layout

• Run WooCommerce → Status → Tools → “Install WooCommerce pages”
• Ensure WooCommerce 8.3+ is installed
• Check the shop page is set under WooCommerce → Settings → Products → Shop page

Quick view button not appearing on product cards

• The button is injected by a render_block PHP filter on woocommerce/product-image blocks inside a Product Collection — it will not appear on standalone image blocks
• Check that product-ux.js is loading (open browser console → Network tab → filter by “product-ux”)

Colour swatches showing a dropdown instead of buttons

• The swatch feature only activates for attributes with the taxonomy slug pa_color or pa_colour — check the attribute slug under Products → Attributes
• Ensure the attribute’s type is Select (not Text)

Auto-updater shows no update available

• Confirm MERIDIAN_LICENSE_EMAIL and MERIDIAN_LICENSE_KEY are defined in wp-config.php — these are the email and license key you received when you purchased Meridian
• Clear the transient: delete the meridian_update_info transient via Tools → Transients Manager or WP CLI: wp transient delete meridian_update_info

Google Fonts not loading

• Some hosting environments block outbound requests to Google. Download DM Serif Display and DM Sans from fonts.google.com, place them in assets/fonts/, add @font-face declarations to global.css, and remove the meridian-fonts enqueue call from functions.php