Getting Started

Soames runs WordPress as a headless CMS: you author content in WordPress, and a fast, static Astro front end reads it over WPGraphQL and renders the site. This guide takes you from a fresh WordPress install to running the Soames front end locally.

What you’ll need

A WordPress site you can administer (self-hosted or managed; multisite works too).
Node.js ≥ 18.20.8 (20 or 22 recommended) and npm on your local machine.
Basic command-line familiarity.

Part 1 — Configure WordPress

1. Set permalinks

Go to Settings → Permalinks and choose Post name (/%postname%/). Pretty permalinks are required for the GraphQL endpoint and for Soames’ URL routing.

2. Install the required plugins

WPGraphQL (from the WordPress.org plugin directory) — exposes the GraphQL API at https://your-site.com/graphql.
Soames (the soames-wordpress-plugin) — adds the Soames settings, the site-assets REST endpoint, the Header/Footer menu locations, the hero header controls (title, caption, background image, overlay), the Soames content blocks, and the Documentation post type.

3. Activate the Soames WordPress theme

Activate the Soames theme (soames-wordpress-theme). It’s a minimal classic theme that enables the features the front end relies on — custom logo, featured images, page excerpts, and the menu locations.

4. Configure Soames settings

In the admin sidebar, open the Soames menu and set the front-end URL, logo, favicon, company name (and whether to show it), and the footer contact blurb.

5. Choose your homepage and blog page

Under Settings → Reading, select “A static page” and set a Homepage and a Posts page. The Posts page is special: its slug sets the blog’s URL (a page slugged blog → /blog/), and its Hero Header settings drive the blog.

6. Create your menus

Under Appearance → Menus, build your menus and assign them to the Header Menu and Footer Menu locations.

7. (Optional) Per-page hero settings

On any Page or Post, use the Hero Header panel in the editor sidebar to set the hero Title (blank falls back to the page title; HTML such as <br> is allowed), an optional Caption (blank shows no caption), a Background image (falls back to the featured image), and the Overlay opacity that keeps the title readable. See Editor Guide → Using the Hero Header Settings for details.

8. Add content

Create your Pages, Posts, and Documentation articles. Documentation has its own admin menu; use the Page Attributes → Parent and Order fields to build the docs hierarchy and ordering — that structure becomes the documentation sidebar on the front end.

Behind a firewall or CDN? Some security plugins (e.g. Wordfence) block GraphQL requests, and HTTPS sites need their WordPress/Site Address set to https. If the front end can’t load content, confirm https://your-site.com/graphql returns data and that any WAF allows it.

Part 2 — Run Soames locally

1. Get the project

git clone <your-soames-site-repo> soames-site
cd soames-site

2. Point it at your WordPress

Create a .env file with your WPGraphQL endpoint:

# .env
WORDPRESS_GRAPHQL_URL=https://your-site.com/graphql

This is read by astro.config.mjs, which registers the Soames theme integration:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import soamesTheme from 'soames-astro-theme';

export default defineConfig({
  output: 'static',
  integrations: [
    soamesTheme({ wordpressUrl: process.env.WORDPRESS_GRAPHQL_URL }),
  ],
});

3. Select your Node version and install

nvm use            # uses .nvmrc (Node 22); or: nvm use 22
npm install

4. Start the dev server

npm run dev

Open http://localhost:4321. The site is now reading live content from your WordPress.

5. Build for production

npm run build      # static output in dist/
npm run preview    # serve the production build locally

Verify your setup

/ shows your Homepage.
Your Posts page slug (e.g. /blog/) lists your posts.
Header/Footer menus, logo, and footer blurb appear as configured.
Editing content and refreshing reflects the change. Restart npm run dev after adding or removing pages/posts so new routes are generated.

Troubleshooting

Astro won’t start / Node error — you’re below Node 18.20.8; run nvm use 22.
No content / build errors — check WORDPRESS_GRAPHQL_URL is correct and reachable, and that WPGraphQL is active.
Logo/footer missing — confirm the Soames settings are filled in and the plugin is active.

Documentation