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 (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

The order matters — install WPGraphQL first.

WPGraphQL — from the WordPress.org plugin directory: Plugins → Add New, search WPGraphQL, then Install and Activate. It exposes the GraphQL API at https://your-site.com/graphql. Soames declares it as a required plugin, so WordPress will refuse to activate Soames until this is in place.
Soames — download soames-wordpress-plugin.zip, then use Plugins → Add New → Upload Plugin, install, and Activate. A Soames menu appears in the admin sidebar. That link always serves the newest release, so there is no version number to remember.

The 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, previews, and the Knowledge Base post type.

There is no separate Soames WordPress theme to install. Earlier versions shipped a small companion theme; since Soames 1.0.0 the plugin does that work itself — it declares the featured-image and page-excerpt support the front end relies on, and it redirects anyone who lands on WordPress directly over to your published site. Keep whatever theme you like active. If you are upgrading from 0.9.0, you can simply deactivate the old Soames theme.

See the download page for the full install walkthrough, the plugin/front-end compatibility table, and how updating works — Soames isn’t in the WordPress.org directory, so updates are manual and nothing in your dashboard will prompt you.

3. 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. The front-end URL matters most: the redirect and the preview button both depend on it.

4. 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.

5. Create your menus

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

6. (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 → Hero Header Settings for details.

7. Add content

Create your Pages, Posts, and Knowledge Base articles. The Knowledge Base lives under the Soames menu; use each article’s Page Attributes → Parent and Order fields to build the hierarchy and ordering — that structure becomes the sidebar navigation on the front end, under /docs/.

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. Create your project from the starter

Start from soames-astro-starter, a GitHub template repository. On that page click Use this template → Create a new repository to get a repo of your own with no shared history, then clone it:

git clone https://github.com/your-username/your-site.git
cd your-site

Prefer the command line? Clone the starter directly and start your own history:

git clone https://github.com/orbivision/soames-astro-starter.git your-site
cd your-site
rm -rf .git        # drop the starter's history
git init           # start your own

The starter is deliberately minimal — the theme package provides every route, layout, and component, so what you clone is the configuration that points it at your WordPress.

2. Point it at your WordPress

Copy .env.example to .env and set 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

Deploy that dist/ directory to any static host. Developer Guide → Deploying Soames to Netlify walks through one host end to end, and Setting Up a Publish Webhook covers rebuilding automatically when you publish.

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.
“WORDPRESS_GRAPHQL_URL is not set” — the starter stops rather than build an empty site. Create .env as in step 2, or set the variable in your host’s build environment.
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.
WordPress won’t activate Soames — WPGraphQL isn’t installed and active yet. It has to come first.

Documentation