DEV Community: Seppe Gadeyne

Run Qwen3.8-Flash-Next Locally with EXL3 and TabbyAPI on 40+ GB of RAM

Seppe Gadeyne — Sun, 04 Oct 2026 17:09:23 +0000

Qwen3.8-Flash-Next is a 125B mixture-of-experts model, and you can run it locally on one consumer GPU. This guide shows the exact route we use on our own workstation: TabbyAPI as the server, ExLlamaV3 as the inference engine, and turboderp's 3.05 bpw EXL3 quant. The machine is a Ryzen 9 9950X3D with an RTX 5090 (32 GB), 64 GB of DDR5-6000, and Arch Linux. Every number below was measured on that machine. Where a figure comes from someone else, I name the source.

You get an OpenAI-compatible endpoint on localhost that serves a 262,144-token context at about 50 tokens per second. The trade-off: the model needs more than your GPU alone. About 26 GB sits in VRAM, and about 43 GB of expert weights live in system RAM, where the CPU computes them. That is why the title says 40+ GB of RAM. In practice, plan for 64 GB installed.

What Qwen3.8-Flash-Next is

Qwen3.8-Flash-Next is an open-weight model from the Qwen team. The model card lists 125B parameters, of which about 6B are active per token, plus a 51B n-gram embedding table and a 4B multi-token prediction (MTP) layer. Each of the 48 layers has 512 routed experts, and 10 of them are picked per token.

That design makes it a good fit for a single GPU with CPU offload. Only a small part of the model does work for each token, so the experts that are rarely used can sit in system RAM without slowing every step. The n-gram table is a lookup, not a compute step, and ExLlamaV3 can stream it from disk.

Why EXL3 and TabbyAPI

EXL3 is the quantization format of ExLlamaV3. According to the project README, it is a streamlined variant of QTIP, a trellis-based method from Cornell RelaxML. The practical gain is quality per bit. On the model page of the EXL3 quants, turboderp publishes a KL divergence chart for this model. The 3.05 bpw quant scores 0.0177 there, against 0.0349 for the UD-IQ3_XXS GGUF quant at a similar size. Lower means closer to the original model.

TabbyAPI is the official API server for ExLlamaV3. It exposes an OpenAI-compatible API, so editors, chat clients, and agent frameworks that speak that API can use your local model without code changes. It also wires up the ExLlamaV3 options this model needs: CPU expert offload, the n-gram table, and MTP drafting.

Hardware requirements

This is the hardware we measured on, and what the model used:

GPU: RTX 5090 with 32 GB of VRAM. About 26 GB in use with the config below.
System RAM: 64 GB of DDR5-6000. About 43 GB resident for the CPU expert arena.
CPU: Ryzen 9 9950X3D (16 cores, 32 threads). The CPU computes the cold experts, so core count matters.
Disk: an NVMe drive with room for the 85.1 GB download. The n-gram table is read from it during inference.
OS: Arch Linux with a current NVIDIA driver.

Two things did not work well. With 60 GB of RAM it gets tight as soon as a browser and other heavy programs run next to the model. And once part of the arena lands in zram or swap, decoding collapses, as described in the pitfalls below. Treat 64 GB as the realistic minimum for this configuration, and run the model on a machine that is not doing other heavy work at the same time.

Install TabbyAPI with the prebuilt exllamav3 wheel

Clone TabbyAPI and create a Python 3.11 virtual environment inside it:

git clone https://github.com/theroyallab/tabbyAPI
cd tabbyAPI
python3.11 -m venv .venv
source .venv/bin/activate
pip install -U ".[cu12]"

The cu12 extra installs PyTorch 2.9.0 (CUDA 12.8) and the prebuilt exllamav3 1.5.1 wheel for your Python version. At the time of writing, TabbyAPI's main branch pins exllamav3 1.5.1. Check that both landed:

pip show exllamav3 torch | grep -E '^(Name|Version)'
python -c "import torch; print(torch.cuda.is_available())"

You should see exllamav3 at 1.5.1+cu128.torch2.9.0 and True for CUDA.

Use the prebuilt wheel rather than a just-in-time (JIT) build. The wheel is faster to set up, and on our system the JIT build of the CUDA extension broke on GCC 16. That build only went through after adding -Xcompiler -Wno-template-body to the compiler flags. With the wheel you skip the whole problem.

Download the 3.05 bpw EXL3 quant

The quants live in one Hugging Face repository, with one branch per size. This guide uses the 3.05bpw_h5_ng5 revision: 3.05 bits per weight for the experts, a 5-bit output head, and a 5-bit n-gram table.

hf download turboderp/Qwen3.8-Flash-Next-exl3 \
 --revision 3.05bpw_h5_ng5 \
 --local-dir models/qwen3.8-flash-next-exl3-3.05bpw

The hf command comes with huggingface_hub, which TabbyAPI installs into the venv. Older guides use huggingface-cli download, but recent huggingface_hub versions no longer run that command. TabbyAPI also has its own downloader (./start.sh download <repo> --revision <branch>) if you prefer that.

The download is 85.1 GB. One file stands out: ngram_embedding.safetensors is 32.6 GB on its own. Keep the folder on NVMe, because that table is streamed from disk while the model runs. The folder name becomes the model name in TabbyAPI.

Configure config.yml and a sampling preset

Copy config_sample.yml to config.yml and change the keys below. The rest can stay at the defaults. These are the values we run and measured:

network:
 host: 127.0.0.1
 port: 5000
 disable_auth: true

model:
 model_dir: models
 model_name: qwen3.8-flash-next-exl3-3.05bpw
 backend: exllamav3
 max_seq_len: 262144
 cache_size: 262144
 cache_mode: Q8
 gpu_split_auto: true
 autosplit_reserve: [1000]
 cpu_moe_split_experts: 400
 cpu_moe_threads: 24
 ngram_ram: false
 reasoning: true

draft_model:
 draft_mode: mtp
 draft_num_tokens: 4
 dynamic_draft: true

sampling:
 override_preset: qwen3_8_flash_next

What the important keys do:

backend: exllamav3 selects the engine. The value is exllamav3, not exl3.
cpu_moe_split_experts: 400 keeps the 400 coldest of the 512 experts per layer in system RAM and computes them on the CPU. The hot experts stay in VRAM, and ExLlamaV3 adjusts the placement while it runs.
cpu_moe_threads: 24 sets the CPU worker threads for those experts. Without it, ExLlamaV3 uses half the core count.
ngram_ram: false streams the 51B n-gram table from disk. Loading it into RAM would need tens of gigabytes more than a 64 GB machine has left.
cache_mode: Q8 stores the KV cache in 8 bits instead of 16, which halves its size for the full 262,144-token context.
autosplit_reserve: [1000] leaves 1,000 MB of VRAM free on the GPU for the desktop and CUDA overhead.
draft_mode: mtp uses the model's own MTP layer for speculative decoding. No separate draft model is needed.
disable_auth: true is only acceptable because the server listens on 127.0.0.1. If you open it to your network, turn authentication back on.

Now create the sampling preset in sampler_overrides/qwen3_8_flash_next.yml. TabbyAPI finds it by name in that folder:

temperature:
 override: 0.7
 force: false
top_k:
 override: 20
 force: false
top_p:
 override: 0.95
 force: false
min_p:
 override: 0.0
 force: false

These values are fallbacks. A request that sends its own sampler settings still overrides them. Skipping this preset is one of the pitfalls below.

Start the server and send a first request

Start TabbyAPI from the project folder with the venv active:

python main.py

From a warm NVMe, the model is loaded in about two minutes on our machine. A first load from a cold disk can take longer. Check that the server is up and the model is loaded:

curl -s http://127.0.0.1:5000/health
curl -s http://127.0.0.1:5000/v1/models

Then send a first chat request to the OpenAI-compatible endpoint:

curl -s http://127.0.0.1:5000/v1/chat/completions \
 -H "Content-Type: application/json" \
 -d '{
 "model": "qwen3.8-flash-next-exl3-3.05bpw",
 "messages": [{"role": "user", "content": "Write a Python function that checks whether a string is a palindrome."}],
 "max_tokens": 4000
 }'

The model reasons before it answers. TabbyAPI splits that reasoning into a separate reasoning_content field, and the answer arrives in content. Note the high max_tokens. The reason is explained in the pitfalls.

The server log prints the speed per request, and with MTP drafting also the acceptance rate of the drafted tokens. That log is the source for all the measurements in the next section.

Performance tuning: our measured A/B results

We tuned three settings one at a time, with greedy decoding, reading the figures from the TabbyAPI server log. All runs were done with nothing else heavy running on the machine.

CPU threads for the expert arena

The thread count for the CPU experts had the biggest effect on decoding. More threads is not always better: at 32 threads the SMT siblings compete for the same cores, and decoding got slower than at 24.

Decode speed by cpu_moe_threads (median, tokens per second)

cpu_moe_threads	Decode (tok/s)	Note
16	48.1	Fewer threads than the CPU can feed
24	51.7	Best result; prefill 188 tok/s in this run
32	47.6	Slower due to SMT contention

On a 16-core, 32-thread CPU, 24 threads was the sweet spot. On a different CPU, run the same test with your own core count.

How many experts go to the CPU

In a separate A/B run, we lowered cpu_moe_split_experts from 430 to 400. That puts 30 more experts per layer on the GPU. Decoding stayed the same, prefill rose from 174 to 204 tokens per second, and the machine kept about 2 GB more free RAM. With 32 GB of VRAM, 400 fit with the 1,000 MB reserve. On a card with less VRAM you need a higher value, which means more RAM.

Draft depth for MTP speculative decoding

With MTP drafting, the model proposes several tokens ahead and verifies them in one pass. draft_num_tokens: 4 with dynamic_draft: true gave the best result. A draft depth of 6 was 4% slower. The acceptance rate stayed around 56–58%, so longer drafts mostly produced more tokens that were thrown away.

The end result on our machine

With all three settings in place, we see about 48–52 tokens per second for decoding and about 175–205 tokens per second for prefill. The model loads in about two minutes from a warm NVMe. These figures were measured without other heavy workloads running.

For context: the ExLlamaV3 1.5.0 release notes list higher numbers for this model on an RTX 5090 paired with a Threadripper 7960X, with the n-gram table in RAM and a pinned arena. That is different hardware with more memory and different settings, so do not treat our numbers as the ceiling, or theirs as what a 64 GB desktop will reach.

Pitfalls we ran into

Swap kills decoding

If part of the expert arena is pushed into zram or swap, decoding falls from about 50 to about 2.4 tokens per second. The model keeps running, so it is easy to miss. Check how much of the process sits in swap:

grep VmSwap /proc/$(pgrep -f "python main.py")/status

Anything far above zero means the arena no longer fits. Close other programs, keep an eye on free RAM with free -g, and do not start the model next to other memory-hungry work.

No sampling preset, no stable output

Without a sampling preset, requests that send no sampler values run with top_k 0 and top_p 1. In that state the model can drift into other languages mid-answer. The preset from step 03 (temperature 0.7, top_k 20, top_p 0.95) works well and keeps clients that send nothing on safe values.

Reasoning eats max_tokens

Qwen3.8-Flash-Next thinks before it writes the answer, and those reasoning tokens count toward max_tokens. With a low limit, the response can stop before the actual answer starts, leaving content empty. Use at least 400 tokens, and 4,000 for real tasks.

Small config mistakes

backend must be exllamav3; exl3 is not a valid value. And run this model on its own: a second model, a game, or another GPU workload on the same machine takes VRAM or RAM the model needs.

What it gets you

The result is a strong coding model on hardware you control. On the Qwen model card, Qwen3.8-Flash-Next scores 58.7 on DeepSWE 1.1 and 62.5 on SWE-bench Pro. Those are the Qwen team's figures for the full model, not measurements of this quant. In our own comparison, it is the strongest model for coding tasks that we can run on this consumer machine. Nothing leaves your network, there is no per-token bill, and any tool that speaks the OpenAI API can connect, from a code editor to an AI agent running a workflow.

Alternatives worth considering

This setup is not the only route, and it is not always the best one:

A smaller quant. The same repository has a 2.05 bpw version that needs less memory, at a clear cost in quality: turboderp's chart shows a KL divergence of 0.0684 for it, against 0.0177 for 3.05 bpw. We did not measure its speed or memory use.
GGUF with llama.cpp. This route runs on more hardware, including Macs and CPU-only machines, and Unsloth publishes GGUF quants with a run guide. In our comparison, that route was slower on this model than ExLlamaV3.
A cloud API. If you do not have the hardware, or only need the model now and then, a hosted API costs less than a new GPU and a RAM upgrade. You give up the privacy and fixed costs of a local setup.

Wrapping up

The short recipe: TabbyAPI in a Python 3.11 venv with the prebuilt exllamav3 1.5.1 wheel, the 3.05bpw_h5_ng5 quant on NVMe, backend: exllamav3, 400 experts per layer on the CPU with 24 threads, a Q8 cache, MTP drafting with 4 tokens, and a sampling preset. Watch swap, give reasoning room, and run the model on its own. On one RTX 5090 with 64 GB of RAM, that gives a 125B model at about 50 tokens per second. ExLlamaV3 and TabbyAPI move quickly, so check the ExLlamaV3 releases for new versions before you start.

If you are wondering what hardware you actually need before AI can run locally in your business, we wrote a practical guide about that too: What computer do you really need to run AI locally? — it covers the trade-offs between local and cloud AI for business use.

A website without a CMS: Astro Content Collections in practice

Seppe Gadeyne — Thu, 01 Oct 2026 07:42:14 +0000

I moved straffesites.com from Astro with Storyblok to Astro Content Collections with local MDX and JSON files. The site still has articles, case studies, landing pages, and Dutch and English versions. What it no longer has is a separate CMS for managing that content.

I am the only person managing the content on straffesites.com, and I work with Hermes, an AI agent. Since I already work in Git, moving the content there was a useful simplification. Content changes now go through the same repository and build pipeline as template changes. I can inspect a paragraph edit next to the schema or component it depends on.

This is a case study of that setup: how the content is organized, what the schemas check, how publishing works, and which CMS features I chose to give up. It is not a recommendation to make every editor learn Git.

Why I removed Storyblok from this project

Astro and Storyblok worked well together. I still use that combination for client projects where an editing interface is useful. On straffesites.com, however, I am the only human editing and managing the content. Hermes helps me work with the files and run checks. I did not need a visual editor for that workflow.

Keeping a CMS meant maintaining content models in another system, managing my CMS account and its permissions, and configuring the integration that fetched content during builds. Code lived in Git; content lived in Storyblok. Changes that touched both required checking both.

Working with Hermes was another part of the decision. The agent could already read the project, edit files, and run checks. To work with CMS content, it also needed an authenticated client and a separate content workflow. That integration was possible, but it was unnecessary for this project.

Moving the content into Git removed the CMS-specific access layer. It did not remove repository permissions, deployment credentials, or the need to maintain the AI tooling.

Content Collections provide a content layer, not an editor

Astro Content Collections let you organize, validate, and query structured content. They can use local files, remote sources, or live data. The setup on straffesites.com uses local files loaded at build time:

MDX for pages and articles.
JSON for datasets, case metrics, people, and site settings.

Those are six collections in this project. You do not need that exact split to use the same approach.

A collection combines a loader with a schema. The loader finds the entries; the schema defines the fields the templates can expect. Here is an excerpt from the article collection configuration:

import { defineCollection, reference } from 'astro:content';
import { glob } from 'astro/loaders';
import { articleFrontmatterSchema } from './content/schemas/article';

const articles = defineCollection({
  loader: glob({ pattern: '**/*.mdx', base: './src/content/articles' }),
  schema: articleFrontmatterSchema.safeExtend({
    author: reference('people').optional(),
  }).superRefine((article, context) => {
    if (article.articleType !== 'glossary' && !article.author) {
      context.addIssue({
        code: 'custom',
        path: ['author'],
        message: 'blog and case articles must include an author',
      });
    }
  }),
});

// The full configuration also registers the people collection.
export const collections = { articles /*, pages, datasets, caseMetrics, people, settings */ };

This is a project-specific excerpt, not a complete starter configuration. It imports the article schema from another file, and the author reference depends on the people collection being registered in the full configuration.

The same article collection holds blog posts, case studies, and glossary entries. The refinement requires an author for blog posts and cases while allowing glossary entries without one.

What validation catches

The frontmatter schema defines fields such as the title, route, publication date, category, tags, summary, and FAQ items. Required fields must be present. A strict schema also rejects unknown field names, so a typo cannot silently become unused metadata.

That gives the templates a defined content contract. It does not make the article correct.

A schema can reject a missing title or a value that violates a configured rule. It cannot establish that an explanation is accurate, a source supports a claim, or an internal link is helpful. A nonempty summary also does not imply a sensible length unless you add a length limit.

I use additional contract tests and build-output checks for rules that go beyond frontmatter. Content Collections alone do not check every link, component choice, or editorial requirement.

What you lose without a CMS

There is no visual editor in this local-file setup. Content Collections do not provide editor accounts, approval screens, a media library, or a publishing calendar.

You can add previews and access controls around a Git workflow. You can also put a Git-based CMS in front of the files. That is a valid option, but it adds an editing interface; it is different from editing the files directly.

How I organize the content

The MDX files on straffesites.com are grouped by language and content type:

src/content/
├── pages/            # landing pages and hub pages (MDX)
│   ├── nl/           # Dutch-language pages
│   └── en/           # English pages
└── articles/
    ├── nl/
    │   ├── blog/      # blogs
    │   ├── case/      # case studies
    │   └── begrippen/ # glossary terms
    └── en/
        ├── blog/      # blogs
        ├── case/      # case studies
        └── glossary/ # glossary terms

The JSON collections sit alongside these directories. The tree above only shows the MDX content.

Each MDX entry starts with frontmatter. The body uses Markdown inside typed content-block components. On the original website, for example, this article's source file contains its metadata and body, while the page template renders shared elements such as the author card and related articles. The DEV version you are reading is an adapted Markdown crosspost, not that MDX file running inside Astro.

For this project, the route comes from an explicit frontmatter field rather than the file's location. That lets me reorganize source files without treating every move as a URL change. The templates and tests still need to respect that convention; Astro does not infer the project's routing rules from the directory tree alone.

Keeping translations connected

Dutch and English pages have a shared pair registry in the repository. It records which routes are counterparts.

Build checks can then verify that those routes exist and that the relationships are consistent. The files being next to each other is not enough: translation pairing is a rule I have to define and test.

This is one advantage of keeping content and code together. The content, route relationships, and checks can change in the same diff.

Publishing is a deployment workflow

On straffesites.com, a push to main triggers a Vercel build and deployment. Astro validates the content and renders static pages. A local commit by itself does not publish anything.

The workflow is straightforward:

Edit MDX or JSON
    -> inspect the diff
    -> run content and build checks
    -> commit and push
    -> verify the deployment

That diagram describes the work to do, not a security guarantee. Git does not force someone to inspect a diff, and a schema does not require human approval. Repository permissions and required checks determine what can reach production.

Git also makes rollback understandable: revert the relevant change, build again, and deploy the result. Reverting a commit locally does not change the live site until the reverted version is deployed successfully.

The maintenance moves rather than disappearing

Concern	Local content in Git	API-first headless CMS
Editing	Files and repository tooling	CMS dashboard
Content validation	Configured schemas and project checks	CMS field rules; project checks can also apply
Content history	Diffs for committed changes	CMS revisions, depending on the platform
Static publishing	Build and deploy after a repository change	Build and deploy after a CMS content change
Systems to maintain	Dependencies, CI, hosting, and repository access	Those systems plus the CMS integration and accounts

These are common workflows, not fixed limits. A headless CMS can feed a fully static site, and a Git-based CMS can provide a dashboard while keeping content in files.

How I work with Hermes

Hermes is the AI agent I work with on this project, not another human editor. It can read an MDX file, update a paragraph, and run the same checks used for code changes. It does not need a CMS-specific API key to edit checked-out files.

For me, the useful part is how easy the changes are to inspect. A content edit can include its frontmatter, body, and related template changes in one diff. There is no separate CMS revision to reconstruct alongside the code change.

Reading a local file avoids a CMS API request. It does not make model usage free: text sent to the model still consumes tokens. Nor does it prove that agents perform better with files than with a CMS.

Instructions are not access controls

Project instructions can tell an agent which files to use, which commands to run, and what it must not change. They help it work within the project's conventions. They are not a security boundary.

An agent with broad repository or deployment access can still make harmful changes. Limit its permissions, make checks explicit, and verify what it changed. For straffesites.com, I remain responsible for the scope and the published result, including when I authorize Hermes to deploy after checks.

Plausible but false prose can pass every schema check. That is an editorial review problem, not something Zod can solve.

Removing a CMS does not automatically make a website faster

I track straffesites.com through monthly PageSpeed measurements and Search Console data on its public case page. Those measurements describe the deployed site. They are not a controlled test of whether removing Storyblok improved performance.

A headless CMS can supply content during the build and produce the same static HTML. Visitors do not necessarily make a CMS request when they open that page.

Removing the CMS API from my build reduced an external build dependency. Visitor performance still depends on the output: JavaScript, images, fonts, caching, and how the page renders.

The change I can describe directly is operational. My content workflow no longer needs a CMS service, a separate editor account, or a CMS integration. Dependencies, hosting, and access control still need maintenance.

When I would keep the CMS

For a client project, I would keep a CMS when the editing interface solves a problem the client or their editorial team actually has.

If editors do not work in Git, asking them to maintain MDX may just move the burden onto them or the development team. Draft states, permissions, scheduling, and media management are useful features, especially when several people publish regularly.

Translation workflows can also be more involved than maintaining two files and a route pair. Editors may need field-level translation status or separate approval steps. A CMS can provide those workflows without requiring the team to build them.

Changing a content model is another consideration. In my setup, adding a new content type means changing a schema and its templates. A CMS dashboard may make field management easier, although frontend changes can still require development work.

You can build versions of these features around Git. But if you need an editor, scheduling, media permissions, and approval screens, consider whether you are rebuilding the CMS you removed.

For straffesites.com, direct file editing fits how I manage the content with help from Hermes. For a client with an editorial team, I may choose a CMS instead. I would start with who edits the content and what their publishing process needs, then choose the storage and tooling.

Adapted for DEV from A website without a CMS: Astro Content Collections in practice, originally published on straffesites.com.

Automating SEO with AI: a self-improving content loop

Seppe Gadeyne — Mon, 28 Sep 2026 11:52:53 +0000

Everyone agrees you should "let AI do your SEO." Few people explain what that looks like when you actually build it. This is the setup I run on my own site: an AI agent with read-only access to Google Search Console, a dedicated service account via gcloud, and one small, verified improvement per run — every thirty days.

The article below is a crosspost from my site. It covers the full loop: setup, prioritization, one-change-per-run, measurement, and the honest learning curve before anything runs on its own.

Automating SEO with AI, in practice, means: an AI agent with read access to your Google Search Console that pulls the real search queries from your data every thirty days and makes one small, verified improvement to your pages. That is not a robot that lifts your website to the top of Google while you drink coffee — that robot does not exist. It is a loop: pull data, prioritize, improve, measure, and again thirty days later. Not everything at once, not on a hunch — one thing per run, measured and logged.

That approach works because SEO is not a one-time project but a habit. Anyone who looks at the same data every month and makes one targeted intervention each time will see their pages gradually align better with what people actually search for. The agent makes that habit affordable: it does the heavy lifting — pulling data, prioritizing, preparing — while you make the decisions. At first you supervise every run. After a few months, most of it runs automatically on a cron job.

Why automating SEO with AI makes sense now

An agent like Hermes can query an API, read and write files, run a build, and inspect the result. For recurring GSC analysis, I combine those tools with a dedicated service account: gcloud handles the Cloud setup, and Search Console grants that account read access to the property. The agent can then retrieve data without waiting for me to sign in through a browser again.

SEO is an ideal application for this, for three reasons:

The source data is objective. Search Console shows literally how people find you: queries, impressions, clicks, positions. That gives the agent source data, but does not prevent hallucinations or incorrect interpretation. Check its conclusions against the export; anonymized queries and API limits make the data incomplete.
The feedback loop already exists. Thirty days after every change you see in the same data whether it had an effect. That is a perfect learning loop for a step-by-step process.
The work is repetitive but requires judgment. Pulling and organizing data is pure routine. Interpreting and prioritizing takes judgment. That exact mix is where a supervised agent shines.

Done manually, most people pick this up once a quarter with a spreadsheet and good intentions. The agent turns it into a fixed rhythm — and rhythm is the most underrated success factor in SEO.

What you need: gcloud, GSC access, and an agent

For scheduled SEO runs, I use gcloud with a dedicated service account. The agent gets its own Google identity, added as a read-only user to the Search Console property, rather than relying on my personal login. You need:

A Google Cloud project and gcloud, with an administrator who can enable the Search Console API and create the service account.
A Search Console property owner who can add that account under Users and permissions.
An agent that can use tools, such as Hermes from Nous Research, Claude Code, Cursor agents, or your own application around a language model.
A git repository for small, reviewable website changes, separate from the Google credentials.

Create a dedicated service account with gcloud

Run these setup commands as a human administrator with the required Cloud permissions. Replace YOUR_PROJECT_ID with your existing project ID; the example account name is seo-reader:

gcloud services enable searchconsole.googleapis.com iam.googleapis.com \
  --project=YOUR_PROJECT_ID
gcloud iam service-accounts create seo-reader \
  --display-name="SEO read-only access" \
  --project=YOUR_PROJECT_ID

The account's email address will be seo-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com. Do not give it broad Cloud Owner or Editor roles. A Cloud IAM role does not grant access to your Search Console property; you add that separately. If it needs permission to consume the quota project, grant the narrow Service Usage Consumer role there, not project-wide administration. See Google's service account setup guide.

Add the service account as a restricted GSC user

In Search Console, the property owner opens the exact property, then Settings → Users and permissions → Add user. Enter the service account's full email address, choose Restricted, and add it. You do not need to make the account an owner or verify the domain again. Google's permissions table confirms that Restricted users can read the Performance report, which is what this loop needs.

Configure the API client to request https://www.googleapis.com/auth/webmasters.readonly, as documented in Search Console authorization. The property role limits what the account can do; the OAuth scope limits what its API token can do. That scope is not tied to one website, so add the account only to properties the workflow needs. A domain property uses an identifier such as sc-domain:example.com; a URL-prefix property uses its exact URL prefix.

Run without a recurring personal login

Use an attached service account or Workload Identity Federation when the runtime and GSC client support it. These avoid storing a long-lived private key. If your local runner needs a JSON key, create one in Google Cloud under the service account's Keys → Add key → Create new key. Follow your organization's key policy and store the file outside your repository. The following path is a placeholder for that protected file:

chmod 600 /secure/path/seo-reader.json
export GOOGLE_APPLICATION_CREDENTIALS="/secure/path/seo-reader.json"
export GOOGLE_CLOUD_QUOTA_PROJECT="YOUR_PROJECT_ID"

Set these variables in the environment that actually starts the agent or its GSC connector, including scheduled runs. A cron job does not automatically inherit your interactive shell's exports. Use a client that supports Application Default Credentials (ADC), with the read-only scope above. ADC locates the credentials; it does not choose the permissions for you. ADC and the gcloud CLI also use separate credential configurations: being logged into gcloud does not configure the application's credentials.

Google's authentication library obtains and renews short-lived access tokens for the service account without an interactive browser login. Personal OAuth can also refresh tokens, but it ties the job to a person's authorization. A service account removes that dependency, making unattended runs easier to maintain. It is not maintenance-free: rotate keys, revoke unused credentials, and review access. Keep keys and tokens out of prompts, logs, Git, and browser code; Google's key-management guidance explains the risks.

Before scheduling the loop, run a small Performance-data query through the same client and environment the scheduled job will use. Confirm the intended property and service account, and stop if access fails rather than falling back to your personal credentials. Isolate the runner from other credentials too. Website changes still go through your codebase and review flow; GSC read access does not authorize publishing.

The loop: pull the data

Every run starts the same way: the agent pulls fresh Search Console data for a bounded period — say the last thirty days, or a comparison with the thirty days before that. It requests the top queries per page, with impressions, clicks, CTR, and average position, and writes that away as a structured file in the repo. From that moment it no longer works with live APIs but with a snapshot you can inspect and compare against previous runs.

One important detail: Search Console data only becomes final after a few days. Google itself says about fresh data points: "Each fresh data point will be replaced with the final data point after a few days" (Google Search Central Blog on data freshness). Measure too early and you draw conclusions from numbers that still shift. That is why the agent works with closed periods and preferably compares month over month, never day over day.

Prioritize: where is the biggest win?

With the data on the table, the agent looks for patterns worth a decision:

Many impressions, few clicks on a query your page already ranks for: usually a title or meta description problem, not a content problem.
Position 8 to 20 with a declining trend: the page is relevant enough to rank but not convincing enough to break through. Sharpening the search intent and internal links helps here.
Queries you have no good page for: content gaps. Those lead to a new article or an expansion of an existing page — not keyword stuffing on some random page.
Multiple pages competing for the same query: cannibalization. Strengthen one page, give the other its own angle.

For each finding the agent states a hypothesis: this page, this query, this expected intervention, this expected effect. No more than one or two per run. If you change ten things at once, you will never know what worked.

Make one small improvement

Then comes the human moment. The agent prepares the change — a rewritten intro that puts the real search intent first, a better title tag, an internal link from a strong page — and for now you always review it. The change is deliberately small: one page, one aspect, describable in one sentence. "This intro now promises what the searcher actually asks for." Not: "The entire page optimized."

Next, the agent verifies its own work. For a website in git that means: commit the change, run the build, fetch the changed route again, and confirm the promised text is actually there. A successful tool call is not a successful task; the run is only complete when the published page checks out.

Measure and log

Every run ends in a log: what the agent saw in the data, what it changed, what the expected effect is, and when to check it. Ideally in your issue tracker, so that thirty days later an on-the-record comparison is possible. Did the intervention raise the CTR on that one query? Did the position move from 14 to 9? Or did nothing happen — and why not?

That logging is not administrative luxury. It is the only way to learn from the agent and to teach the agent. Because every time a hypothesis does not pan out, it says something about your instructions: was the prioritization wrong, the intervention too small, or the expectation too high?

Repeat every 30 days

A single run does little. The power is in the repetition. After six cycles you have six verified improvements, six measurement moments, and a growing archive of what did and did not work. Along the way your pages have gradually been tuned to the real search intent of your visitors — not to your assumption of what they search for, but to what the data shows they search for.

Why thirty days and not every week? Because Search Console data only finalizes after several days and positions show too much noise week over week. Thirty days gives a signal you can act on, and it matches the pace of content changes: thorough enough to matter, slow enough to measure cleanly.

From supervising to automatic: be realistic

This needs honesty: the first time, this does not work. The first run of a new agent rarely produces anything publishable. The data gets misinterpreted, the prioritization misses, the proposed copy reads like a committee memo. That is not the concept failing — it is the onboarding period.

This is an illustrative three-phase plan, not a measured timeline or guarantee. Automate only after repeated tests show that the workflow is reliable enough:

Phase	What you do	What the agent does
Months 1–2	Supervise every run, correct every change, rewrite instructions	Pull data, draft the analysis, make mistakes
Months 3–4	Review results, feed in edge cases	Prepare complete runs, propose improvements with reasoning
Months 5+	Check in occasionally, judge escalations	Run on schedule by itself, ask for human input when in doubt

How you speed up that curve: give the agent skills. An agent like Hermes works with reusable instruction packages — how to structure a page audit, how to interpret search intent, how to rewrite a title without clickbait. You teach those once, and every next run builds on them. After a few months those skills are the difference between an intern and a colleague: the process is in its fingers, and you only look over its shoulder for the hard cases.

From that moment on, you turn the loop into a cron job: a scheduled task that runs the agent on a schedule — say the first of every month. The run follows the same rules as when you sat next to it, only without you having to be there. Hard decisions (new pages, major rewrites, anything touching money or reputation) stay explicitly human.

Skills: teaching the agent how to run SEO audits

The fastest way to climb that curve: give the agent skills — reusable instruction packages that describe one task in detail. A skill for a page audit specifies exactly what data gets pulled (live HTML, Search Console rows, robots.txt), which dimensions get scored (search intent, E-E-A-T, content depth, on-page, structure, technical), with what weights, and in what format the report appears. You write such a package once, or teach it from an existing collection. I've documented that installation route step by step in Hermes Agent for SEO: from Search Console to a blog post: installing the agent, connecting Search Console through gcloud, and adapting the SEO skills for it. After that, the agent runs every next audit in exactly the same way — including the cron run in the middle of the night.

The historical audit below shows what such a report looks like. It was recorded on September 2, 2026, before this article switched to the service account setup. Its earlier authentication advice is preserved as part of the original output; follow the updated setup above for new runs.

On my own site, this article includes the full recorded audit terminal: the complete first run's output, scores, findings, and the GSC baseline of that moment (recorded on September 2, 2026). It's too long to paste here, but you can read it in the original article.

The audit reported that the page had no Search Console data on its publication day instead of inventing numbers. Its scores and baseline describe that moment, not the current page. Each finding comes with a concrete fix. For later changes, record a fresh baseline and wait at least thirty days before assessing the effect.

What an agent may and may not do on its own

Automation without boundaries is a risk, especially on something as visible as your website. A few rules of thumb that work in practice:

Read permissions for data, write access through git. The agent reads Search Console, but every change goes through your codebase and review flow.
Small commits. One change per run, with explanation. Not because the agent cannot do more, but because otherwise you lose the measurement effect.
No invented numbers. Every metric in copy comes from the actual data export, with period and source attached. An agent that smooths over or invents numbers is useless for this work.
Human decisions stay human. Merging pages, restructuring key landing pages, changing prices or promises: do not automate.
Useful stays useful, even at speed. Google's guidance on AI-generated content stresses that automation changes nothing about the requirement that content be made for people and be genuinely helpful — regardless of who or what wrote it.

For a broader look at deploying such an agent without losing control, read What is an AI agent?. And for the bigger picture around recurring work: Workflow automation.

Where the change lands: MCP into your CMS, or Git for your Astro site

So far, every improvement went to "your codebase". But where exactly the agent writes depends on how your website is built — and that is less complicated than it sounds. Broadly, there are two routes.

Route one: your site runs on a CMS. Then you want the agent to work directly in that CMS, and for that you use MCP: the Model Context Protocol, an open standard that connects AI applications to external systems in a structured way. An MCP server for WordPress or Storyblok offers the agent a limited, explicit list of functions — create a draft, update a field, publish a page — with matching permissions. That way the agent can adjust a page on its own after an approved analysis, but only through the doors you open. And because every CMS draft starts as a draft rather than going live immediately, you keep a natural review step.

Route two: your site is static, like this one. Straffe Sites runs on Astro with Content Collections: every page and article is a file in a git repository, with strict schemas as the quality gate. Here the agent does not edit a CMS but the files themselves — update frontmatter, rewrite an intro, add an internal link — and every change goes straight through the schema and build checks. Each run becomes a small commit you can read, revert, or approve. No database, no admin screen; the repository is the CMS.

Both routes end in the same place: one small, verified change per run, with a human eye on it before it goes live.

Plan B if the loop does not take off

Sometimes it does not work. The data is too thin (less than a few hundred impressions a month), the market too competitive, or the agent keeps making silly choices after months of course-correcting. Then the honest conclusion is: automation adds no value here.

But you still win. Because the agent still functions as an analyst: it pulls your data monthly, flags the notable movements, and puts it all in a fixed report. You do the interpretation and the changes yourself, once a quarter. That is not a self-improving loop, but it is a return on your onboarding time — and sometimes that is the realistic picture for a small website. Start small, measure honestly, and let the automation earn what it is worth. And if you would rather build that cycle with guidance than figure it out alone, AI automation with human control is where we help. Doubting the business case? What SEO costs in 2026 lets you compare the agent approach with what freelancers and agencies charge for the same recurring work. Considering an agent beyond SEO, for your whole business? The guide on hiring someone to build an AI agent walks through the signals, costs, and pitfalls.

This article was first published on Straffe Sites.

Google Search Console setup: verification and first checks

Seppe Gadeyne — Fri, 25 Sep 2026 12:38:15 +0000

A deployed site isn't necessarily an indexed site. Google Search Console lets you check what Google has discovered, which pages it has indexed, and which searches bring people to your site.

This guide covers adding a property, verifying ownership, and the first checks I'd make after setup. You need a Google account and access to the site's DNS settings, or help from whoever manages them.

What Search Console tells you

Google Search Console is Google's free tool for tracking search performance. It reports impressions and clicks, the queries behind them, indexing status, and technical issues that may affect visibility.

Google Analytics measures what visitors do on your site. Search Console measures how the site appears in Google Search before they click. They answer different questions. Search Console alone won't tell you whether a visitor submitted a form or became a customer.

Sign in with your Google account

Open Search Console and sign in. Choose an account you'll retain access to. If you're setting this up for a client, make sure they retain ownership rather than leaving access tied only to your account. You can add other users with their own permissions later.

Add your website: domain or URL prefix

Click "Add property" and choose between two types:

A domain property covers the entire domain, including subdomains and both HTTP and HTTPS. Enter the domain without a protocol or path. This requires DNS verification.
A URL-prefix property covers addresses that begin with the exact prefix you enter, such as https://www.example.com/. Use this when you deliberately want to measure one part or version of the site, or need a verification method other than DNS.

For a whole website, I'd usually start with a domain property. Be careful with URL prefixes: https://example.com/ and https://www.example.com/ are different prefixes.

Verify ownership

For a domain property, copy the TXT value Google provides and add it to the DNS records at your DNS provider. Keep existing records intact. Then return to Search Console and click "Verify."

DNS changes can take time. If verification fails, check the record name and value against your provider's instructions before trying again. Keep the verification record after setup so Google can recheck ownership.

A URL-prefix property supports additional methods, including an HTML file or tag, Google Analytics, and Google Tag Manager. Each has its own requirements. Google's verification documentation explains those requirements and troubleshooting steps.

Submit your sitemap

Open "Sitemaps" and submit the actual XML sitemap URL generated by your site. Common paths include /sitemap.xml and /sitemap-index.xml, but check your deployment rather than guessing.

Open that URL yourself first. It should return the sitemap, not an HTML error page or a login screen. A sitemap helps Google discover URLs; it doesn't guarantee indexing.

Inspect an important page

Paste a complete page URL into the URL Inspection field. Start with your homepage and one important content page.

Read the indexed result before running a live test. The indexed result describes Google's stored information; a live test checks the current page. A successful live test doesn't mean the URL is already indexed.

For a new or substantially updated page, you can request indexing through URL Inspection. That is a request, not a guarantee of inclusion or a particular crawl time.

Use the Performance report

Data collection starts when the property is first added to any Search Console account, even before verification. It doesn't recreate search performance from before that first addition.

Once you have enough data, open the Performance report and select "Search results."

Start in the Pages tab. Click a page with substantial impressions, then switch to Queries to see the searches associated with it. Ask whether the page answers what those people are looking for before changing its title or adding content.

Average position isn't a fixed ranking. It combines different searches, and results vary by device, location, and other factors. Likewise, low click-through rate doesn't prove that a title is wrong. Compare similar queries and conditions, then inspect the actual search results.

If you want more context on choosing relevant queries, I've written a guide to keyword research.

Review indexing separately from traffic

The Pages report under Indexing shows which URLs are indexed and which are not, with reasons. "Discovered, currently not indexed" and "Crawled, currently not indexed" can have several causes. Inspect the affected URL and its content before assuming you need a code fix.

The Sitemaps report shows the status of submitted sitemaps and the URLs Google discovered through them. Those discovery counts aren't a count of indexed pages.

For ongoing work, keep a record of what you changed and when. Review a meaningful period rather than reacting to a single day's movement. If the goal is more inquiries or sales, track those outcomes separately from search clicks.

Adapted from my guide on setting up Google Search Console, originally published on Straffe Sites.

A small docs MCP server: search, retrieve, and keep track of the source

Seppe Gadeyne — Thu, 24 Sep 2026 09:51:13 +0000

An agent can remember an API that no longer matches the project in front of it. Giving it documentation helps, but the source matters: the newest documentation and the documentation for an installed version are not necessarily the same.

I use two small TypeScript servers to make that distinction explicit: tailwind-docs-mcp reads Tailwind's documentation source, while hermes-docs-mcp prefers a local Hermes documentation tree and falls back to GitHub.

Both expose search, retrieval, and listing over MCP stdio. Neither needs an embedding service or vector database. The interesting engineering is in parsing the documentation, ranking a useful page above an incidental mention, and knowing when the index is stale.

Give the agent a small retrieval loop

Each server has three tools:

Job	Tailwind	Hermes
Find candidate pages	`search_tailwind_docs`	`search_hermes_docs`
Read one page	`get_tailwind_doc`	`get_hermes_doc`
Browse available slugs	`list_tailwind_docs`	`list_hermes_docs`

Search returns titles, slugs, source URLs, and snippets. The agent selects a slug and retrieves the page before answering. Listing helps when it does not know the right terminology; Hermes also supports filtering by section.

I prefer this to returning an entire manual for every question. Search is a navigation step, though, not a substitute for reading the page. A snippet can omit a warning or the condition that makes an example valid.

Unknown slugs return an MCP error with suggested matches. Neither server needs a tool that writes into the consuming project's files.

Tailwind: parse the source instead of rendering the website

Tailwind's adapter reads MDX under src/docs in tailwindlabs/tailwindcss.com. It extracts exported titles and descriptions, headings, recognizable utility classes, and literal API-table rows. It removes selected MDX wrappers to produce Markdown-like content.

This is a source-specific parser, not an MDX runtime. It does not execute documentation components. Computed tables and unusual component syntax can lose information, and the cleanup can alter code-like expressions. Use the linked documentation page when exact presentation or a complete generated example matters.

The search scorer gives title and slug matches more weight than body mentions. It also recognizes utility families: a color utility such as bg-red-500 gets a boost toward background-color.

That domain knowledge matters because many unrelated examples contain background classes. A plain text match can find a real occurrence on the wrong reference page.

During verification, this call to search_tailwind_docs ranked background-color first:

{"query":"bg-red-500 background","limit":3}

Then retrieve the selected page with get_tailwind_doc:

{"slug":"background-color"}

Those calls were executed against the pinned server. They show one working query, not a search-quality benchmark across the whole documentation set.

Build both servers from pinned source

You need Git, npm, Node.js 20 or newer, and an MCP client that can launch stdio servers. GitHub access is needed for the default remote sources. A local documentation directory avoids those runtime fetches; Node and the server's npm dependencies are still required.

These are Bash commands for Linux, macOS, or WSL. Native Windows is not tested here. Start in a directory where you want the checkouts:

git clone https://github.com/seppegadeyne/tailwind-docs-mcp.git
cd tailwind-docs-mcp
git checkout --detach 072985944b26721d3c8d8161255fdde97da5f47e
npm ci --ignore-scripts
npm test
npm run build
cd ..

git clone https://github.com/seppegadeyne/hermes-docs-mcp.git
cd hermes-docs-mcp
git checkout --detach 0decc76d0d9a4f5b54ffa8b73c4dcc9f5d9c018b
npm ci --ignore-scripts
npm test
npm run build

The locked installs and builds passed during verification on Linux with Node 25.2.1 and npm 11.6.2. Tailwind's three tests and Hermes's 15 tests passed. These suites check parser and search behavior using fixtures; the separate MCP smoke tests exercised discovery and real remote retrieval.

If you have not installed Hermes yet, my guide on Voltti walks through installing Hermes with the desktop app or terminal. Return here once your client is ready; the configuration below connects it to the documentation servers.

For an existing Hermes client, merge the following into its configuration, using your own absolute paths. The syntax follows the official MCP guide.

mcp_servers:
  tailwind-docs:
    command: node
    args: ["/absolute/path/to/tailwind-docs-mcp/dist/cli.js"]
    timeout: 180
    connect_timeout: 60
    enabled: true
  hermes-docs:
    command: node
    args: ["/absolute/path/to/hermes-docs-mcp/dist/cli.js"]
    timeout: 180
    connect_timeout: 60
    enabled: true

Check discovery before asking a model to use the tools:

hermes mcp test tailwind-docs
hermes mcp test hermes-docs

Discovery alone does not verify indexing: loading happens when a documentation tool is called. Follow it with the search and retrieval examples. Other clients need their own configuration format.

Hermes: a local-first source with a remote fallback

Hermes's adapter checks HERMES_DOCS_DIR, then its conventional local checkout location, and otherwise reads website/docs from NousResearch/hermes-agent on GitHub. Unlike the Tailwind local loader, the Hermes loader walks nested directories and accepts both Markdown and MDX.

It reads simple frontmatter metadata, derives slugs from paths, preserves fenced code, and converts Docusaurus admonitions into text markers. Its parser does not implement every frontmatter feature; a custom route declared in metadata is not necessarily the path-derived URL it returns.

A local tree can correspond to the installed software, provided you point it at that installation and account for local modifications. The GitHub fallback follows main. It does not promise that the returned docs describe your installed release.

The fallback was exercised with an empty home directory and no local override. Search, retrieval, and listing succeeded. The actual list response began:

Hermes Agent docs: 3 of 440 pages (installed commit unknown).

That unknown matters. The current commit helper inspects a local Git checkout; it does not attach a resolved remote SHA to fallback content. The wording says “installed commit” even on the remote path. Do not interpret it as verified version provenance.

For a known page, this is the argument to get_hermes_doc:

{"slug":"user-guide/features/mcp"}

The Glama listing provides discovery, not evidence of a successful hosted deployment. The standalone test establishes that the source loader works without a local Hermes checkout. Hosting still needs the runtime, a transport arrangement, and network access.

Freshness and reproducibility need separate decisions

Both remote loaders cache their index in process memory without a time-based refresh. Restarting the process rebuilds it on the next request. Hermes caches its local index for 60 seconds; Tailwind rereads its local directory on each load.

For reproducible documentation, check out the upstream doc repository at a chosen commit and point the server at it. These are illustrative environment-variable examples; replace the paths with actual documentation directories and start the command from the corresponding server checkout:

TAILWIND_DOCS_DIR=/absolute/path/to/tailwindcss.com/src/docs npm start

HERMES_DOCS_DIR=/absolute/path/to/hermes-agent/website/docs npm start

Set those variables in the client's server environment for normal MCP use. An explicitly configured but invalid Hermes directory fails locally rather than silently selecting GitHub.

Pinning the MCP adapter does not pin remotely fetched docs. The current loaders request the tree and individual files through moving main references, so an upstream change during indexing could mix revisions. They also fetch pages with Promise.all; they do not implement bounded concurrency or a persistent disk cache. A network failure can prevent the index from loading.

What I would carry into another documentation adapter

Start with a normalized page record and tests for your source format. Preserve its URL, source path, and code examples. Build a small query set with expected reference pages, including terms that occur in many examples. The live Hermes query mcp_servers, for example, ranked a plugin guide first during verification. Lexical scoring is understandable, but it still needs evaluation.

Before distributing a corpus, check the documentation's own license and attribution requirements. Public source access is not a blanket redistribution license. Treat retrieved text as reference material, not instructions that grant the agent new permissions.

For a production adaptation, I would resolve one source SHA before fetching, report it with results, bound fetch concurrency, and define an explicit refresh policy. Those are improvements to make, not features to assume these versions already have.

The small tool surface is reusable. The parser, ranking rules, and version policy are the parts that need to fit the documentation you are serving.

Giving an AI agent a spell checker with MCP

Seppe Gadeyne — Thu, 24 Sep 2026 09:33:48 +0000

A writing agent can produce a fluent paragraph and still choose the wrong spelling convention. A word can pass a dictionary check and still conflict with a style guide. US English makes a useful example: spelling and regional usage are separate checks.

I keep those decisions outside the model in language-mcp: a small TypeScript MCP server with local spelling and simplicity checks. It currently supports US English and Dutch, with a separate Dutch word lookup and a B1 simplicity check for each language. The examples below use US English and Dutch; the same design can be extended to other languages with suitable dictionaries, rules, and tools. The agent submits text, reads the findings, and decides which changes make sense. The server does not rewrite files.

The useful part of this project is the boundary between a dictionary, a style rule, and an editorial decision. They answer different questions, even when all three produce something that looks like a correction.

A local dictionary first, a network lookup when needed

Six tools use the Hunspell executable with bundled dictionaries. Dutch uses OpenTaal; US English uses the SCOWL/LibreOffice dictionary assets. Spelling checks do not send the submitted text to a spelling API.

That privacy statement applies to this server, not to the whole agent session. If your MCP client uses a hosted language model, its conversation and tool results may still reach that provider. I explain this distinction in more detail in our guide to what stays local in a hybrid AI setup.

The one network tool, get_dutch_word_details, queries Woordenlijst.org, maintained by the Instituut voor de Nederlandse Taal for the Taalunie. It provides lexical details such as pronunciation, word forms, and hyphenation. This is a separate network operation, useful for an individual word that needs investigation.

The Dutch dictionary source is OpenTaal's Hunspell repository. Keep the dictionary attribution and license files when redistributing the assets; a server's code license does not replace them.

Why I kept the Hunspell executable

The project's architecture decision record considers replacing the executable with nspell, a JavaScript implementation. Removing a native dependency would simplify deployment. I kept the executable because changing the implementation also means proving behavioral compatibility.

A particularly easy mistake sits in Hunspell's -a pipe protocol. It does not promise one response line for every submitted token. A hyphenated input can produce a response for each part, followed by an empty separator line.

If the wrapper zips individual response lines with input words, one compound can shift the remaining results onto the wrong words. The current implementation groups output into blocks separated by empty lines, then associates each block with one unique input token. It rejects a response-count mismatch instead of returning misaligned findings.

Within a block, the wrapper accepts * and + responses, collects suggestions from & responses, and treats unknown responses as failures. It removes duplicate suggestions and returns at most eight per token. It also limits the subprocess to 20 seconds.

That explains the dependency better than a speed claim. The ADR discusses performance, but I am not presenting a Hunspell-versus-nspell benchmark here. A replacement should pass the same compound and suggestion tests before deployment gets simpler at the expense of correctness.

Install the pinned version

You need Git, Node.js 20 or newer, npm, and hunspell available on the MCP host's PATH. The Bash commands below target Linux, macOS, or WSL. Native Windows setup is not covered here; with WSL, install the dependencies and run the client inside that environment.

Install Hunspell through your operating system's package manager first. The repository README gives pacman -S hunspell for Arch Linux. Package installation may require administrator privileges. Check the actual executable before building:

node --version
npm --version
hunspell --version

git clone https://github.com/seppegadeyne/language-mcp.git
cd language-mcp
git checkout --detach e769c5d960c92a4455f1be0607cc68b873dffab2
npm ci --ignore-scripts
npm test
npm run build

The checkout pins the source discussed here rather than silently following future changes. Run the locked dependency install, tests, and build on your MCP host before configuring your client. A successful run on one machine is not proof that every Node version or operating system has been exercised.

In an existing Hermes installation, merge this entry into mcp_servers in your configuration. Replace the example path with your checkout's absolute path; do not replace unrelated server entries.

mcp_servers:
  language:
    command: node
    args: ["/absolute/path/to/language-mcp/dist/cli.js"]
    connect_timeout: 60
    enabled: true
    timeout: 120

Then test discovery:

hermes mcp test language

The server speaks MCP over stdio, so node dist/cli.js is not an interactive spelling prompt. Your client launches it and exchanges protocol messages. Other stdio-capable MCP clients need their own configuration syntax, and their tool names may include a server prefix.

Try the US English tools

These JSON objects are tool arguments, not shell commands. Select the named tool through your MCP client or ask your agent to call it.

For a paragraph, use check_us_english_text:

{"text":"While moving toward the center, we organized everything."}

The verified response is:

US English check (hunspell en_US + britticism scan)
8 words checked, 0 unknown, 0 British forms.
OK: no typos, no British forms found.

For one word, use validate_us_english_word:

{"word":"color"}

The verified response is "color" is correct US English.

To see the regional style check in action, replace While with the intentionally British Whilst, and toward with towards. These are test inputs, not recommended US English. The dictionary accepts them, but the separate style rules flag both and suggest the US forms. A dictionary check alone would miss that distinction.

The server also provides check_dutch_text, validate_dutch_word, and get_dutch_word_details. The first two use the local Dutch dictionary; the last uses the network for lexical details. You do not need the network lookup for the US English examples. Two simplicity checks, check_dutch_b1_text and check_us_english_b1_text, are covered next.

Checking Dutch text for B1-level simplicity

Version 0.4.0 adds check_dutch_b1_text, for a question the spelling tools cannot answer: is this Dutch text simple enough for a broad audience?

"Dutch at B1" is an editorial convention, not a validated text measurement. The Rijksoverheid communication guideline asks writers to aim for B1 (CEFR) in new public-facing material. A formula cannot certify that a text meets it, so the tool reports proxies a reviewer can check in context:

Readability: Flesch-Douma reading ease (the Dutch-adapted Flesch formula) and ARI, with a practical B1 band around 60-70 for Flesch-Douma. Below 50 words or three sentences, the formulas are suppressed instead of reporting noise.
Sentence and paragraph length against configurable thresholds (defaults: warn above 15 words per sentence, flag above 20; 150 words per paragraph).
Passive voice, using a second Hunspell pass described below.
Officialese jargon with plain alternatives (thans to nu, betreffende to over), filler words, and idioms that are hard for NT2 readers, each with its position.
Nominalization density (-ing/-tie/-heid/-iteit words per 100 words) and je/u voice consistency.

The passive detector is a second Hunspell protocol story. The -a pipe from the spelling tools returns no morphology, but hunspell -m returns st: stem and ts: tag fields from the OpenTaal affix file. Three quirks matter:

Only affix-derived forms get the past-participle tag ts:VBpe (gemaakte); bare participles such as verzonden are their own lemma without a tag.
Separable compounds analyze as compound stems: uitgevoerd becomes uit st:gevoerd.
Tags are context-free: is plus a participle can be a perfect tense or a passive, so those hits are labeled low confidence.

The wrapper combines the tag, a bare-lemma check with Dutch participle phonology, and a compound-stem rule, then scans for auxiliaries (wordt, worden, werd, is, zijn) followed by a participle. Every hit is a review flag with its sentence and position, not a verdict.

An intentionally bureaucratic example:

{"text":"Wellicht wordt de aanvraag thans door de gemeente in behandeling genomen. De implementatie van de regeling betreffende de vergoeding wordt vervolgens door de afdeling uitgevoerd, wat betekent dat u als klant langer moet wachten op een beslissing dan u wellicht zou verwachten op basis van de eerder door ons gedane toezeggingen. Je krijgt daarna een bericht. Onder de loep genomen?"}

The verified response, abbreviated:

Dutch B1 simplicity check (B1 proxies, not a validated B1 verdict)

Readability:
- Flesch-Douma: 54 (band: below-b1; B1 target 60-70)
- ARI: 11.4 (grade-level indication)
- Words: 58, sentences: 4, avg 14.5 words/sentence
- Sentences over 15 words: 1 (1 over 20)
- Long words (>=4 syllables): 7%

Passive voice (review flags, not verdicts):
- "wordt genomen" (+ door/van agent) — "Wellicht wordt de aanvraag thans door de gemeente..." (position 0)
- "wordt uitgevoerd" (+ door/van agent) — "De implementatie van de regeling betreffende..." (position 73)

Jargon and vague wording (plain alternatives):
- "thans" → nu (position 27)
- "implementatie" → uitvoering, uitrollen (position 77)
- "betreffende" → over, bij (position 107)

Filler words:
- "Wellicht" → misschien (position 0)

Idioms (consider plain phrasing for NT2 readers):
- "Onder de loep genomen" → goed bekijken (position 359)

Nominalization density: 10.3 per 100 words (high — prefer verbs over nouns)

Voice consistency: MIXED (expected je): u-forms 2x at position 196, je-forms 1x at position 329 — pick one address form.

The same check for US English

Version 0.5.0 adds check_us_english_b1_text. It asks the same question about US English copy. The output has the same structure: readability, passive voice, rule findings with plain alternatives and positions, nominalization density, and reader address. "B1" is still shorthand for plain language, not a certified level.

The English version needs its own measurements, not translated Dutch rules:

Readability: Flesch Reading Ease (the original English formula, with 60-70 as the practical plain-English band), Flesch-Kincaid grade level (default target 9 or lower), and ARI. A zero-dependency syllable counter feeds the formulas. It agrees with the CMU Pronouncing Dictionary on about 94% of the 10,000 most common US English words. That is accurate enough for averages over a text, not for individual words.
Sentence length: warn above 20 words and flag above 25, following plainlanguage.gov and the GOV.UK style guide. Both thresholds are tool parameters.
Rules from the Federal Plain Language Guidelines and the GOV.UK "words to avoid" list. They cover formal jargon (utilize to use, prior to to before), wordy phrases (in order to to to), hidden verbs (make a decision to decide), filler words, and idioms. British spellings stay in check_us_english_text, so nothing is reported twice.
Reader address: the tool lists references to "users" or "the customer" when the text could address the reader as "you".

Passive detection was the second Hunspell surprise. The bundled en_US affix file has no ts: tags at all. hunspell -m marks regular -ed forms with the affix flag fl:D (created st:create fl:D), while irregular participles such as written or built come back as bare lemmas. The detector therefore combines the flag with a closed list of irregular participles. It also has to skip hyphenated words, because the en_US dictionary splits data-driven into one morphology block per part. Participles that usually describe a state after "be" (is located, are required) are labeled low confidence.

An intentionally bureaucratic example:

{"text":"In order to facilitate the processing of your request, it is essential that applicants utilize the online portal prior to the deadline. Requests that are submitted after the deadline will not be considered by the committee. Users are required to make a payment before a decision can be reached. Due to the fact that the system is undergoing maintenance, additional delays may be experienced. You will get an email when we are done."}

The verified response:

US English B1 plain-language check (B1 proxies, not a validated B1 verdict)

Readability:
- Flesch Reading Ease: 51.8 (band: below-b1; B1 target 60-70)
- Flesch-Kincaid grade: 9.6 (above target 9)
- ARI: 8.9 (grade-level indication)
- Words: 71, sentences: 5, avg 14.2 words/sentence
- Sentences over 20 words: 1 (0 over 25)
- Complex words (>=3 syllables): 20%

Passive voice (review flags, not verdicts):
- "are submitted" — "Requests that are submitted after the deadline will not be considered by the committee." (position 135)
- "be considered" (+ by agent) — "Requests that are submitted after the deadline will not be considered by the committee." (position 135)
- "are required" [adjectival use likely, low confidence] — "Users are required to make a payment before a decision can be reached." (position 223)
- "be reached" — "Users are required to make a payment before a decision can be reached." (position 223)
- "be experienced" [adjectival use likely, low confidence] — "Due to the fact that the system is undergoing maintenance, additional delays may be exper…" (position 294)
- "are done" [adjectival use likely, low confidence] — "You will get an email when we are done." (position 391)

Jargon and buzzwords (plain alternatives):
- "facilitate" → help, make possible (position 12)
- "utilize" → use (position 87)
- "prior to" → before (position 113)
- "required" → need, must (position 234) — common in web copy; judge in context
- "additional" → more, extra (position 354)

Wordy phrases:
- "In order to" → to (position 0)
- "it is essential that" → (state the point directly) (position 55)
- "Due to the fact that" → because (position 295)

Hidden verbs (use the verb, not the noun):
- "make a payment" → pay (position 246)

Nominalization density: 2.8 per 100 words
  Top: decision (1x), maintenance (1x)

Reader address: third-person references to the reader 2x (first at position 76): applicants (1x), users (1x) — address the reader as "you" where they are the audience; "you" used 2x.

The last hit shows why these remain review flags: "when we are done" is an adjective, not a passive, and the tool labels it low confidence instead of hiding it.

Extend the pattern to another language

MCP does not tie this design to English or Dutch. The current server implements those two languages; adding another one requires code and dictionary assets, not just a language name in a request.

Start with a compatible Hunspell dictionary from a trustworthy source. Include its dictionary and affix files, preserve its license and attribution, and add it to the dictionary resolver. Then register language-specific text-checking and word-validation tools with the same result structure.

Add regional or editorial rules only when the dictionary cannot express the distinction you need. A lexical lookup is optional and requires a suitable source for that language; the Dutch lookup is not a universal dictionary API. Finally, test valid words, misspellings, compounds, suggestions, and any language-specific rules before exposing the new tools to an agent.

The reusable idea is the separation of responsibilities: the dictionary checks spelling, explicit rules check selected conventions, and the agent reviews the findings in context. Language coverage depends on the available dictionaries and the integration work, not on MCP itself.

Treat the style rules as review suggestions

The britticism detector is a static list of regular expressions and suggested replacements. Some rules cover spelling variants. Others encode editorial preferences, such as using custom rather than bespoke.

I would not automatically apply every match. The list also includes context-sensitive vocabulary: queue is perfectly ordinary in an American programming article, and lift does not always mean an elevator. Rules can flag valid text or generate an unsuitable inflection. This implementation is not a grammar parser.

There is no measured coverage percentage behind the rule list. It is inspectable and testable, which makes it useful for enforcing a specific style contract, but it cannot certify that a paragraph is idiomatic US English.

The two checking paths also treat Markdown differently. The spelling tokenizer removes URLs, email addresses, fenced code, and inline code. The britticism scan receives the original text. A quoted example or identifier can therefore appear in style findings even when spelling ignores it. Preserve source quotations and code; review the surrounding prose instead.

The limits belong in the workflow

The tokenizer stops after 2,000 checkable tokens, skips one-character tokens, and skips short all-uppercase acronyms. For a longer document, split it into sections and keep track of what you submitted. A clean result is not evidence that every character in the original document was checked.

Reported positions are JavaScript string indexes, not editor-ready line and column locations. Since version 0.5.0, each spelling finding reports the offset of the token itself. Earlier versions searched for the first occurrence of the word, which could point inside a longer word (red inside hundred). Treat the positions as navigation aids: excluded material and later edits still make automatic patching risky.

The network lookup has its own boundaries. It uses an unofficial XML service, serializes calls with a minimum 1.2-second interval, and caches results in memory for 24 hours. This is not a bulk dictionary download API or an availability guarantee. Its parser also takes the first matching descendant fields; in the verified pizza lookup, the top-level hyphenation reflected a diminutive. Check ambiguous lexical details on the source website rather than treating every rendered field as authoritative.

My preferred workflow is simple: submit a section, inspect the findings, make deliberate edits, and check the edited section again. Keep proper nouns and technical identifiers unless there is a specific reason to change them. Read the whole paragraph afterward. A dictionary cannot tell whether a sentence says what you meant.

The Glama listing is another way to discover the server; the pinned repository is the reference for the tool names and behavior described here. A directory listing does not remove the Hunspell runtime requirement.

Keyword Research with AI Agents and Google Search Console

Seppe Gadeyne — Tue, 22 Sep 2026 09:40:19 +0000

Keyword Research with AI Agents and Google Search Console

Manual keyword research is slow and disconnected from real user behavior. I use AI agents connected to Google Search Console data to automate keyword clustering, intent analysis, and content gap detection for client websites.

This article shows the complete workflow: from raw GSC data to actionable keyword clusters that drive content decisions.

The problem with manual keyword research

Traditional keyword research relies on guesswork. You look at competitor sites, use keyword tools with volume estimates, and try to predict what users might search for. But if you already have a website, Google is telling you exactly what people search for — and you're not listening.

Google Search Console provides actual search query data, grouped by page, with impressions, clicks, and average position. This is the real signal. The problem is extracting actionable insights from thousands of rows of query data.

That's where AI agents come in.

The architecture

The system consists of three components:

Data source: Google Search Console Search Analytics API
AI agent: A coding agent with access to the GSC data and the ability to execute scripts
Cluster output: A JSON mapping of queries to pages, intents, and optimization opportunities

The agent runs a Node.js script that authenticates with Google Cloud, fetches 12 months of search query data, and processes it into keyword clusters organized by page and intent.

Step 1: Setting up GSC access

Before anything else, you need API access to Search Console data. This requires:

A Google Cloud project with the Search Console API enabled
Application Default Credentials (ADC) configured with gcloud auth application-default login
The Search Console property added to your account

# Configure ADC credentials
gcloud auth application-default login

# Set the quota project (required since 2026)
export GOOGLE_CLOUD_QUOTA_PROJECT=your-project-id

Step 2: The keyword cluster script

The core of this workflow is a Node.js script that fetches GSC data and processes it. Here's how it works:

// Authenticate with GSC API
async function mintAdcToken() {
  const result = await execFileAsync('gcloud', [
    'auth', 'application-default', 'print-access-token'
  ]);
  return result.stdout.trim();
}

// Fetch query data for a specific period
async function fetchGscRows({ startDate, endDate }) {
  const accessToken = await mintAdcToken();
  const response = await fetch(
    'https://searchconsole.googleapis.com/webmasters/v3/sites/' +
    encodeURIComponent('sc-domain:your-site.com') +
    '/searchAnalytics/query',
    {
      method: 'POST',
      headers: {
        authorization: `Bearer ${accessToken}`,
        'content-type': 'application/json',
        'x-goog-user-project': process.env.GOOGLE_CLOUD_QUOTA_PROJECT
      },
      body: JSON.stringify({
        startDate,
        endDate,
        dimensions: ['query', 'page'],
        dataState: 'final',
        rowLimit: 25000
      })
    }
  );
  return (await response.json()).rows;
}

The script fetches up to 25,000 rows of query data spanning the last 12 months. It uses pagination to handle larger datasets.

Step 3: Processing the data into clusters

Once the data is fetched, the processing happens in several stages:

Map routes to pages: Each query result is mapped to a canonical route, stripping fragments and query parameters.

Aggregate by page: For each page, all queries are collected along with their impressions, clicks, and positions.

Identify intent clusters: Queries are grouped by intent. "What is X" queries are informative. "Buy X" or "hire X" queries are commercial. The intent is inferred from both the query phrasing and the page it leads to.

Detect cannibalization: When multiple pages rank for similar queries, the script flags potential cannibalization where pages compete for the same search terms.

Here's a simplified version of the clustering logic:

function clusterQueries(page, queries) {
  return {
    route: page,
    pageMetrics: calculatePageMetrics(queries),
    primaryTerm: queries[0].query, // Highest click volume
    cluster: queries.map((q, i) => ({
      query: q.query,
      clicks: q.clicks,
      impressions: q.impressions,
      ctr: q.clicks / q.impressions,
      role: i === 0 ? 'primary' : (i <= 9 ? 'secondary' : 'long-tail'),
      sharedWith: detectCannibalization(q.query, allPages)
    }))
  };
}

Step 4: Using the clusters for content decisions

The output is a JSON file that maps each page to its keyword clusters. This becomes the foundation for all content and SEO decisions.

Optimization targets: Pages with high impressions but low clicks are prime optimization targets. The title, meta description, or content may need improvement.

Internal linking strategy: Use the cluster data to identify which pages should link to which. If a page ranks for "website development services" and another ranks for "hire a web developer," they should link to each other.

Content gap identification: With query and page as dimensions, every returned row already pairs a query with a page. A gap here means the site may lack content that fits the search intent, even though an existing page earns impressions for that query. Review the current page and search results before deciding whether to improve it or create a separate page. This export cannot reveal demand for queries where the site has no recorded visibility.

Commercial vs. informational intent: The intent labels help decide whether a page should be a blog post (informative) or a landing page (commercial).

Example: real data from our site

Here's a real example from our Search Console data (August 2026):

Query	Impressions	Position	Current page
website laten maken	2,019	16.7	/blog/wat-kost-een-website-laten-maken
goedkope website laten maken	1,232	21.3	/blog/goedkoop-website-laten-maken
een website laten maken	401	19.2	/blog/wat-kost-een-website-laten-maken
astro website laten maken	15	7.0	/astro-website-laten-maken

(These queries are in Dutch — they come from a Dutch-language client site we manage. The workflow itself works the same in any language.)

What should we investigate?

The price blog earns impressions for "website laten maken." It may answer cost questions well, while a service page may better serve someone ready to hire a developer. The query alone does not establish which intent dominates.
The row for "goedkope website laten maken" shows one blog. To investigate cannibalization, inspect the other query-page pairs; this table alone does not demonstrate competing pages.
"astro website laten maken" appears with a relevant service page and an average position of 7.0. That is useful visibility data, not evidence of inquiries or sales.
Before proposing a new service page for "website laten maken," check whether a suitable one already exists and review the search results. Improving an existing page and its internal links may be the better option.

The script surfaces candidates for review. It does not establish that a new page is necessary or that it will bring in more business.

Automating the workflow with AI agents

The real power comes from automating this workflow. With an AI coding agent, you can:

Schedule regular runs: Run the script weekly or monthly to track changes
Generate reports: Have the agent analyze the data and generate optimization recommendations
Implement changes: Have the agent actually update titles, meta descriptions, and internal links based on the cluster data
Track results: Compare search performance and qualified inquiries before and after changes, using conversion tracking or CRM data alongside GSC

The agent doesn't replace your SEO judgment — it amplifies it. You still decide the strategy, but the agent handles the data analysis and implementation.

Measure inquiries as well as search visibility

For a service business, a new page should help generate relevant inquiries. GSC reports search performance; it does not tell you whether a visitor submitted a useful project inquiry or became a customer. Use analytics conversion tracking for successful form submissions and, where available, CRM records to assess lead quality.

Before making changes, record organic traffic and qualified inquiries for the relevant existing pages. After launch, compare the combined results for those pages and the new service page, not just the new page in isolation. Otherwise, moving inquiries from the blog to the service page can look like growth when the total has not changed.

Use comparable, non-overlapping periods of at least 30 days and allow longer when inquiry counts are low. Consider seasonality and other site or marketing changes; a before-and-after comparison alone does not prove causation. A higher ranking without more relevant inquiries is not enough to call the change a business success. These are proposed measurement criteria, not conversion results demonstrated by the table above.

Practical tips

Always compare fixed periods: When measuring changes, use complete, non-overlapping periods. Don't compare this week with last week if they have different numbers of days.
Track baseline metrics: Before making any SEO changes, record the current impressions, clicks, and positions for the affected pages and queries.
Give changes time: Reassess after at least 30 days, and wait longer when the data is sparse. Avoid repeated changes before you have enough evidence to judge the previous one.
Use the API, not the UI: The Search Analytics API gives you more data and more control than the web interface. It's worth the extra setup.

Conclusion

Keyword research doesn't have to be manual guesswork. By connecting AI agents to your real Google Search Console data, you can build a data-driven SEO workflow that continuously optimizes based on actual user behavior.

The key insight: you already have the data you need. You just need the right tools to process it.

This workflow is based on our experience running keyword research for client websites. The scripts described here are used in production on straffesites.com. New to keyword research? Start with How to do keyword research in 6 clear steps on the Straffe Sites blog.

Hermes Agent for SEO: from Search Console to a blog post

Seppe Gadeyne — Mon, 14 Sep 2026 07:28:10 +0000

I don't want an AI agent to turn a keyword into another 1,500 words of plausible advice. I want it to inspect the site, find a question worth answering, read the relevant documentation, and give me an article whose claims I can check.

Hermes Agent plus Google Search Console gets you part of the way there. Add reusable research and writing skills, your repository, and your own technical notes, and you have a workflow you can inspect instead of a conversation you hope went well.

This tutorial covers installation, connecting Google Search Console, and using short skill commands to research, write, or audit an article. It adapts the process behind my work at Straffe Sites.

What you are connecting
Install Hermes for your operating system
Connect Search Console through gcloud
Adapt the marketing skills for Hermes
Turn the setup into an article
Check the draft before you publish
Troubleshooting before you blame the model

What you are connecting

There are three separate pieces:

Piece	Job	What it does not provide
Hermes Agent	Runs the conversation and tools; reads files; follows skills	A Google account or verified technical expertise
Google Search Console API	Returns search performance for properties you can access	Market-wide keyword volume or an explanation of why rankings changed
NotFair's open-source skills	Supply research, audit, planning, and writing procedures	An automatically working replacement for their default hosted connector

You ask for a task; Hermes loads the relevant skill, uses the connected tools, and returns an audit or draft for you to review. The skill carries the detailed procedure, so your chat message can stay short.

Your Google credentials stay in the local setup, but content passed to a cloud model may reach that model provider. Use approved accounts, keep credentials out of chat, and only share client data you are allowed to process.

You will need Git, a model provider configured in Hermes, and a Google account. You or your administrator must be able to approve Cloud setup and access to the intended Search Console property. Hermes can help select or create the Cloud project instead of making you configure it in advance. The Bash examples below target Linux, macOS, and WSL2 on Windows.

Install Hermes for your operating system

Linux and Apple Silicon macOS

The official Hermes installation guide provides this CLI installer:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

That executes a downloaded installer with your user's permissions and installs dependencies. If you prefer to review it first, use this route instead:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh \
  -o hermes-install.sh
less hermes-install.sh
# Run only after reviewing the script and its dependencies.
bash hermes-install.sh

Open a new terminal if hermes is not yet on your PATH. Then verify the CLI and run setup in the default Hermes profile:

hermes --version
hermes setup
hermes skills list

In setup, choose your model provider and follow its authentication flow. Hermes installation and access to a model are separate requirements.

The current platform support page lists Apple Silicon macOS as supported and Intel macOS as unsupported. Check that page before assuming an older Mac has the same installation path.

Windows

For the Bash examples in this article, use WSL2. In an administrator PowerShell window:

wsl --install

Restart if Windows requests it, open the installed Linux distribution, complete its initial user setup, and run the Linux installer above inside that shell. Have Hermes install Google Cloud CLI inside WSL too. Mixing a Windows Hermes process, WSL credentials, and Bash paths makes authentication harder to diagnose.

Hermes also has an official native Windows installer. If you prefer PowerShell rather than WSL:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Review that script first if you would not normally execute a remote installer. Native Windows installation is an alternative, not an extra step after WSL. The remaining shell snippets here are Bash; don't paste them unchanged into PowerShell. The Google setup prompt below asks Hermes to handle installation and paths for your actual environment, including native Windows.

For an introduction that also covers the desktop app, see installing Hermes on Voltti. Use the official Hermes docs for current commands.

Connect Search Console through gcloud

Open Hermes:

hermes

Replace [MY_WEBSITE] with your site and give Hermes this prompt:

Install gcloud and connect Google Search Console for [MY_WEBSITE]
using a service account. Add its email in GSC through browser control,
or give me the email to add myself. Use read-only access, ask me to
approve permissions, and test the connection.

Hermes can work out the installation commands, Cloud project setup, and authentication details from the official documentation. You handle Google login, consent, and 2FA. If browser control is unavailable, a Search Console property owner can add the email under Settings → Users and permissions. Restricted access is enough for performance reports.

Keep command approvals enabled. Prefer keyless service-account authentication, keep credentials out of chat and your repository, and don't grant site ownership or broad Cloud administrator roles just to read reports. The connection test must use the service account that was added to GSC, not a different personal account.

You should finish with the correct property identified and a real API read, not just “setup complete.” If the property has no useful history yet, Hermes should say so. My Search Console setup guide covers creating and verifying the property itself.

Adapt the marketing skills for Hermes

The NotFair plugin provides reusable SEO, research, and writing procedures. Ask Hermes to adapt them to the Google connection you just set up:

Adapt the SEO and Search Console skills from
https://github.com/nowork-studio/notfair-plugin for Hermes.
Use my gcloud service account instead of the hosted connector, name
them notfair-*, and keep Google access read-only. Show the changes
and test results before installing.

Hermes should inspect the source, include the required supporting files, and test the adaptation. You don't need to dictate the folder structure or API implementation. Review what it changed; once you are satisfied, reply:

Install the reviewed skills.

The notfair-* names below are the local names requested in that prompt, not commands bundled with a fresh Hermes install. Start a new Hermes session after installation. If a command is missing, ask Hermes to check that the skill was installed and exposed under its intended command name.

Voltti's guide to retrieving marketing data with an AI agent explains the broader approach. Here, the goal is simply to make the skills use your own working Google connection.

Turn the setup into an article

In the Hermes chat box, start with /skill-name, then add a URL and what you want done. Type / to see available commands. Hermes loads the installed skill's instructions for you; you don't need to paste its whole procedure into the conversation.

These examples go into Hermes chat, not Bash or PowerShell. I use Straffe Sites URLs as examples. Replace them with your own site; a public URL does not grant access to its private Search Console data.

Each block below contains the original prompt and the complete final answer from a recorded Hermes run. Intermediate tool activity is omitted. The writing follow-ups continue the same writing conversation; the audit follow-up continues its own audit conversation. Nothing was published.

DEV currently labels these compatible trace imports as Claude Code. The agent that ran them was Hermes. Expand the longer answers and use the scrollbar to read them. DEV does not create section anchors inside these embeds, so an answer's contents links will not jump to its headings.

Write an article

The skill supplies the writing process. Your prompt supplies the site and topic. Add an audience or angle when it matters, and let Hermes ask for anything it cannot establish from the context.

Hermes Agent: writing Astro vs WordPress (compatible trace import) gpt-6-astra

You

/notfair-content-writer https://straffesites.com
Write an English article about Astro versus WordPress for small
business websites.

Agent

Blog article: Astro vs WordPress: choose for the person editing

SEO metadata

Title tag: Astro vs WordPress: choose for the person editing
Meta description: Astro vs WordPress for small business websites: compare editing, speed, maintenance, and integrations. Use a practical checklist to choose your setup.
Proposed URL slug: /en/blog/astro-vs-wordpress
Target keyword: Astro vs WordPress
Secondary keywords: Astro for small business websites; WordPress for small business; Astro CMS; WordPress vs static website.
Search intent: Commercial investigation, answered through an educational comparison.
Audience: Developers advising small businesses and owners evaluating website proposals.
Content angle: Choose the editing and maintenance workflow first, then test the complete implementation.
Metadata checks: Title: 49 characters. Description: 150 characters.

Editorial research and positioning

Existing coverage and keyword evidence

No dedicated Astro-versus-WordPress article was found in the inspected content inventory or site search. Related coverage already exists:

A website without a CMS: the site's Astro and Git content workflow.
Astro vs. Next.js: framework selection.
WordPress maintenance: ongoing operational work.
What is a headless CMS?: separating editing from presentation.

This draft keeps its focus on small-business platform selection rather than repeating those implementation guides.

The verified keyword registry uses final Google Search Console data for sc-domain:straffesites.com, covering September 1, 2025, through September 1, 2026. It contains no retained query combining “Astro” and “WordPress.” The proposed primary keyword therefore comes from the requested topic and live search research, not a demonstrated ranking opportunity in that registry.

Relevant existing queries include:

Existing destination	Recorded query	Impressions
Headless CMS article	what is a headless cms	106
WordPress maintenance article	wordpress development and maintenance	182
Astro glossary entry	astro framework	11

These are query impressions for this property and period, not search volumes. The low-click clusters are indicative, and absent queries do not establish absent demand.

Search-result review

The first five returned results included:

Result	Format and emphasis	Editorial response
Web Aloha	Broad comparison with performance, security, and cost claims	Explain caching and avoid treating platform defaults as guaranteed outcomes.
Reddit discussion	Community discussion about editing and maintenance ownership	Full discussion unavailable: extraction failed and the browser showed a human-verification page. No anecdote from it is used as evidence.
Andrew Walpole	Developer perspective on custom brand sites and content architecture	Bring the decision down to small-business editing tasks and handover requirements.
MFB Solutions	Small-business comparison favoring Astro	Correct the implication that static delivery eliminates technical maintenance.
Dizzi Digital	Business-purpose comparison and migration discussion	Add a concrete acceptance test for editing, publishing, integrations, and recovery.

Technical claims below rely on official documentation rather than competitors' benchmarks. The business scenario is explicitly hypothetical. No speed experiment, client result, or ranking uplift is invented.

Content

Astro vs WordPress: choose for the person editing

Astro vs WordPress is often sold as a speed contest. For a small business, the more expensive mistake may be choosing a site that nobody can update. Choose Astro when a developer will maintain a mostly informational site; choose WordPress when the business needs a familiar publishing dashboard or depends on established plugins. A fast homepage cannot compensate for an outdated service page.

This comparison is for developers advising small businesses and owners reviewing their recommendations. WordPress here means the open-source CMS in a conventional hosted setup, not a particular WordPress.com plan. Astro means the web framework, with static delivery as the starting point rather than a restriction.

Contents

Astro vs WordPress: the practical comparison
Test editing before choosing the stack
Compare finished pages, not framework promises
Account for maintenance on both sides
Check forms, bookings, and checkout early
Use headless WordPress only for a specific reason
Work through a small-business example
Decide whether a migration is worth doing
Frequently asked questions

Astro vs WordPress: the practical comparison

WordPress combines content management with website rendering. Its block editor gives editors a browser interface for headings, images, paragraphs, and other content. Themes control presentation, while plugins can add features.

Astro is a framework for building the website. It does not supply an equivalent editorial dashboard by itself. Developers can use content files, connect a CMS, or combine sources. Its default rendering mode builds pages ahead of time; routes that need fresh or personalized responses can render on demand with an adapter and suitable runtime.

Decision	Astro, starting with static pages	Conventional WordPress
Who changes content?	A developer, or editors using a separately configured CMS	Editors using the built-in dashboard
How do visitors receive pages?	Prebuilt HTML for static routes; server rendering where configured	Generated pages or cached responses, depending on the setup
How are features added?	Components, integrations, external services, or custom code	Core features, plugins, external services, or custom code
What needs maintenance?	Dependencies, build and deployment workflow, hosting, accounts, and integrations	Core, themes, plugins, hosting, database, accounts, and integrations
Where does it fit well?	Content-focused sites with deliberate control over the frontend	Sites that benefit from an established editor and plugin workflow

Neither column describes a maintenance-free product. Compare the complete setup the client will receive, including the editing interface and support arrangement.

Test editing before choosing the stack

Ask the eventual editor to do real work

Before approving a platform, ask the person who will maintain the content to change opening hours, replace a photo, and publish a service update in a preview environment. Give them the proposed interface, not a presentation about it.

Watch where they need help. Can they preview the page on a phone? Can they correct a mistake without contacting the developer? Can another employee take over? A technically elegant setup fails this test if routine changes require skills the business does not have.

WordPress supplies the basic editing interface. Its usability still depends on the theme, blocks, permissions, and customizations. A cluttered dashboard with unrestricted layout controls can be harder to use than a small set of well-designed fields.

Make Astro's content workflow explicit

An Astro proposal should name the content workflow: developer-managed files, a Git-based editor, or a headless CMS. These are different products for the business, even when visitors receive similar HTML.

Straffe Sites provides a concrete example of the file-based option: its website without a CMS uses Astro Content Collections with MDX and JSON content in Git. That demonstrates a workable approach for a technical team. It does not show that a shop owner should learn Git to change holiday hours.

If editors need a CMS, include it from the start. Agree on preview access, publication timing, image handling, and who responds when an update fails. Choose the editing workflow before treating Astro as the finished solution.

Compare finished pages, not framework promises

Astro provides useful defaults, not a guaranteed score

Astro's islands architecture lets developers render UI components as HTML and add client-side JavaScript where interactive components need it. A service page can remain mostly HTML while a calculator receives its own interactive code.

That can reduce unnecessary browser work. It does not make large photos smaller by itself, remove an embedded booking widget, or stop a developer from adding expensive scripts. Ordinary script tags and third-party embeds still count toward the visitor's workload.

WordPress is not required to rebuild every public page for every visitor. Its official caching documentation describes serving cached static files. A well-configured page cache changes the comparison substantially; dynamic and personalized pages need separate consideration.

Agree on a fair test

Compare representative pages with the content and features the business will actually use. Include the same images, fonts, analytics, and booking tools. Test a service page and an article, not just a nearly empty homepage.

Check loading behavior and responsiveness on mobile, keyboard navigation, layout stability, and whether the main action works. Record the test conditions. Lab tests help diagnose problems; available real-user data describes a different population and should not be presented as the same measurement.

Google confirms that Core Web Vitals are used by its ranking systems, but good scores do not guarantee top rankings. Neither platform replaces useful content, crawlable links, or accurate service information. This article reports no controlled Astro-versus-WordPress experiment, so it makes no percentage-speedup or ranking-uplift claim.

The acceptance criterion should be a usable, measured website, not the framework name on the proposal.

Account for maintenance on both sides

WordPress maintenance has a familiar shape

WordPress needs a plan for core, theme, and plugin updates, backups, access control, and recovery. Its security guidance describes security as risk reduction rather than risk elimination. Managed hosting can take responsibility for some tasks; check which ones the agreement actually covers.

Test important functions after changes. For a service business, a working contact form matters more than a dashboard that says every plugin is current. The separate guide to WordPress maintenance covers the work in more detail.

Static delivery removes some responsibilities, not all of them

A fully static Astro frontend does not need a WordPress application or database to serve its pages. Removing that public application layer removes the need to maintain it. But the repository, dependencies, deployment accounts, domain, and hosting still need care. Forms, APIs, and any connected CMS bring their own responsibilities.

A compromised deployment account can replace a static site. A broken dependency can prevent the next build. If the site uses on-demand rendering, its runtime also needs maintenance. “Nothing to patch” is not a credible handover promise.

Compare ownership costs across the same scope: implementation, hosting, editor support, integrations, updates, recovery, and eventual handover. Do not compare basic static hosting with a WordPress agreement that also includes technical support. Ask who owns each task and what happens when that person is unavailable.

Check forms, bookings, and checkout early

A static page can display a form, but submitting it still needs a receiving service or server endpoint. Choose that destination before launch. Test validation, spam controls, delivery failures, and the confirmation message. A success screen should mean the receiving system accepted the request, not merely that the visitor clicked a button.

For appointments, distinguish a link to an existing booking service from a custom booking application. A local consultant who already uses a scheduling service may need only a clear link. A business managing staff calendars, deposits, cancellations, and customer accounts has a larger integration problem.

The same distinction applies to selling online. WordPress can use a commerce plugin such as WooCommerce. Astro can connect to a commerce backend, but the framework itself is not an order-management system. Define who handles products, inventory, payments, refunds, and customer notifications before selecting the frontend.

List the business operations first. If an established WordPress plugin already supports them well, replacing it with custom integrations needs a specific benefit. If the business already runs those operations in another service, its website may not need to duplicate them.

Use headless WordPress only for a specific reason

Astro and WordPress can work together. In a headless setup, WordPress manages content while Astro renders the public website. The official Astro integration guide explains how to retrieve content through the WordPress REST API.

This is useful when editors need to retain WordPress while developers need a separate frontend. The guide to how a headless CMS works explains that separation more broadly.

It also leaves two systems to operate. For a statically built frontend, publishing in WordPress must trigger a successful build and deployment before visitors see the new content. Draft previews, failed builds, redirects, and cache invalidation need deliberate handling. WordPress plugins that expect to render their own frontend do not automatically become Astro components.

Keep private drafts behind appropriate authentication. Treat HTML returned by a CMS according to its trust boundary; rendering a string as HTML is not a substitute for controlling who can supply it.

Choose this combination to preserve a valuable editorial workflow or meet a frontend requirement. It is usually unnecessary complexity if a conventional WordPress site already does the job.

Work through a small-business example

Consider a hypothetical electrical contractor with eight service pages, a project gallery, a contact form, and an existing external scheduling tool. The owner changes service descriptions occasionally and wants someone else to handle technical maintenance. These are example requirements, not a client case or measured experiment.

Astro is a reasonable starting point. The service pages can be prebuilt, the gallery can use optimized images, and the booking action can link to the scheduling tool. The proposal still needs to explain how the owner requests content changes and how urgent corrections are handled.

Now change one requirement: an office manager must publish new projects independently every week. Astro can still work, but a suitable CMS becomes part of the proposal. WordPress deserves a fresh comparison because its editor may meet that requirement with less integration work.

Change another requirement: the business already relies on a WordPress plugin to coordinate bookings and payments. Keeping WordPress may now be the lower-risk choice. Rebuilding a working operational system just to change the frontend is a much larger decision than replacing a brochure site.

Use this exercise in discovery. Change the requirements and see whether the recommendation changes. If the answer is always the developer's favorite framework, the evaluation is not doing its job.

Decide whether a migration is worth doing

A working WordPress site does not need replacement because Astro exists. First identify the problem: slow pages, an unusable editor, excessive maintenance, or a design that no longer fits the business. Some problems can be fixed without changing platforms.

If a migration is justified, make an inventory of existing URLs, content, images, metadata, forms, and integrations. Preserve useful URLs where possible. Map changed URLs to relevant destinations instead of sending everything to the homepage, and check internal links after the move.

Avoid these common shortcuts:

Comparing a minimal Astro demo with an unoptimized production WordPress site.
Calling static delivery maintenance-free.
Assuming every editor needs a CMS, or assuming nobody does.
Replacing a working booking or checkout workflow without testing its replacement.
Promising better rankings simply because the framework changes.

Before signing off, request a demonstration of editing, publishing, and recovery, plus a written handover plan. Choose Astro for a content-focused site with an agreed editing workflow and capable technical ownership. Choose WordPress when its editor or established integrations solve the business's needs more directly. Keep the current site when the migration cannot justify its disruption.

Frequently asked questions

Is Astro better than WordPress for a small business?

Astro is a strong option for a content-focused site with an agreed editing workflow and technical support. WordPress is often the more direct choice when staff need its built-in editor or established plugins. Choose the complete setup, not the framework in isolation.

Can a nontechnical owner update an Astro website?

Yes, if the project includes an appropriate CMS or editing interface. Astro alone does not provide a WordPress-style dashboard. Without an editor, content changes usually go through someone comfortable with the project's files and publishing workflow.

Does switching to Astro improve SEO automatically?

No. Astro can support a lightweight implementation, but rankings also depend on content relevance and other signals. A migration must preserve useful URLs, internal links, metadata, and indexability. Good performance scores do not guarantee higher rankings.

Can Astro use WordPress as its CMS?

Yes. Astro can retrieve content through the WordPress REST API while WordPress remains the editing system. The project still needs WordPress maintenance, frontend deployment, and a tested approach to previews and publishing.

Image concepts

Image production is outside this demonstration's scope. These are concepts, not existing assets. No placeholder image tags have been inserted. The inline concepts are optional editorial suggestions, not instructions to override the site's image policy.

Featured image: two publishing workflows

Role: Explanatory editorial illustration.
Placement: After the opening paragraph.
Suggested filename: astro-vs-wordpress-publishing-workflows.webp
Alt text: “A browser editor and a file-based publishing workflow both leading to a finished business website.”
Prompt: Create a wide 16:9 editorial 3D illustration showing two equally credible publishing routes. On the left, a browser editing panel with content blocks; on the right, document files passing through a build stage. Both connect to the same finished small-business website. Use a warm beige #E9E6DF background, substantial charcoal forms, paper-colored panels, and several lime accents. Crisp edges, restrained glass details, clear directional connections, studio lighting. Avoid winner trophies, speed gauges, logos, fabricated screenshots, tiny text, people at laptops, and decorative clutter.

Inline concept: the editing acceptance test

Role: Workflow diagram.
Placement: “Test editing before choosing the stack.”
Suggested filename: website-editor-acceptance-test.webp
Alt text: “Editing test showing an opening-hours change, photo replacement, preview, and publication.”
Prompt: Design a readable 4:3 workflow diagram with four connected stages: edit opening hours, replace a photo, preview the page, publish the update. Show recognizable content panels rather than brand-specific interfaces. Use beige #E9E6DF, charcoal, paper, and lime. Give every stage generous space. Add labels during design production for accurate typography. Avoid fake software screenshots, approval badges, decorative people, and implied measured results.

Inline concept: what visitors receive

Role: Architecture comparison.
Placement: “Compare finished pages, not framework promises.”
Suggested filename: astro-wordpress-page-delivery.webp
Alt text: “Static Astro delivery beside WordPress delivery with separate cache-hit and cache-miss paths.”
Prompt: Create a wide technical diagram with two horizontal lanes. Astro: content and templates, build, static files, visitor. WordPress: visitor request, page cache, cached response; show a separate cache-miss branch to application and database before returning HTML. Add a small annotation area for Astro's optional on-demand rendering. Use matching visual weight for both lanes, beige background, charcoal connectors, and lime route highlights. Avoid latency numbers, winner labels, or implying every WordPress visit queries a database.

Inline concept: maintenance ownership

Role: Responsibility diagram.
Placement: “Account for maintenance on both sides.”
Suggested filename: website-maintenance-responsibilities.webp
Alt text: “Shared website responsibilities alongside WordPress application maintenance and Astro build maintenance.”
Prompt: Create a 4:3 responsibility diagram. Put shared tasks in a central column: domain, accounts, hosting, integrations, recovery. Place WordPress core, themes, plugins, and database on one side; Astro dependencies, build workflow, and optional runtime or CMS on the other. Use paper cards over warm beige, charcoal typography, and lime grouping markers. Keep the mood practical and neutral. Avoid shields suggesting immunity, empty Astro maintenance columns, numerical risk scores, and logos.

Structured data

The following draft JSON-LD parses successfully, and all four FAQ questions and answers match the article.

Publication-specific fields are deliberately absent: image, url, mainEntityOfPage, author identity, and publication dates must come from the approved publication and real assets. This is a draft schema, not a claim that a page or image has been published.

FAQPage remains a Schema.org type, but Google's documentation changelog states that FAQ rich results are no longer shown. This markup is not a promise of search-result enhancements.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "BlogPosting",
      "headline": "Astro vs WordPress: choose for the person editing",
      "description": "Astro vs WordPress for small business websites: compare editing, speed, maintenance, and integrations. Use a practical checklist to choose your setup.",
      "inLanguage": "en-US",
      "about": [
        {
          "@type": "Thing",
          "name": "Astro"
        },
        {
          "@type": "Thing",
          "name": "WordPress"
        }
      ]
    },
    {
      "@type": "FAQPage",
      "inLanguage": "en-US",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "Is Astro better than WordPress for a small business?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Astro is a strong option for a content-focused site with an agreed editing workflow and technical support. WordPress is often the more direct choice when staff need its built-in editor or established plugins. Choose the complete setup, not the framework in isolation."
          }
        },
        {
          "@type": "Question",
          "name": "Can a nontechnical owner update an Astro website?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Yes, if the project includes an appropriate CMS or editing interface. Astro alone does not provide a WordPress-style dashboard. Without an editor, content changes usually go through someone comfortable with the project's files and publishing workflow."
          }
        },
        {
          "@type": "Question",
          "name": "Does switching to Astro improve SEO automatically?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "No. Astro can support a lightweight implementation, but rankings also depend on content relevance and other signals. A migration must preserve useful URLs, internal links, metadata, and indexability. Good performance scores do not guarantee higher rankings."
          }
        },
        {
          "@type": "Question",
          "name": "Can Astro use WordPress as its CMS?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Yes. Astro can retrieve content through the WordPress REST API while WordPress remains the editing system. The project still needs WordPress maintenance, frontend deployment, and a tested approach to previews and publishing."
          }
        }
      ]
    }
  ]
}

Internal linking plan

This article links to

Destination	Anchor used	Purpose
Website without a CMS	website without a CMS	Show the site's documented file-based content workflow.
WordPress maintenance	WordPress maintenance	Keep detailed maintenance coverage on its existing page.
What is a headless CMS?	how a headless CMS works	Explain the architecture without expanding this comparison into a separate CMS tutorial.

The headless anchor follows a recorded query variation. The maintenance anchor is a natural topic description; no ranking claim is made for that exact phrasing. The newer no-CMS article has no demonstrated cluster in the inspected snapshot.

Publishing checklist

Completed for this demonstration

[x] Full article delivered in US English.
[x] Article exceeds 1,000 words.
[x] Hook-driven title and metadata lengths checked.
[x] Existing coverage and verified keyword clusters inspected.
[x] Official sources consulted for technical claims.
[x] Hypothetical scenario clearly distinguished from client evidence.
[x] Table of contents mirrors the article's H2 sections.
[x] Four visible FAQ answers supplied.
[x] Draft JSON-LD parsed and FAQ text parity verified.
[x] Final language pass removed promotional claims and unsupported certainty.
[x] Website, Git, GitHub, authentication, and third-party content left unchanged.

Required only if publication is later approved

[ ] Confirm the route and recheck overlapping coverage.
[ ] Obtain editorial approval and confirm the author byline.
[ ] Set actual publication and modification dates.
[ ] Produce the approved featured image; set alt text and Open Graph metadata.
[ ] Decide whether any optional inline diagrams fit the site's editorial policy.
[ ] Verify asset format, dimensions, and file size.
[ ] Populate structured-data image and publication fields with verified values.
[ ] Integrate with existing schema output without duplicate article or FAQ nodes.
[ ] Configure the appropriate canonical URL for the publication destination.
[ ] Add approved contextual links in both directions.
[ ] Verify rendered links, heading anchors, mobile tables, and desktop/mobile layout.
[ ] If published, assess Search Console results after at least 30 days.

This is the complete demonstration draft and writing package. Nothing has been published.

This is writing output to review, not an approved article. A short follow-up narrows the same draft to developers maintaining the site:

Hermes Agent: focus the outline on developers gpt-6-astra

You

Focus on developers maintaining the site. Show me the outline first.

Agent

Proposed title
Astro vs WordPress: what developers maintain after launch

Audience
Developers responsible for small business websites after handover: content changes, dependency updates, forms, production failures, and eventual migration.

Angle
Compare the work each setup leaves you with. Keep the earlier draft's distinctions around caching, headless WordPress, and editing, but move the focus from the owner's platform choice to the maintainer's responsibilities.

Outline

Choose the maintenance model before the framework

Open with the recommendation:
- Static Astro is a strong fit when the site mostly publishes content and its publishing workflow has a clear technical owner.
- Conventional WordPress is often more practical when its editor and established plugins already meet the business's needs.
- Keeping a working site is a valid outcome.

Define the comparison: static-first Astro versus conventional WordPress with sensible caching and maintenance. Cover on-demand Astro and headless WordPress as separate configurations.

What changes when the public site becomes static?

Explain the request path briefly, then connect it to operational work:
- Prebuilt Astro pages versus cached and uncached WordPress responses.
- What removing a public PHP application and database removes from maintenance.
- What remains: dependencies, deployment access, hosting, domains, and integrations.
- How adding SSR changes the responsibilities again.

Include one compact comparison table organized by maintenance task, not feature scores.

Follow a content change from request to production

Trace the same change through both setups: update a service description and replace its image.

Cover:
- WordPress editing, preview, publication, and cache invalidation.
- Astro file changes or CMS updates, validation, build, and deployment.
- Diagnosing “published in the editor, missing on the website.”
- Who handles urgent corrections when the usual maintainer is unavailable.

Treat the editor as part of the system the developer supports, not a separate convenience.

Updates and recovery: what happens when something breaks?

Use two clearly labeled hypothetical incidents:
- A WordPress plugin update breaks the contact form.
- An Astro dependency update prevents deployment.

Explain:
- Staging, backups, dependency locks, and focused regression checks.
- The difference between a failed build and a broken live deployment.
- Why a code rollback does not necessarily reverse database changes.
- What a recovery procedure must cover beyond “revert the commit.”

Takeaway: define and test recovery for the actual deployment setup.

Forms and bookings often determine the workload

Follow the business-critical path beyond the frontend:
- Form submission, validation, spam protection, and delivery.
- Embedded scheduling tools versus booking plugins or custom integrations.
- Payments, webhooks, and external service failures where relevant.
- Checks that prove an inquiry reached its destination.

Show when replacing a working plugin creates more maintenance than it removes.

Headless WordPress: keep the editor, accept another system

Explain when Astro plus WordPress is justified.

Cover the additional work:
- API access and private previews.
- Build triggers, publication delays, and failed updates.
- Rendering blocks and features that previously depended on the theme.
- Maintaining both WordPress and the Astro frontend.

Keep this section short: an operational trade-off, not an integration tutorial.

Make the decision against the site you actually maintain

Apply the comparison to a hypothetical small service-business site. Change its requirements to show when the recommendation changes.

End with a practical checklist:
- Who edits, and how urgently?
- Which integrations already work?
- Who owns updates and recovery?
- What can another developer take over?
- Could the current site's problems be fixed without migrating?

Include performance checks here: representative pages, real scripts and embeds, consistent test conditions, and no automatic SEO benefit.

Frequently asked questions

Does a static Astro site still need dependency updates?
Can a failed Astro build take the live website down?
Does managed WordPress hosting remove the developer's maintenance work?
When does headless WordPress justify maintaining two systems?

Essential editorial decisions

Use developer-to-developer language. Explain business consequences without turning the article into a sales pitch.
Keep the public Straffe Sites content-in-Git example, but use it only as architecture evidence, not proof that Astro wins universally.
Replace the earlier owner's editing test with publishing, failure diagnosis, and recovery workflows.
Avoid fabricated maintenance hours, cost savings, benchmarks, or first-person incident stories.
Keep detailed migration instructions and framework setup code out of scope.
End with a maintenance decision checklist rather than a contact CTA.
Visual concepts only: a publishing-flow diagram and a recovery-path comparison. No images or article implementation at this stage.

An outline lets you check the angle before another writing pass. Give Hermes your own code, notes, or test results when you want first-hand examples; the agent cannot invent your experience.

Audit an existing page

The URL is enough to request a page audit. Hermes loads the audit skill, examines the page, and identifies improvements. If its GSC connection has access to that property, it can use the search data too; otherwise it should explain that limitation.

Hermes Agent: SEO audit (compatible trace import) gpt-6-astra

You

/notfair-seo-page https://straffesites.com/en

Agent

Page SEO Analysis — https://straffesites.com/en

September 13, 2026 · GSC data: June 13–September 10, 2026 · 90 days, final data

The page is indexed, its canonical is correct, and its technical foundation is strong. The main opportunity is clearer, better-qualified commercial messaging—not an indexability repair.

The audited URL is the English business homepage, not a developer tutorial. It should help prospective clients understand the service, assess the evidence, and contact the team. Tutorial content is supporting material.

Overall Score: 7.8/10

These are editorial assessments, not Google scores, PageSpeed measurements, or ranking predictions. GSC metrics and browser observations are identified separately.

Dimension	Score	Weight	Weighted
Search Intent Alignment	8.0/10	20%	1.600
E-E-A-T Signals	7.5/10	20%	1.500
Content Quality & Depth	7.0/10	20%	1.400
On-Page SEO	8.5/10	15%	1.275
Content Structure & UX	8.0/10	15%	1.200
Technical SEO	8.5/10	10%	0.850
Overall			7.825 → 7.8

Why these scores

Dimension	What earns the score	What prevents a higher score
Search intent	Services, portfolio, process, and “Discuss your project” fit a commercial homepage.	The headline emphasizes speed without immediately identifying the small-business audience. Actual GSC queries are sparse and ambiguous.
E-E-A-T	Named contact, 12 linked case studies, linked Google reviews, technical explanations, and an HTTP Archive citation.	Hero performance claims lack an adjacent measurement date, sample definition, and clearly named loading metric.
Content quality	Covers services, examples, process, editing, support, and terminology.	Buyers get limited detail about project scope and delivery dependencies. A substantial part of the content is article-card text rather than buyer guidance.
On-page SEO	Complete metadata, one H1, descriptive links, responsive WebP images, and language annotations.	Minor English-copy issues and an opportunity to make the title more audience-specific.
Structure and UX	Short sections, a clear primary CTA, native FAQ disclosures, and no horizontal overflow in the tested viewports.	The article rail contains 34 cards, which may be more choice than a homepage visitor needs. No conversion or usability study was available.
Technical SEO	Google confirms indexing; server-rendered content, self-canonical, valid JSON-LD parsing, HTTPS, and responsive geometry.	No fresh Lighthouse or URL-level field-performance assessment was run, and this was not a full accessibility or asset audit.

Top Priority Fixes

No critical indexability blocker was found.

The biggest improvement would be making the existing performance evidence precise and easy to verify. Strong numbers are useful only when visitors understand what was measured.

#1 — Qualify the hero’s performance claims

🟡 High

Score impact: Potentially +0.5 in E-E-A-T and +0.5 in Content Quality. These are editorial estimates, not projected ranking gains.

Current:

“Our case sites reach a 98/100 median mobile PageSpeed score; the fastest loads in 0.9 seconds.”

Fix:

Add a nearby evidence link and state:

The measurement period.
The number of measured case sites.
How the median was calculated.
Which metric the 0.9-second figure represents.
Whether the measurement is from a lab test or real-user data.

Do not describe LCP as total page-load time if LCP is the underlying metric.

A safe nonnumeric alternative, pending verification of those details:

“Explore our case studies for monthly PageSpeed measurements and Search Console reporting.”

Why: The audit verified that the numbers appear on the page; it did not independently reproduce them. Clear provenance strengthens trust and avoids confusing a lab performance score with a visitor-experience guarantee.

#2 — Update the “latest” HTTP Archive comparison

🟡 High

Score impact: Potentially +0.5 in Content Quality and +0.5 in the Trustworthiness subscore.

Current heading:

“We build with Astro — the Core Web Vitals leader in the latest HTTP Archive comparison”

Current explanation:

“In July 2026, 69% of measured mobile Astro sites had good Core Web Vitals, compared with 49% for WordPress and 33% for Next.js.”

Verified finding: The linked source confirms those July values. However, it now displays August 2026 as the latest period, with Astro at 71%, WordPress at 48%, and Next.js at 35%.

Fix:

Suggested heading:

“Astro leads this Core Web Vitals comparison”

Suggested explanation:

“In HTTP Archive’s August 2026 mobile comparison, 71% of measured Astro origins had good Core Web Vitals, compared with 48% for WordPress and 35% for Next.js.”

Keep the source link. Explain that an origin groups pages under the same protocol, host, and port; this is not a measurement of every page built with a framework.

Why: The existing July figures are not fabricated or disproved, but “latest” is stale. Framework-level comparisons also do not prove that a particular website will pass Core Web Vitals.

#3 — Make the audience more explicit in the search snippet

🟢 Medium

Score impact: Potentially +0.5 in Search Intent Alignment and +0.3 in On-Page SEO.

Current title:

“Straffe Sites — rock-solid websites that load fast”

Current H1:

“A rock-solid site that loads fast”

Fix:

Test this title rather than assuming the existing one is underperforming:

“Fast websites for small businesses | Straffe Sites”

The proposed title is 50 characters.

Keep the distinctive H1 if desired, but make the first sentence more explicit:

“We design and build fast websites and online stores for independent professionals and small businesses. Seppe is your main contact, supported by a senior team.”

Why: The current meta description already identifies the audience. Bringing that clarity into the title or opening sentence helps qualified visitors recognize the fit.

GSC does not show a proven CTR problem here. This is a relevance hypothesis, not a fix justified by a statistically reliable CTR deficit.

#4 — Give buyers more useful project-planning answers

🟢 Medium

Score impact: Potentially +0.5 in Content Quality.

Current timeline answer:

“It varies by project. Because you work directly with the developer, communication is quick. After our first conversation, you’ll get a realistic schedule.”

Fix:

Explain the factors that determine the schedule without inventing a delivery promise:

“The schedule depends on the number of pages, content readiness, custom integrations, and feedback rounds. After the first conversation, we outline the project milestones and what we need from you.”

Review the content-editing answer in the same way: distinguish projects with an editor-friendly CMS from projects where content is maintained through a development workflow.

Why: Competitors explain publishing autonomy, migrations, and ongoing delivery in more detail. A few concrete answers would help buyers qualify their project without turning the homepage into a technical manual.

E-E-A-T Breakdown

Signal	Score	Evidence
Experience	8/10	Twelve named case-study cards and practical delivery language: “You speak directly with the builder” and “You see the progress as it happens.” The homepage does not itself show detailed before-and-after evidence.
Expertise	8/10	Correctly identifies LCP, INP, and CLS in the glossary; explains integrations, maintenance, CMS editing, and a staged delivery process. The hero’s “loads in 0.9 seconds” wording lacks metric precision.
Authoritativeness	7/10	Seppe is named, the team page is linked, the server-rendered content states “25+ years of experience,” and relevant case studies and technical articles are linked. Independent reputation and backlinks were not assessed.
Trustworthiness	7/10	HTTPS, direct contact details, legal links, a Google-review link, and an HTTP Archive citation. The review rating and case-performance aggregate were not independently remeasured; the “latest” comparison needs updating.

YMYL: This is not primarily a health, financial-advice, legal-advice, or safety page. Health-related client names in the portfolio do not make the homepage a medical-advice resource.

E-E-A-T Gaps to Close

Attach measurement context directly to the hero’s numerical claims.
Keep dated comparisons synchronized with their sources, or remove “latest.”
Consider one short, permission-cleared client quotation with attribution and a relevant case link. Do not invent a testimonial.
Make ownership, handover, and editing responsibilities clearer where the actual service agreement supports those claims.

The page displays “4.9/5 on Google” and “26 reviews.” These are observed page claims, not independently verified review metrics from this audit.

Search Intent Analysis

Target keyword: “Fast websites for small businesses” is an inferred commercial theme, not an established high-volume query for this URL.

Actual leading disclosed GSC query: “fast sites,” with 3 clicks and 17 impressions.

Intent type: Commercial service selection and branded navigation.

Content format match: Yes for the commercial theme; uncertain for the ambiguous query “fast sites.”

Search-result reality check

Two searches were used to avoid judging intent from the homepage alone.

Search	Observed result sample	Interpretation
`fast website development small business Astro agency`	Astro Partner Agencies; Astro’s framework homepage; Lucky Media; Seibert; Opace	A mixture of agency discovery, commercial service pages, and framework information. The homepage’s service format is compatible.
`fast sites`	Louisiana’s FastSites program; a governor’s announcement; WAFB coverage; a Catchpoint performance article; Louisiana Illuminator coverage	Strong ambiguity. This is not a clean web-development purchase query in the returned sample.

These are current search-tool results, not a controlled Google rank-tracking study. Geography, device, and personalization were not matched to the historical GSC impressions.

Conclusion: Do not optimize the homepage around “fast sites” simply because it produced three clicks. Preserve the homepage’s brand and service role, and let dedicated service pages own narrower purchase queries.

SERP Feature Opportunities

Feature	Optimized?	Fix
Featured snippet	Not established	No featured-snippet ownership was confirmed. Do not add a long informational section solely to chase one.
People Also Ask	Structurally prepared	Four visible FAQs provide question-and-answer content, but PAA appearances were not reported by the search tool. Improve buyer usefulness rather than promising placement.
Rich results	Markup present; appearance unconfirmed	Organization, WebSite, and FAQPage JSON-LD parse successfully. URL Inspection did not return a rich-result assessment. Markup does not guarantee an enhanced result.
Image results	Basic preparation present	Descriptive alt text and WebP assets exist. Image-search visibility was not measured.

On-Page SEO Audit

Metadata

Element	Current	Status	Recommendation
Title tag	“Straffe Sites — rock-solid websites that load fast” — 50 characters	Good length and clear benefit	Consider the audience-specific variant above. No demonstrated truncation problem.
Meta description	“The Straffe Sites team designs and builds fast websites and online stores for independent professionals and small businesses, with no agency in between.” — 152 characters	Complete and relevant	Retain the audience clarity. A stronger invitation to view work is optional, not essential.
H1	“A rock-solid site that loads fast”	One H1; clear benefit	Clarify the service and audience in the adjacent introduction.
Canonical	`https://straffesites.com/en`	Correct	Google-selected and user-declared canonicals agree.
Robots metadata	No robots meta tag; no X-Robots-Tag in the checked response	No exclusion detected	An explicit `index,follow` tag is unnecessary.
Open Graph	Title, description, URL, image, type, site name, and `en_US` locale	Complete	The declared 1200×630 image URL returned HTTP 200; visual preview not reviewed.
Twitter Card	`summary_large_image`, title, description, and image	Complete	No urgent change.
Language	HTML `lang="en"`	Appropriate	Continue using US English consistently.
Hreflang	`nl`, `en`, and `x-default`	Present on the audited page	Reciprocal annotations on the Dutch page were outside this page-only audit.

Sitewide title and description uniqueness was not tested.

Heading Structure

The main content has one H1 and a consistent H2 → H3 hierarchy.

H1: A rock-solid site that loads fast
  H2: We build with Astro — the Core Web Vitals leader in the latest HTTP Archive comparison
  H2: One team, everything for your site
    H3: Web development
    H3: Custom features & integrations
    H3: Website maintenance
    H3: Technical partner
    H3: AI design to website
  H2: Work with real personality
    H3: Verhuurwinkel.nl
    H3: Straffe Sites
    H3: Voltti.ai
    H3: Gitaarlessen Boeckx
    H3: 2140 Boxing Training
    H3: Figur
    H3: New Impact
    H3: Roulez Roulez
    H3: sympl
    H3: ZET
    H3: HWV Facilities
    H3: CLW Antwerpen
  H2: How we work together
    H3: Introduction
    H3: Design
    H3: Build
    H3: Launch & support
  H2: No agency. Just a senior team
  H2: Keep reading
    H3: 34 linked article titles
  H2: Frequently asked questions
  H2: Terms
    H3: CMS
    H3: Responsive web design
    H3: Core Web Vitals
    H3: SEO
    H3: Web hosting
    H3: Website maintenance
  H2: Ready for a rock-solid site?

The article-card H3s cover CMS integrations, websites without a CMS, agency SEO research, lab versus field performance, website costs, semantic markup, AI writing, Search Console, Storyblok, Astro, hiring developers, maintenance, keyword research, and implementation tutorials.

Navigation and contact-interface headings also exist outside <main>. They are not extra page H1s.

Assessment: Logical structure. The main weakness is not heading hierarchy but emphasis: the long framework-comparison heading is more technical than the buyer-oriented service headings.

Internal Links

Found 122 same-origin link elements across the document, including navigation, repeated destinations, and fragment links. 63 are inside <main>.

These are link-element counts, not counts of unique destination pages.

Anchor text or card heading	Target	Quality
Discuss your project	`/en/contact`	Clear conversion action
See recent work ↓	`/en#werk`	Useful on-page navigation; target exists
Web development	`/en/website-development`	Relevant; card description adds context
Custom features & integrations	`/en/web-development`	Descriptive and differentiated
Website maintenance	`/en/website-maintenance`	Strong service anchor
AI design to website	`/en/ai-design-to-website`	Specific service intent
Meet the team ↗	`/en/team`	Useful trust destination
Straffe Sites case card	`/en/case/straffe-sites`	Useful supporting evidence
Core Web Vitals	`/en/glossary/core-web-vitals`	Relevant explanation
View all articles	`/en/blog`	Appropriate directory action

The checked contact, service, team, and own-case destinations returned HTTP 200 without a redirect. This was a targeted check, not a full crawl of every link.

The large link count is not automatically an SEO defect. Much of it comes from the portfolio, article rail, and navigation. A shorter article selection could improve decision-making, but there is no measured evidence here that link count is harming rankings.

External Links

Two outbound HTTPS link elements were found:

Link	Purpose	Assessment
Google reviews	Reputation evidence	Useful direct source; rating and count not independently confirmed
HTTP Archive comparison	Framework-performance citation	Source inspected successfully in a browser; July values confirmed and newer August values found

Email and telephone links are contact actions, not external web citations.

Images

Found 49 <img> elements:

Image group	Count	Format and attributes	Assessment
Case-study images	12	WebP, width/height attributes, responsive candidates, lazy loading	Strong implementation
Article-card images	34	WebP, 800×450 declared dimensions, lazy loading	Mostly responsive candidates; four have only an 800w candidate
Reused Seppe portraits	3	WebP with responsive candidates	Two lazy-loaded; the review avatar uses normal browser loading

All images have an alt attribute and declared width and height. 48 are lazy-loaded. One review-avatar image has empty alt text; that can be appropriate because the surrounding review link already has an accessible label.

Representative findings:

Image	Current alt text	Issue or recommendation
Verhuurwinkel case	“Players in transparent bubble suits running at each other during a game of bubble football”	Descriptive and relevant
Straffe Sites case	“…against a light grey background”	Use “gray” for consistent US English
Figur case	“…with grey curly hair…”	Use “gray”
New Impact case	“Camera operator filming a effects technician…”	Correct to “an effects technician”
CMS article illustration	“Abstract Straffe Sites illustration of AI agents connecting to a CMS through MCP”	Understandable; avoid adding keywords merely for SEO

Four article assets with only an 800w candidate were observed at encoded sizes of 7,288, 17,778, 7,446, and 18,088 bytes. Smaller variants might save bytes, but these are not evidence of a major performance problem.

Content Quality Assessment

Helpful Content Signals

Signal	Present?	Evidence
Clear target audience	Partial	The meta description names independent professionals and small businesses; the hero is broader.
Answers the query completely	Mostly	Services, portfolio, process, content editing, maintenance, and contact are covered. Project-planning detail is limited.
Original value added	Yes	Named projects, a direct-contact model, and linked measurement-oriented case studies.
Passes the “Last Click” test	Partial	Enough to begin a conversation; less useful for comparing scope, handover, and ongoing responsibilities.
Appropriate depth	Yes, with a composition caveat	1,167 words in the extracted main-content text, including FAQs, glossary cards, and article-card text.
First-hand knowledge	Yes	Practical delivery descriptions and a substantial linked portfolio.
Human-first presentation	Mostly	Direct language and clear CTAs; the long article rail serves several audiences at once.

Word-count method: Text nodes were joined with spaces; scripts, styles, navigation, and aside elements were excluded. The same method was used for the competitor comparisons. Counts describe content volume, not quality or words visible simultaneously on screen.

No page-level publication or update date was found in <time> elements or the JSON-LD. A homepage does not require an article-style date, but numerical claims should carry their own date.

Content Gaps vs Competitors

Two commercial pages from the exploratory search were fetched and inspected. They are comparison references, not proof that Straffe Sites competes against them for every query.

Competitor	Page type	Measured main-content words	Relevant strengths
Lucky Media	Detailed Astro agency service page	4,327	Named client quotations, migration examples, publishing autonomy, ownership, retainer support
Seibert	Astro agency landing page	1,584	Development, migration, performance optimization, integrations, consulting, and maintenance explanations
Straffe Sites `/en`	General commercial homepage	1,167	Broad portfolio, small-team model, direct contact, concise service overview

Lucky Media H2 topics: platform limitations; delivered Astro projects; customer pain points; reasons to choose the agency; promise; process; services; enterprise projects; ongoing support; features; FAQs.

Seibert H2 topics: business impact of performance; publishing workflows; Astro performance; islands; performance demonstration; services; FAQs; UI kit; company scale; partnership; contact.

Topic/subtopic	This page	Competitor evidence	Action
Who the service is for	Explicit in metadata; broad in hero	Both identify more specific buyer scenarios	Make the opening audience clearer
Content-editing autonomy	One brief FAQ answer	Both explain publishing workflows in more depth	Clarify available editing approaches
Migration concerns	Not explained in the main service overview	Both describe migration work	Add a short answer or link if this is part of the intended offer
Ownership and handover	Not clearly stated in the homepage copy	Lucky Media explicitly discusses ownership and lock-in	State only verified contractual terms
Attributed customer testimony	Aggregate Google-review badge	Lucky Media displays named quotes and roles	Consider one approved, relevant quote
Ongoing support	Present but brief	Both describe support more specifically	Explain responsibilities and next steps without publishing prices

Do not copy competitors’ absolute promises about rankings, “instant” loading, or guaranteed performance. More aggressive wording is not better evidence.

Technical SEO

Check	Status	Details
HTTP response	Pass	Audited URL returned HTTP 200
Indexability	Indexed	URL Inspection: `PASS`, “Submitted and indexed”
Robots.txt	Pass	HTTP 200; `User-agent: *` and `Allow: /`
Indexing directives	Pass	Google reports `INDEXING_ALLOWED`; no checked meta/header exclusion
Canonical	Pass	User-declared and Google-selected canonical both equal `https://straffesites.com/en`
Last Google crawl	Confirmed	September 5, 2026, 19:09:45 UTC; successful fetch; crawled as mobile
Server-rendered content	Pass	Full main content available in fetched HTML, not an empty JavaScript shell
Mobile readiness	Positive bounded evidence	No horizontal document overflow at 390px; viewport metadata present
Desktop layout	Positive bounded evidence	No horizontal document overflow at 1440px
H1 wrapping	Pass in tested layouts	Two measured line bands at both 1440px and 390px
Primary CTA	Adequate measured size	Approximately 240×53px on desktop and 350×53px on mobile
Intro text	Readable measured size	20.8px desktop; 18px mobile
FAQ container	Contained on mobile	Heading begins 20px from the left and remains inside the viewport
Schema markup	Basic checks pass	Organization, WebSite, and FAQPage JSON-LD parse; all four FAQ answers match the page text
Rich-result status	Unconfirmed	Inspection returned no rich-result assessment
Google mobile-usability verdict	Unspecified	`VERDICT_UNSPECIFIED`; this is not a mobile-usability pass
Page-speed signals	Favorable proxies only	No external stylesheet links; one inline head style block; module scripts and asynchronous analytics
Fonts	Positive	Local WOFF2 fonts, two font preloads, and `font-display: swap` declarations
DOM size	Observed, not diagnosed	968 elements in the inspected document
HTTPS/mixed content	Pass in checked markup	HTTPS; no HTTP URLs found in inspected `src`/`href` attributes
Core Web Vitals	Not measured for this URL	No fresh field-data or Lighthouse verdict established

Browser geometry is not a substitute for visual review, assistive-technology testing, or real-user monitoring. No accessibility certification or full performance pass is claimed.

The page’s 98/100 case aggregate and the HTTP Archive framework percentages are not measurements of this homepage’s current Core Web Vitals.

GSC Performance Summary

Property: sc-domain:straffesites.com

Exact page: https://straffesites.com/en

Period: June 13–September 10, 2026

Data state: Final

Page totals were taken from page-dimension data, not reconstructed from disclosed query rows.

Metric	Value
Clicks, 90 days	7
Impressions, 90 days	105
Average CTR	6.67%
Average position	5.66
Trend	Too little data for a reliable growth or decline conclusion

Average position is a historical GSC aggregate—not the page’s current fixed rank.

Top Ranking Queries

All five disclosed query rows for this page are shown below.

Query	Avg. position	Clicks	Impressions	CTR	Expected CTR	Gap
fast sites	6.00	3	17	17.65%	3–4%, only if treated as transactional	+13.65 to +14.65 percentage points; intent uncertain
fast site	8.00	0	2	0%	1.5–3%, only if treated as transactional	−3 to −1.5 percentage points; sample too small
sites f	7.75	0	4	0%	N/A	Unclear intent; no suitable benchmark
straffe	6.13	0	8	0%	N/A	Could be brand-related or unrelated; insufficient evidence
websites starting with s	27.00	0	1	0%	N/A	Outside the supplied benchmark range; poor commercial fit

The benchmark ranges are generic reference bands, not measured expectations for these exact searches. No SERP-feature discount was applied because no relevant feature was confirmed.

Query-data limitation: Disclosed queries account for 3 of 7 clicks and 32 of 105 impressions: 42.86% and 30.48%, respectively. They are not the complete search-query picture.

There is no defensible basis for predicting additional clicks from a title change with this sample.

Trend Across Three Nonoverlapping 30-Day Periods

Period	Clicks	Impressions	CTR	Avg. position
June 13–July 12	2	26	7.69%	4.50
July 13–August 11	1	45	2.22%	6.04
August 12–September 10	4	34	11.76%	6.03

The latest period has more clicks but fewer impressions than the preceding period. With single-digit clicks, describing this as sustained growth would overstate the evidence.

No algorithm-update attribution is justified.

Cannibalization Check

The disclosed query fast sites appeared for:

Page	Clicks	Impressions	Avg. position
`/en`	3	17	6.00
`/`	0	15	3.47
`/blog/laadtijd-website`	0	1	5.00

This is query overlap, not proven harmful cannibalization.

The Dutch homepage had the stronger average position, while the English homepage received the disclosed clicks. Language and geography could explain part of that difference.

Do not consolidate the language homepages or change canonicals on this evidence. Maintain distinct language roles and monitor relevant query/page combinations over a longer period.

What to Improve Next

Correct small English-copy issues. Change “a effects technician” to “an effects technician” and standardize “grey” to “gray” in the observed alt text.
Evaluate the article rail as a commercial UX choice. It contains 34 cards. Consider whether a smaller curated selection would help buyers, while keeping the full blog directory available. This is a usability hypothesis, not a proven ranking fix.
Preserve the distinction between website builds and custom development. The links to /en/website-development and /en/web-development serve different roles. Keep their labels differentiated rather than targeting every service page with the same phrase.
Run a dedicated performance check before changing loading behavior. Current HTML and resource signals are favorable, but they do not establish LCP, INP, or CLS.
Reassess after at least 30 days following any future change. Keep a dated baseline, compare matching periods, and focus on qualified commercial queries. Low traffic may require a longer observation window.

Skill Handoffs

No follow-up workflow was executed.

Handoff	Purpose
Metadata optimization	Develop audience-specific title and description alternatives without assuming the current CTR is deficient
Content writing	Refine the hero’s evidence wording and expand buyer FAQs using verified service details
Keyword research	Validate relevant English commercial demand instead of treating “fast sites” as a reliable primary keyword
Structured-data review	Check search-feature eligibility separately from JSON syntax; no missing-schema emergency was found
Search Console follow-up	Reassess this exact URL after at least 30 days, with query/page overlap and low-volume limitations preserved

Bottom line: This is an indexed, technically sound commercial homepage with useful portfolio depth. The strongest next step is to make its evidence more precise and its buyer guidance more specific—not to add keywords indiscriminately, expand it into a tutorial, or chase an ambiguous query.

Its scores and recommendations are the agent's assessment, not a Google rating or a promise of results. You can narrow the audit to three priorities without letting it edit the page:

Hermes Agent: choose three audit priorities gpt-6-astra

You

Which three changes would you prioritize? Don't edit the page yet.

Agent

I’d prioritize these three changes to https://straffesites.com/en, in this order, based on the recorded audit.

Make the hero’s performance claims verifiable

The line “98/100 median mobile PageSpeed score; the fastest loads in 0.9 seconds” needs context.

Add a short measurement note and an evidence link stating the period, number of case sites, and calculation method. Identify exactly what the 0.9 seconds measures. If it is lab LCP, call it that rather than total loading time.

Until those details are verified, use:
“Explore our case studies for monthly PageSpeed measurements and Search Console reporting.”

Why first: Performance is the page’s central selling point. Visitors should be able to check the evidence without guessing what the numbers mean. The audit confirmed the claims were present, not that the aggregate was independently reproduced.

Correct the dated HTTP Archive comparison

The heading says “latest,” but the paragraph uses July 2026 figures. The audit confirmed those July figures and found August data in the linked source.

Suggested heading:
“Astro leads this Core Web Vitals comparison”

Suggested paragraph:
“In HTTP Archive’s August 2026 mobile comparison, 71% of measured Astro origins had good Core Web Vitals, compared with 48% for WordPress and 35% for Next.js.”

Keep the source link and briefly explain that these are framework-level results across measured origins, not a guarantee for an individual website. Avoid “latest” unless the wording is maintained with every update.

Why second: This is a specific, verified freshness issue in a prominent evidence block. Correcting it is more defensible than changing copy based on speculative keyword gains.

Make the service and audience explicit at the top

Keep “A rock-solid site that loads fast” as the H1. It already fits the tested desktop and mobile layouts. Clarify the audience in the opening sentence instead.

Suggested introduction:
“We design and build fast websites and online stores for independent professionals and small businesses. Seppe is your main contact, supported by a senior team.”

Suggested title:
“Fast websites for small businesses | Straffe Sites”

Put the qualified measurement note from priority one beside or below this introduction.

Why third: Prospective clients should immediately recognize what you build and whether it is for them. The existing meta description already does this better than the hero. I would not target “fast sites” aggressively: the recorded search results were ambiguous, and the page’s GSC sample was too small to establish a CTR problem.

These are editorial priorities, not Google ratings or promises of better rankings. I’d leave the indexed URL, canonical, schema, and broader layout alone for now. No page edits or new audit were performed for this follow-up.

Find a topic using Search Console

Use the planner when you haven't chosen a subject. Ask it to check whether an existing page already answers the question before proposing another article. Then take the topic you prefer to the writing skill.

Hermes Agent: choose three topics from Search Console gpt-6-astra

You

/notfair-content-planner https://straffesites.com
Suggest three article topics using my Search Console data.

Agent

I recommend three article refreshes rather than three new posts. Each topic already has a relevant page earning impressions; a new URL would split the same search intent.

Search Console connection verified: sc-domain:straffesites.com
Period: June 13–September 10, 2026, inclusive, finalized Web Search data.
Retrieved: September 13, 2026.

I checked 3,944 query/page rows, 258 page rows, your repository’s keyword clusters, and the current live articles. The property recorded 150 clicks and 336,530 impressions during this period.

What a website costs: compare quotes without surprises

Refresh the existing Dutch article:
https://straffesites.com/blog/wat-kost-een-website-laten-maken

Why this topic: It has the largest observed opportunity of these three, with substantial visibility for specific cost questions.

Query-level evidence for this page:
“wat kost een website laten maken”
5,391 impressions · 0 clicks · 0% CTR · average position 14.77

“website laten maken kosten”
8,859 impressions · 1 click · 0.011% CTR · average position 17.27

Whole-page context: 125,547 impressions and 33 clicks.

Writing angle: Turn the existing quote-comparison advice into a checklist readers can use alongside an actual proposal. Cover included work, revisions, content responsibilities, recurring costs, ownership, and exclusions. Keep the sourced market benchmarks already present.

Ownership warning: “goedkope website laten maken” appeared on both the budget article (3,548 impressions) and this cost guide (49). Online-store cost queries also overlap: “wat kost een webshop laten maken” received 116 impressions on this general guide and 43 on the dedicated online-store cost article. Keep budget-saving advice and online-store pricing detail on their respective pages. These overlaps are cannibalization signals, not proof of ranking damage.

Timing: This article received a substantive update on September 11, after the report ends. Review its performance no earlier than October 11 before making another SEO-driven rewrite.

Writing prompt:
Refresh the existing Dutch website-cost guide for Belgium and the Netherlands. Develop its quote-comparison section into a practical checklist covering scope, revisions, content, hosting, maintenance, ownership, and exclusions. Preserve sourced market figures with their dates and context. Do not invent prices or publish Straffe Sites rates. Link to the existing budget and online-store cost guides instead of duplicating them.

Astro and Prettier: setup checks and formatting fixes

Refresh the existing US English article:
https://straffesites.com/en/blog/integrate-prettier-astro-tailwindcss

Why this topic: Its main formatting queries already average positions around 6–7, closer to prominent results than the other two recommendations.

Query-level evidence for this page:
“astro prettier”
422 impressions · 1 click · 0.237% CTR · average position 6.88

“prettier astro”
376 impressions · 0 clicks · 0% CTR · average position 6.11

“prettier-plugin-astro”
218 impressions · 1 click · 0.459% CTR · average position 6.11

Whole-page context: 4,295 impressions and 14 clicks.

Writing angle: The article already explains installation, plugin order, and Tailwind stylesheet configuration. Add a short diagnostic path for formatting failures rather than another setup walkthrough: does formatting work from the command line, does the editor use the same configuration, and does class sorting work separately?

Ownership: Keep formatting on this dedicated guide. The broader Astro starter guide received only 6 impressions for “astro prettier,” compared with 422 here. The historical keyword registry flags overlap, but the current report does not show substantial competition for this query.

Writing prompt:
Refresh the existing Astro/Prettier guide in US English. Preserve the configuration and add troubleshooting that separates command-line formatting, editor integration, and Tailwind class sorting. Verify current official documentation and test examples before claiming they work. Keep general Astro/Svelte/Vercel setup in the existing starter guide and link to it.

Set up Google Search Console and fix verification problems

Refresh the existing US English article:
https://straffesites.com/en/blog/google-search-console

Why this topic: Google already shows the guide for clear setup intent, but those impressions produce few clicks.

Query-level evidence for this page:
“how to set up google search console”
1,649 impressions · 0 clicks · 0% CTR · average position 14.60

“google search console setup”
1,033 impressions · 1 click · 0.097% CTR · average position 14.28

Whole-page context: 8,677 impressions and 5 clicks.

Writing angle: Keep the existing three-step setup and practical reporting workflow. A useful next extension is concise verification troubleshooting: choosing the correct property, finding the authoritative DNS provider, placing the TXT record, and distinguishing verification delays from missing report data.

Ownership and timing: The English guide is the clear owner for these setup queries. Preserve its Dutch counterpart rather than merge languages. The September 9 refresh already improved the reporting instructions and citations; review its results no earlier than October 9 before expanding it again.

Writing prompt:
Review the September 9 update before refreshing this US English guide. Preserve the setup steps and page/query workflow. Add concise verification troubleshooting supported by current Google documentation. Separate setup time from DNS waiting time and sitemap discovery from indexing. Do not promise immediate data or ranking gains.

Evidence limits

These are observed search opportunities, not traffic forecasts. GSC omits anonymized queries, and average position is not a fixed ranking. Low CTR alone does not establish a title problem.

Country/page and device/page reports were also retrieved, but their totals did not reconcile with page-only data, including after a device-report recheck. I have not used them to claim audience shares. The proposed troubleshooting sections are editorial extensions of demonstrated broader intent, not independently proven high-volume keywords.

No articles, publication dates, or shared calendars were created or changed.

Search Console describes searches where your site appeared. It is not a market-wide keyword-volume tool, and sparse data should not become a confident demand forecast. Refreshing an existing article can be a better choice than adding a competing page.

Improve the draft in the same conversation

Back in the writing conversation, this follow-up revises the Astro-versus-WordPress draft using the developer-focused outline above:

Hermes Agent: revise the draft in the same conversation gpt-6-astra

You

/notfair-content-writer
Revise the draft above. Keep the code examples, cut generic advice,
and make the explanation easier to follow.

Agent

SEO metadata

Title: Astro vs WordPress: what developers maintain after launch

Meta description: Astro vs WordPress for developers maintaining small business sites. Compare updates, publishing, integrations, recovery, and the work each setup leaves you.

Proposed slug: /en/blog/astro-vs-wordpress
Primary keyword: Astro vs WordPress
Secondary topics: Astro maintenance, WordPress maintenance, static-site deployment, headless WordPress.

The earlier article contained no implementation code examples. I kept the technical explanations and updated its JSON-LD rather than introducing untested code.

Astro vs WordPress: what developers maintain after launch

A static Astro site can remove a WordPress application and database from the public request path. It cannot remove the developer responsible for publishing changes, fixing forms, and recovering from a bad release. For developers comparing Astro vs WordPress for small business websites, that ongoing work is a better starting point than a framework benchmark.

Choose static-first Astro when the site mostly publishes content and you can support its editing and deployment workflow. Keep WordPress on the shortlist when its editor or existing plugins already handle the business's requirements. A working WordPress site does not need a migration just because you would prefer to maintain Astro.

This comparison assumes conventional WordPress with sensible caching, not an intentionally slow installation. On the Astro side, it starts with prebuilt pages. On-demand rendering and headless WordPress add responsibilities of their own.

Contents

Astro vs WordPress: what becomes your responsibility?
Follow a content change through to production
Separate failed updates from broken production
Trace forms and bookings beyond the frontend
Headless WordPress leaves you with two systems
Make the decision against a real maintenance brief
Frequently asked questions

Astro vs WordPress: what becomes your responsibility?

A conventional WordPress installation runs application code and stores content in a database. That does not mean every visitor triggers a fresh database query. WordPress's caching documentation describes serving cached static files; uncached requests and dynamic features still need the application.

Astro prerenders routes by default. For those routes, the host serves the files produced by the build. You maintain the system that creates and delivers those files rather than a CMS application serving public pages.

Maintenance task	Static-first Astro	Conventional WordPress
Publish content	Edit files or use a connected CMS, then build and deploy	Publish through the editor; check cache behavior
Update software	Framework, packages, build environment, and integrations	Core, themes, plugins, and the hosting runtime
Recover content	Restore source content or CMS data; rebuild if needed	Restore revisions or appropriate database and file backups
Recover a release	Restore a known-good deployment or rebuild a reverted version	Restore compatible application code and account for database changes
Investigate missing inquiries	Trace the form endpoint, provider, and delivery	Trace the plugin or endpoint, provider, and delivery

For a fully static frontend, removing WordPress also removes its core, theme, and plugin update cycle. Repository access, deployment accounts, hosting, and external services remain. A compromised deployment account can replace a static site just as effectively as a compromised application can alter a dynamic one.

If you add Astro's on-demand rendering, you also need an adapter and runtime. Include those in the maintenance plan. The relevant distinction is which code runs where, not whether the project has an Astro logo.

Follow a content change through to production

Suppose the client asks you to update a service description and replace its photo. The task is finished when the public page shows the approved content, with the right image and working links.

WordPress: check the saved content, then the response

The block editor provides the editing interface. Preview the change, publish it, and check the page as a logged-out visitor. An administrator's view may bypass caching or show content that an ordinary visitor cannot see.

If the old description remains visible, first confirm the right page was updated and published. Then inspect the page cache and CDN behavior. If only the image is stale, check the image URL and its caching separately. Purging every cache before identifying the stale response can hide the cause.

Astro: check the source, build, deployment, and public page

With file-based content, the change passes through the repository and build before it reaches production. A CMS adds an editing interface, but a statically built frontend still needs a successful publication path.

Straffe Sites documents one file-based approach in its article about a website without a CMS: content lives as MDX and JSON in Git, with Astro Content Collections validating configured fields. That is an example of a technical team's workflow, not a requirement for every Astro project.

When an update is missing, check the stages in order:

Does the intended source contain the new content?
Did the build use that source revision or CMS version?
Did the build and deployment succeed?
Does the production domain serve that deployment?
Is a cached page or asset hiding the change?

A CMS saying "published" answers only the first part of this chain. Give editors a way to tell whether their change reached the website, and assign someone to investigate failures. Otherwise routine publishing problems become unexplained support tickets.

Separate failed updates from broken production

The following are hypothetical failure scenarios, not reports of tests performed for this article.

A WordPress plugin update breaks the form

After a plugin update, the contact page still loads, but submissions fail. Start by reproducing a submission with test data. Inspect the browser request and the relevant server or provider logs. Determine whether the failure occurs before the request, at the endpoint, or during onward delivery.

Before restoring an older plugin version, check whether the update changed stored data and whether the older code can read it. Restoring files alone may not reverse a database migration. Restoring an entire database backup may also discard newer inquiries, bookings, or orders.

This is why the recovery plan must identify both the code version and the state it expects. WordPress's security guidance covers updates and recovery preparation; the separate WordPress maintenance guide provides broader context. For this incident, the useful acceptance test is a submitted inquiry reaching its destination.

An Astro dependency update prevents the next deployment

An Astro update can fail during dependency installation, validation, or the build. Check the first relevant error and compare the changed dependency versions and runtime requirements. Use the project's lockfile and documented build environment rather than trying unrelated package upgrades.

A failed build is not necessarily an outage. A deployment system that retains the previous successful release until its replacement is ready can keep serving the old site. A script that deletes or overwrites live files before finishing the build cannot make the same promise. Verify the host's behavior instead of attributing that protection to Astro.

A successful build can still publish the wrong content or a broken form. Check the deployed page and critical interactions after release. Restoring a previous deployment reverses that deployment's files; it does not automatically reverse changes in an external CMS, form service, or database.

For either stack, document what "rollback" restores and what it leaves untouched. Recovery should not begin with someone discovering where the backups are.

Trace forms and bookings beyond the frontend

An HTML form on a static page still needs somewhere to send its data. A WordPress form plugin also depends on processing and delivery beyond the visible form. In both cases, trace the complete path:

Visitor submission → receiving endpoint → stored record or delivery queue → staff notification or CRM.

Check each boundary. Did the endpoint accept the submission? Was a record stored? Did the notification arrive? An accepted API request and a delivered email are different events. The confirmation message should accurately describe what the system knows.

Keep the failure check small and repeatable: submit identifiable test data without private customer details, verify the destination, and remove the test through the agreed operational process. Check invalid input and unavailable-provider behavior as well as the successful path. Never use real charges to test a checkout when the provider supplies a test mode.

Do not rebuild working business operations by accident

A booking link to an existing scheduling service is a small frontend feature. Replacing a WordPress plugin that manages availability, deposits, and cancellations is a different project. List those behaviors before estimating a migration.

WooCommerce is a commerce platform for WordPress. Astro can render a storefront connected to a commerce backend, but it does not supply order management by itself. The new setup still needs someone responsible for payment events, inventory changes, refunds, and failed notifications.

Retain an established integration when it works unless the replacement solves a specific problem. Moving complexity into custom code or another provider does not make it disappear from your maintenance workload.

Headless WordPress leaves you with two systems

With headless WordPress, editors retain WordPress while Astro renders the public site. Astro's WordPress integration guide describes fetching content through the WordPress REST API. The broader headless CMS explanation covers the separation between editing and presentation.

For a statically built frontend, you now own the connection between two publication states: content published in WordPress and content deployed by Astro. Define how publication triggers a build, how a failed build is reported, and how an editor previews a draft without exposing it publicly.

Audit the plugins before committing to this design. A plugin that modifies a WordPress template, inserts frontend scripts, or renders a form will not automatically reproduce that behavior in Astro because the content API is available. Rendering CMS HTML also requires a clear trust boundary; inserting a string as HTML is not a sanitization step.

Headless WordPress is justified when preserving the editorial workflow has value and a separate frontend meets a concrete requirement. If the conventional site already works, adding a second deployment system solely to change frameworks is hard to justify.

Make the decision against a real maintenance brief

Consider a hypothetical electrical contractor with eight service pages, a project gallery, a contact form, and an external scheduling service. The developer handles occasional content changes.

Static Astro fits that brief: prebuilt pages, a defined form endpoint, and a link to the existing scheduler. The maintenance agreement still needs a response time for urgent content corrections and a backup maintainer who can publish them.

If an office manager must publish projects independently every week, include an editor in the Astro proposal and compare the resulting setup with WordPress. If bookings and payments already depend on a working WordPress plugin, keeping WordPress may avoid a substantial integration rewrite.

Test the actual site before using speed to justify a move

Astro's islands architecture lets you add interactive components without hydrating the entire page. That is useful control over browser work, but a booking embed, large image, or added script can still dominate performance.

Compare representative pages with the same required content and integrations. Record lab conditions, check mobile behavior, and use available real-user data as a separate source. Do not compare an empty Astro demo with a full production WordPress page.

Google states that good Core Web Vitals do not guarantee top rankings. A platform change needs its own operational justification. If you migrate, preserve useful URLs and verify redirects, metadata, internal links, and indexability rather than treating the rebuild as an automatic SEO improvement.

Before recommending a stack, put these answers in the handover document:

Who publishes routine changes, and who handles urgent ones?
Which endpoint receives inquiries, and how is delivery checked?
What does the update process test before and after release?
What survives a failed build, and what does rollback restore?
Can another developer publish and recover the site using the documentation?
Can the current site's problems be fixed without migration?

Choose Astro when its publishing and delivery model removes work you would otherwise maintain. Choose WordPress when its editor and integrations already do that work well. Keep the existing site if a rebuild cannot explain what becomes simpler afterward.

Frequently asked questions

Does a static Astro site still need dependency updates?

Yes. Static delivery removes the application runtime from prebuilt page requests, but the framework, packages, build environment, and integrations still need maintenance. Prioritize updates according to the affected component and its exposure.

Can a failed Astro build take the live website down?

That depends on deployment behavior, not Astro alone. A system that keeps serving the previous successful release while a replacement builds can preserve availability. A deployment script that removes live files first may not. Verify your setup.

Does managed WordPress hosting remove the developer's maintenance work?

No. The host may handle infrastructure, backups, or some updates. The developer still needs to know what the agreement covers and who tests custom code, plugins, forms, and business workflows after changes.

When is headless WordPress worth maintaining?

When retaining WordPress's editorial workflow and using a separate frontend solve concrete requirements. Account for both systems, including previews, API access, publication triggers, failed builds, and plugin behavior that must be recreated in the frontend.

Accompanying publication notes

Structured data

This replaces the previous draft's headline, description, and FAQ content. JSON parsing and exact FAQ-text matching were checked.

Publication-specific fields remain deliberately absent: author, dates, canonical URL, and image must reflect the actual approved publication. Image concepts are not published assets. FAQPage describes the visible questions; it does not promise Google FAQ rich results, which Google's previously verified documentation says are no longer shown.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "BlogPosting",
      "headline": "Astro vs WordPress: what developers maintain after launch",
      "description": "Astro vs WordPress for developers maintaining small business sites. Compare updates, publishing, integrations, recovery, and the work each setup leaves you.",
      "inLanguage": "en-US",
      "about": [
        { "@type": "Thing", "name": "Astro" },
        { "@type": "Thing", "name": "WordPress" }
      ]
    },
    {
      "@type": "FAQPage",
      "inLanguage": "en-US",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "Does a static Astro site still need dependency updates?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Yes. Static delivery removes the application runtime from prebuilt page requests, but the framework, packages, build environment, and integrations still need maintenance. Prioritize updates according to the affected component and its exposure."
          }
        },
        {
          "@type": "Question",
          "name": "Can a failed Astro build take the live website down?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "That depends on deployment behavior, not Astro alone. A system that keeps serving the previous successful release while a replacement builds can preserve availability. A deployment script that removes live files first may not. Verify your setup."
          }
        },
        {
          "@type": "Question",
          "name": "Does managed WordPress hosting remove the developer's maintenance work?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "No. The host may handle infrastructure, backups, or some updates. The developer still needs to know what the agreement covers and who tests custom code, plugins, forms, and business workflows after changes."
          }
        },
        {
          "@type": "Question",
          "name": "When is headless WordPress worth maintaining?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "When retaining WordPress's editorial workflow and using a separate frontend solve concrete requirements. Account for both systems, including previews, API access, publication triggers, failed builds, and plugin behavior that must be recreated in the frontend."
          }
        }
      ]
    }
  ]
}

Image concepts

Concepts only; no images generated or inserted.

Featured illustration, after the opening paragraph
Filename: astro-wordpress-maintenance.webp
Alt: “Static publishing and WordPress application maintenance shown as separate workflows with shared integrations.”
Concept prompt: Wide 16:9 editorial 3D diagram with two equally weighted workflows, connected to shared form and hosting services. Warm beige #E9E6DF, charcoal modules, paper panels, lime connectors. Avoid winner symbols, invented metrics, logos, and fake dashboard screenshots.
Publishing-flow diagram, under “Follow a content change through to production”
Filename: website-content-publication-paths.webp
Alt: “WordPress publication and Astro build-and-deploy paths, each ending with a public-page check.”
Concept prompt: Two horizontal process lanes. WordPress: edit, publish, cache, public page. Astro: source change, build, deployment, public page. Mark each diagnostic checkpoint. Use beige, charcoal, and lime; add labels during design production. Avoid timing claims and implied test results.
Recovery comparison, under “Separate failed updates from broken production”
Filename: website-release-recovery-boundaries.webp
Alt: “Code, deployed files, and external data shown as separate recovery boundaries.”
Concept prompt: A clear 4:3 technical diagram separating application files, static deployment artifacts, and persistent data. Show rollback arrows limited to their actual boundary. Neutral beige background, charcoal outlines, lime highlights. Avoid suggesting that restoring code also restores external data.
Inquiry-delivery diagram, under “Trace forms and bookings beyond the frontend”
Filename: website-form-delivery-checkpoints.webp
Alt: “A form submission passing through an endpoint, storage or queue, and notification destination.”
Concept prompt: Wide process diagram showing submission, endpoint acceptance, storage or queue, and notification or CRM as distinct checkpoints. Use simple labeled boxes, beige, charcoal, and lime. Avoid customer information, provider branding, and success badges presented as measured evidence.

Internal linking

The revision retains contextual links to the existing no-CMS, WordPress maintenance, and headless CMS articles. Those pages remain the detailed references; this article owns the developer-maintenance comparison.

Suggested incoming links remain editorial recommendations only:
- From the no-CMS article: “maintaining Astro versus WordPress.”
- From the WordPress maintenance article: “whether a platform migration reduces maintenance.”
- From the Astro-versus-Next.js article: “Astro versus WordPress after launch.”

Before publication

Confirm author, dates, route, and canonical destination.
Produce the approved imagery and populate image metadata with real asset URLs.
Integrate the revised schema without duplicating existing template output.
Check rendered headings, links, table behavior, and mobile layout.
Keep the failure scenarios labeled hypothetical; no execution evidence has been added.

Change notes

Shifted the explanation from owner-facing platform selection to developer responsibilities.
Replaced broad advice with publishing checkpoints and specific failure scenarios.
Clarified cache behavior, failed builds versus outages, and code rollback versus data recovery.
Kept the small-business example, but tied each requirement change to maintenance work.
Reused the already verified sources without rerunning the earlier broad research.
Updated the metadata and FAQ schema. No website or external content was changed.

You don't need to repeat the URL, audience, and full brief when they are already in the conversation. Point to the part you want changed and say what would make it more useful.

Check the draft before you publish

Read the article, check its sources, and run the code examples where safe. This next message continues the same writing conversation and asks Hermes to review the revised draft, fix what it can, and report what it could not verify:

Hermes Agent: check facts, links, and code before publishing gpt-6-astra

You

Check this draft's facts, links, and code examples. Fix the issues
and tell me what you couldn't verify. Don't publish it.

Agent

The draft is broadly accurate. I corrected seven passages, checked the links against their actual destinations, and validated the JSON-LD. Nothing was published or changed on the website.

Checked on September 13, 2026.

Review results

All 11 original article links returned HTTP 200 and led to relevant pages.
Both sources added during the corrections also returned HTTP 200. The corrected article has 13 working links.
The seven table-of-contents entries match the headings using conventional Markdown slug rules. Final rendered anchors remain untested.
The JSON-LD parses successfully, has no duplicate keys, and matches all four visible FAQ questions and answers.
The article has no executable Astro, JavaScript, PHP, or shell examples. Its only accompanying code block is JSON-LD, which is data—not an implementation to run.

Corrections

Narrow the WordPress caching claim

“Uncached requests … still need the application” was too broad. An uncached image or stylesheet can be served without running WordPress.

Corrected passage:

A conventional WordPress installation runs application code and stores content in a database. That does not mean every visitor triggers a fresh database query. WordPress's caching documentation describes serving cached static files; requests that generate a page or process a submission through WordPress still need the application. Static assets such as images and stylesheets can be served directly by the host or CDN.

Source:
https://developer.wordpress.org/advanced-administration/performance/cache/

Distinguish removing WordPress from replacing its frontend

The original wording could suggest that a static frontend eliminates WordPress maintenance even when WordPress remains the CMS. It also made an unnecessary comparison between different kinds of compromise.

Corrected passage:

Retiring the WordPress installation removes its core, theme, and plugin update cycle. Replacing only the frontend does not: headless WordPress still needs maintenance. Repository access, deployment accounts, hosting, and external services also remain. Someone with permission to publish a deployment can change the public site, even when its pages are static.

Sources:
https://docs.astro.build/en/guides/cms/wordpress/
https://developer.wordpress.org/advanced-administration/security/hardening/

Make Git a workflow choice, not an Astro requirement

File-based content does not inherently require a repository.

Corrected passage:

In a Git-based workflow, a file change passes through the repository and build before it reaches production. Git is a workflow choice, not an Astro requirement. A CMS adds an editing interface, but a statically built frontend still needs a successful publication path.

The Straffe Sites example remains appropriate: its public no-CMS article describes MDX and JSON content in Git. That verifies the attributed example, not a requirement for every Astro site.

https://straffesites.com/en/blog/website-without-cms

Strengthen the plugin rollback instructions

The draft correctly separated plugin files from database state. It needed two precautions: preserve the current state before recovery, and check whether downgrading would restore a known vulnerability.

Corrected passage:

Before restoring an older plugin version, preserve the current files and database. Check whether the update changed stored data, whether the older code can read it, and whether rolling back would reintroduce a known vulnerability. Test recovery on an isolated staging copy where possible. Restoring plugin files does not undo database changes. Restoring an older database can discard inquiries, bookings, or orders recorded after that backup.

This is recovery guidance, not a claim that a particular plugin update or database migration was tested.

Cite backup documentation directly

The general hardening guide was relevant, but the backup documentation supports the files-versus-database explanation more directly.

Corrected passage:

WordPress's backup documentation explains why a typical full-site restore needs both files and the database. Its security guidance covers keeping software current. The separate WordPress maintenance guide provides broader context.

New direct source:
https://developer.wordpress.org/advanced-administration/security/backup/

Clarify deployment rollback versus rebuilding an old commit

“Reverses that deployment’s files” was ambiguous. Serving an earlier build and rebuilding earlier source are different recovery operations.

Corrected passage:

Restoring a known-good static deployment puts its built files back into service. It does not automatically restore external CMS content, form-service data, database state, or separately managed hosting settings. Rebuilding an old commit is a different operation: external content, dependency resolution, or build settings may have changed since the original release.

The existing warning about failed builds stays: retaining the previous live release is deployment-system behavior, not an Astro guarantee. I did not test a hosting provider’s rollback behavior.

Make the HTML-rendering warning specific

The draft’s sanitization warning was correct but abstract. Astro documents the relevant behavior explicitly.

Corrected passage:

Rendering CMS HTML also requires a clear trust boundary. Astro's set:html directive inserts HTML without automatically escaping it. Use it only for trusted HTML or content sanitized with an appropriate allowlist. Render untrusted plain text through Astro's normal escaped expressions instead.

Source, including its checked fragment:
https://docs.astro.build/en/reference/directives-reference/#sethtml

No sanitizer implementation is included or claimed to have been tested.

Facts that can stay

The official sources support these central claims:

Astro prerenders routes by default. On-demand rendering requires an adapter and a suitable runtime.
https://docs.astro.build/en/guides/on-demand-rendering/
Astro islands allow selected components to become interactive without hydrating the whole page. That does not guarantee a fast site once images, embeds, and scripts are included.
https://docs.astro.build/en/concepts/islands/
Astro can fetch WordPress content through the REST API. Making content available through an API does not automatically reproduce a plugin’s frontend behavior.
https://docs.astro.build/en/guides/cms/wordpress/
WordPress provides a block editor, and WooCommerce provides commerce functionality for WordPress. Astro itself is not an order-management backend.
https://wordpress.org/documentation/article/wordpress-block-editor/
https://woocommerce.com/
Good Core Web Vitals do not guarantee top Google rankings. The draft correctly avoids presenting a framework migration as an automatic SEO improvement.
https://developers.google.com/search/docs/appearance/page-experience

The remaining internal article links also worked. I checked their relevance to the passages that cite them; I did not audit every claim on those linked pages.

JSON-LD and publication notes

No JSON syntax correction was needed. The existing BlogPosting and FAQPage graph can remain as draft data.

The distinction that matters:

This JSON-LD has passed syntax and FAQ-content checks. It has not been validated inside a rendered page or submitted to Google’s Rich Results Test or Schema.org’s validator. Add the approved author, publication dates, canonical details, and real image assets before publication; do not invent values to complete the draft.

The FAQ rich-result statement is also supported by current Google documentation. It should now include the direct citation rather than refer vaguely to “previously verified documentation.”

Corrected note:

FAQPage remains a Schema.org type, but Google states that FAQ rich results are no longer shown in Search. Keeping this graph is optional for describing the visible FAQ; it is not a recommendation for gaining a Google rich result.

Sources:
https://schema.org/FAQPage
https://developers.google.com/search/updates#removing-faq-rich-result

The Google changelog fragment exists and was checked.

What I could not verify

Actual failure recovery. I did not update plugins, install dependencies, restore databases, run builds, or deploy anything.
Forms, bookings, payments, or email delivery. I submitted no test records and made no payment requests.
Provider-specific guarantees. No particular hosting contract, backup retention policy, atomic deployment behavior, or rollback process was tested.
Performance differences. No Astro-versus-WordPress benchmark was run. The draft makes no measured performance comparison.
Final presentation. The unpublished draft has not been rendered, so mobile layout, table overflow, accessibility, actual heading IDs, and embedded JSON-LD remain unchecked.
Image assets. They remain concepts. There are no generated images or asset URLs to validate.
Publication metadata. Author attribution, publication dates, canonical destination, and image metadata still require approval.

The hypothetical scenarios remain labeled as hypothetical. The corrected draft preserves the original argument without presenting documentation checks as hands-on testing.

If Hermes can access your website repository, start it from that directory and ask it to save the approved draft using the project's existing format. A website URL alone does not give it filesystem or CMS access. My site uses MDX and JSON in Git with Astro; other sites can use their CMS's draft mode.

Keep the publication decision yourself. Record the live URL, publication date, and any pre-change measurements. After at least 30 days, ask Hermes to compare the article's Search Console performance over comparable periods. For a new URL, track its first results rather than inventing a prepublication baseline. That's the monthly review pattern behind my SEO automation workflow, not a promise that every article will improve rankings.

Troubleshooting before you blame the model

The slash command is missing: check that the adapted skill is installed. Restart the session and check the exact command name.
The skill still requests a hosted connector: ask Hermes to check the adaptation and its shared references. It should use the gcloud connection you approved.
Google refuses access: ask Hermes to verify the actual identity and property permissions. Don't paste credentials into chat or grant broader rights blindly.
The article feels generic: give it a specific question, your own example, or a technical opinion you can defend. Another writing pass cannot create missing experience.

Start with one useful task. The skills contain the detailed procedures; your chat messages can stay short.

For more on choosing a topic, drafting, and reviewing your work, see my AI writing workflow on Straffe Sites. The installation commands follow the linked official documentation. The installation and setup prompts are examples for your own environment, not transcripts of freshly completed installations or guaranteed results. The Agent Session blocks from “Turn the setup into an article” onward are recorded Hermes exchanges.

Set up Astro with Svelte, Tailwind CSS, Vercel, Prettier, and TypeScript

Seppe Gadeyne — Thu, 10 Sep 2026 09:32:10 +0000

I use Astro with Svelte for interactive components, Tailwind CSS for styling, and Prettier to keep formatting consistent. This guide walks through the project setup, strict TypeScript checks, and a static deployment to Vercel.

Getting started

Before you begin, make sure you have the following on your machine:

Node.js 22.12.0 or higher (odd-numbered releases are not supported)
Visual Studio Code with these extensions: astro-vscode, prettier-vscode, svelte-vscode, and tailwindcss-intellisense

That's it. Astro needs no global CLI and no Docker container to get going.

Initial Astro project setup

Create a new Astro project with:

npm create astro@latest

Astro asks where to create the project and which starter to use. Choose a minimal template unless you already need a themed starter, and keep the strict TypeScript configuration shown below. That gives you a clean setup without demo files to remove later.

Adding Svelte, Tailwind CSS, Prettier, and type checks

From inside the newly created project folder, add the integrations:

npx astro add svelte
npx astro add tailwind
npm install --save-dev @astrojs/check typescript prettier prettier-plugin-astro prettier-plugin-svelte prettier-plugin-tailwindcss

Tailwind's integration has changed. The npx astro add tailwind command now installs the Tailwind Vite plugin (@tailwindcss/vite), which is the recommended path for Tailwind 4. The integration commands update astro.config.mjs where needed, so you rarely have to configure them by hand. Accept the defaults when prompted.

Create src/styles/global.css with @import "tailwindcss"; if the command has not already created it. Import that stylesheet in your shared Astro layout frontmatter with import '../styles/global.css' (adjust the relative path). The Vite plugin alone does not apply styles to a page.

Why this stack? Astro renders pages to static HTML by default and only ships JavaScript where an island needs it. That helps keep a static website fast. I use Svelte 5 for interactive parts because it has a small runtime, runes-based reactivity, and a comfortable component model. Tailwind CSS provides utility classes and can encode the tokens from a design system, keeping the styling predictable.

Configuring Prettier

Create a .prettierrc file in the root of your project:

{
  "useTabs": true,
  "singleQuote": true,
  "trailingComma": "none",
  "semi": false,
  "printWidth": 100,
  "tailwindStylesheet": "./src/styles/global.css",
  "plugins": ["prettier-plugin-astro", "prettier-plugin-svelte", "prettier-plugin-tailwindcss"]
}

Create a .prettierignore too:

node_modules/**
vercel.json

Two details matter in 2026. First, pluginSearchDirs is gone. Prettier 3 no longer discovers plugins implicitly, so you must list them in plugins. Second, prettier-plugin-tailwindcss sorts classes for both Tailwind 3 and 4 configurations. With Tailwind 4, tailwindStylesheet is required: point it at your actual CSS entry file, here src/styles/global.css.

Configuring Astro

A typical astro.config.mjs for this stack:

import { defineConfig } from 'astro/config';
import svelte from '@astrojs/svelte';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  site: 'https://yourdomain.com',
  integrations: [svelte()],
  vite: {
    plugins: [tailwindcss()],
  },
  trailingSlash: 'never',
  output: 'static',
});

Astro's default output is static, and a fully static site can deploy to Vercel without an adapter. The platform serves the exported HTML and assets from its CDN without per-request rendering. Run npx astro add vercel only when you need on-demand routes or Vercel-specific services such as image optimization; current versions import the adapter from @astrojs/vercel.

The astro check command type-checks .astro files. It requires @astrojs/check and TypeScript, which the install command above adds. Run it in CI to catch type errors before they are merged or deployed:

{
  "scripts": {
    "dev": "astro dev",
    "check": "astro check",
    "build": "astro check && astro build"
  }
}

Configuring TypeScript

Edit tsconfig.json:

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

The paths setting gives you path aliases: import components as @/components/Button.astro instead of ../../components/Button.astro. My site uses the same trick with @blocks/* for its block registry.

The old advice to declare a *.astro module shim in src/env.d.ts is obsolete. Since version 3, Astro has generated typed references for .astro imports automatically. If you still have such a declaration lying around, you can delete it.

Configuring Vercel

A static deployment needs little configuration after you connect the repository in Vercel. Here is a minimal vercel.json for the project root:

{
  "regions": ["fra1"],
  "cleanUrls": true,
  "trailingSlash": false,
  "redirects": [
    { "source": "/old-slug", "destination": "/new-slug", "permanent": true }
  ]
}

trailingSlash: false makes Vercel redirect /old-slug/ to /old-slug with a 308, which keeps your URLs canonical. When you migrate slugs, account for both trailing-slash variants so every old incoming link reaches the intended page.

Running the project

Start the development server with:

npm run dev

If the project behaves oddly after an Astro upgrade, reinstall the dependencies before rewriting your configuration. Stale dependency state is often the culprit.

Originally published on Straffe Sites.

Integrate Prettier with Astro and Tailwind CSS

Seppe Gadeyne — Mon, 07 Sep 2026 08:53:55 +0000

Prettier handles indentation, quotes, and line breaks. With the right plugins, it also formats .astro files and sorts Tailwind utility classes. This guide sets up both for an Astro project using Prettier 3 and Tailwind CSS 4.

There are two details to get right: Prettier 3 requires explicit plugin loading, and the Tailwind plugin needs the CSS entry point for your Tailwind 4 configuration.

Getting started

Use a current Node.js LTS release supported by your Astro version, with npm installed. If you use VS Code, install these extensions:

Astro (astro-build.astro-vscode)
Prettier (esbenp.prettier-vscode)
Optional: Tailwind CSS IntelliSense for class suggestions; it is not required for formatting.

If you do not have an Astro project yet, create one:

npm create astro@latest

Choose a starter template and install its dependencies when prompted. Run the remaining commands from the project folder created by the wizard. This guide assumes Astro 5.2 or newer, where astro add tailwind installs the Tailwind 4 Vite plugin.

Adding Tailwind CSS and Prettier

If Tailwind 4 is not already configured, run:

npx astro add tailwind

Review and accept the proposed changes. The command adds @tailwindcss/vite to astro.config.mjs and creates src/styles/global.css with the Tailwind import:

@import 'tailwindcss';

Import that stylesheet in the front matter of a shared layout, such as src/layouts/Layout.astro, or in each page that needs it:

---
import '../styles/global.css'
---

Merge the import into your existing front matter; keep the rest of the layout. The CSS must be imported by a layout or page you actually render. See Astro's Tailwind setup instructions if your project uses a different structure. Existing Tailwind 3 projects should follow the migration instructions there first.

Then install Prettier and both formatting plugins:

npm install --save-dev --save-exact prettier@3 prettier-plugin-astro prettier-plugin-tailwindcss

--save-exact saves exact versions in package.json. Commit package-lock.json as well so teammates and CI can install the same dependency tree with npm ci.

Configuring Prettier

Create .prettierrc in the project root, or merge these settings into your existing Prettier configuration:

{
  "useTabs": true,
  "singleQuote": true,
  "trailingComma": "none",
  "semi": false,
  "printWidth": 100,
  "plugins": ["prettier-plugin-astro", "prettier-plugin-tailwindcss"],
  "tailwindStylesheet": "./src/styles/global.css",
  "overrides": [
    {
      "files": "*.astro",
      "options": {
        "parser": "astro"
      }
    }
  ]
}

The first five options are formatting preferences, not Astro requirements. Adjust them to your team's conventions.

The plugins array explicitly loads the plugins. Prettier 3 removed automatic plugin discovery; installing a package alone does not load it in the CLI. The Astro parser override follows the Astro plugin's recommended configuration.

For Tailwind 4, tailwindStylesheet is required by the Tailwind plugin's setup instructions. Point it to your actual CSS entry point containing the Tailwind import and your theme or custom utility definitions. The path is relative to .prettierrc, not the file being formatted.

Keep prettier-plugin-tailwindcss last in the plugin array. If your project also uses Svelte, install its formatter:

npm install --save-dev --save-exact prettier-plugin-svelte

Then replace the plugins array with this one, keeping the other settings:

["prettier-plugin-astro", "prettier-plugin-svelte", "prettier-plugin-tailwindcss"]

Add .prettierignore for generated output:

dist/
.astro/
.vercel/

Prettier already ignores node_modules by default. There is no general reason to exclude vercel.json; it is a source configuration file that Prettier can format.

Formatting on save in VS Code

Merge these settings into .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "prettier.documentSelectors": ["**/*.astro"],
  "[astro]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

The Astro extension has its own formatter; these settings explicitly select the Prettier extension for .astro files. The Prettier extension uses your project's locally installed Prettier. Open a trusted workspace and approve local module loading if prompted.

For Svelte projects, also add "**/*.svelte" to prettier.documentSelectors and a [svelte] setting with the same editor.defaultFormatter value.

Checking the setup locally and in CI

Format the project, then check it without making changes:

npx prettier . --write
npx prettier . --check

Review the formatting diff before committing. --check exits with a nonzero status if files need formatting, so it can fail a CI job. In CI, install the committed dependencies with npm ci before running npx prettier . --check.

If formatting fails, check that the stylesheet path exists, the Astro parser override is present, and the Tailwind plugin is last. If the CLI works but saving in VS Code does not, check the selected formatter and the Prettier output panel.

Conclusion

The project now has an explicit plugin configuration, a Tailwind 4 stylesheet reference, and a formatting check you can use outside the editor. Keep the configuration and lockfile in Git so format-on-save and CI use the same rules.

The full Astro setup guide covers the wider starter configuration, including Svelte, Vercel, and TypeScript.

Originally published on straffesites.com.

A guide to proper semantic markup for blog posts

Seppe Gadeyne — Thu, 03 Sep 2026 11:06:26 +0000

Semantic markup means choosing HTML elements for their meaning: one <h1> for your title, <h2> and <h3> for logical sections, <figure> with <figcaption> for images, <time> for your publication date, and JSON-LD BlogPosting data for search engines. This guide explains why that matters for SEO and gives you examples of each element that you can copy, paste, and validate.

Introduction to semantic markup

Semantic markup uses HTML elements to make the structure and meaning of a page clear to browsers, search engines, and assistive technology. Give the blog post one <h1> for its title. Below it, use a logical hierarchy without skipping levels: <h2> for main sections and <h3> for subsections. This makes the article easier to scan and understand.

You can also add an id attribute to each <h2> and <h3>, usually based on a short hyphenated version of the heading. A table of contents can then link directly to it with a fragment such as #name-of-the-id.

The basic structure of a blog post

Here is an example of the basic structure of a blog post with semantic markup:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My website</title>
  </head>
  <body>
    <header>
      <figure>
        <img src="logo.svg" alt="Company name" />
      </figure>
      <nav aria-label="Main navigation">
        <!-- aria-label instead of a heading: navigation doesn't belong in the content outline -->
        <menu>
          <li><a href="/">Home</a></li>
          <li><a href="/contact">Contact</a></li>
        </menu>
      </nav>
    </header>
    <main>
      <article>
        <h1>Main title</h1>
        <h2>Title 1</h2>
        <p>Paragraph 1</p>
        <h2>Title 2</h2>
        <p>Paragraph 2</p>
        <h2>Title 3</h2>
        <p>Paragraph 3</p>
      </article>
    </main>
    <footer>
      <nav aria-label="Footer navigation">
        <menu>
          <li><a href="/">Home</a></li>
          <li><a href="/contact">Contact</a></li>
        </menu>
      </nav>
      <p>&copy; 2023 Company name</p>
    </footer>
  </body>
</html>

Notice that the navigation does not need an <h2>. Headings describe content sections; an aria-label names the <nav> landmark instead. The heading hierarchy stays clean, while screen reader users can still distinguish one navigation area from another.

Images and their alt text

Images need the same care as the surrounding text. Use descriptive filenames and write alt text that explains the content or purpose of each informative image. Alt text is primarily an accessibility feature, though it can also give search engines useful context.

A <figcaption> provides a visible caption that connects the image to your article. The alt text describes the image for someone who cannot see it; the caption is visible to everyone. The two may overlap, but they do not need to repeat each other word for word.

<figure>
  <img
    src="example-image.jpg"
    alt="An example of a well-formatted image"
  />
  <figcaption>An example of a well-formatted image</figcaption>
</figure>

Using `<time>` and `<address>`

Use <time> for a machine-readable publication or modification date. The <address> element is suitable for the article author's contact information, not for every postal address that happens to appear in the copy. Link to a useful author page if you have one.

Here is a simple example using <time> and <address>:

<time datetime="2023-03-21">March 21, 2023</time>
<address>
  Written by <a href="author-page.html">The Author</a>
  Follow me on <a href="https://twitter.com/theauthor">Twitter</a>
</address>

Schema markup for blog posts

Schema markup gives search engines an explicit description of the page. A blog post can use Article or its more specific BlogPosting type. If the page contains a genuine FAQ, FAQPage can describe those questions and answers too.

Here is a BlogPosting example:

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "A guide to the right semantic markup for blog posts",
  "url": "https://example.com/blog/semantic-markup-blog-posts",
  "image": [
    "https://example.com/image/1x1/image.jpg",
    "https://example.com/image/4x3/image.jpg",
    "https://example.com/image/16x9/image.jpg"
  ],
  "datePublished": "2023-03-20T12:42:21.345Z",
  "dateModified": "2023-03-21T12:12:44.220Z",
  "author": {
    "@type": "Person",
    "name": "The Author",
    "url": "https://example.com/the-author",
    "sameAs": [
      "https://twitter.com/the-author",
      "https://www.linkedin.com/in/the-author/"
    ]
  },
  "publisher": {
    "@type": "Organization",
    "name": "Company name",
    "url": "https://example.com",
    "sameAs": ["https://www.linkedin.com/company/company-name/"],
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.svg"
    }
  }
}

And here is an FAQPage example using Question and Answer:

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Why is semantic markup important for SEO?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Semantic markup helps search engines understand the structure and meaning of a page and gives assistive technologies useful relationships. It can support indexing, but it does not guarantee rankings or traffic."
      }
    },
    {
      "@type": "Question",
      "name": "Should I always use alt text for images?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Use descriptive alt text for informative images. Give purely decorative images an empty alt attribute so screen readers can skip them. Alt text primarily supports accessibility and can also provide search engines with useful context."
      }
    }
  ]
}

Always validate pasted markup. Google's Rich Results Test shows whether Google recognizes supported structured data, while the Schema.org validator checks the underlying vocabulary. URL inspection in Google Search Console shows how Google sees the published page. As a quick local check, the JSON must be accepted by JSON.parse without HTML-entity corruption.

Conclusion

Correct semantic markup gives readers, assistive technology, and search engines a clearer article. Use headings in order, describe informative images with useful alt text, and add valid schema markup where it accurately reflects the page. For the editorial side, I also wrote a guide on formatting and structuring a blog post. MDN has a useful reference on semantics in HTML as well.

This post was originally published on straffesites.com — I build fast, semantic websites there.

Supercharge your Shopify pages with Liquid shortcodes for collections

Seppe Gadeyne — Fri, 02 Jun 2023 11:33:14 +0000

I will share a handy trick I recently applied to a client's website selling orthopedic insoles. We needed a way to showcase collections in a page's text. Unlike WordPress, this isn't a feature directly offered by Shopify. We can achieve this with some Liquid, Shopify's template language. Look at the link above for an example of this implementation.

Making your Shopify theme shortcode-ready

The first step in our journey involves tweaking your theme's main-page.liquid file, located under the /sections directory. We'll make a small but impactful change here: replace {{ page.content }} with {% render 'shortcode', page: page.content %}. This modification tells Shopify to load the snippet named shortcode.liquid and pass it the variable named page containing page.content.

Creating the liquid shortcodes

Once we've prepped our theme, it's time to create two new files within the /snippets folder: shortcode.liquid and shortcode-collection.liquid.

In shortcode.liquid, we'll be inserting the following code:

{% liquid
   if page != empty
       assign content = page | split: '[collection='

       if content.size > 1
           assign content_parts = content[1] | split: ']'
           assign shortcode_handle = content_parts[0]

           echo content[0]

           if collections[shortcode_handle].id != empty
               render 'shortcode-collection', handle: shortcode_handle
           else
               echo '<p>No collection found with the handle "' | append: shortcode_handle | append: '".</p>'
           endif

           echo content_parts[1]
       else
           echo page
       endif
   endif
%}

This code checks if a shortcode in the format [collection=name-collection] is present within the text. If detected, the content will be split into two parts, and shortcode-collection.liquid will be loaded. If no shortcode is found, page.content is loaded as is.

Now, we'll add the following code to shortcode-collection.liquid:

{% assign collection = collections[handle] %}

{% if collection.id != empty %}
   <article>
       <h2>{{ collection.title }}</h2>
       {% for product in collection.products %}
           <article>
               <a href='{{ product.url }}'>
                   <img
                       src='{{ product.featured_image | image_url: width: '600', height: '600' }}'
                       alt='{{ product.title }}'
                       width='600'
                       height='600'
                       loading='lazy'
                   >
               </a>

               <a href='{{ product.url }}'>
                   <h3>
                       {{ product.title }}
                   </h3>
               </a>

               <p>
                   {{ product.price | money }}
               </p>
           </article>
       {% endfor %}
   </article>
{% else %}
   <p>No collection found with the handle "{{ shortcode_handle }}".</p>
{% endif %}

This code is responsible for rendering the products of a given collection. Remember, you'll likely need to style the output with CSS to match your website's looks. I intentionally used the <article> element, along with heading elements <h2> and <h3>, to leverage semantic markup, which can help your site rank higher on Google. For more information on semantic markup and improving your Google ranking, check out my other articles at Straffe Sites.

Conclusion

With some creativity and Liquid code, we've created a system that allows for the flexible insertion of Shopify collections into any part of your webpage.

This technique can be a real game-changer for those who want to provide a more dynamic and customized shopping experience. It's another example of the flexibility and power that Shopify's Liquid language offers.

But remember, with great power comes great responsibility. Always double-check your code and test your pages thoroughly to ensure everything works as expected. And remember to style your output with CSS to maintain a consistent and appealing visual aesthetic across your site.

I hope this tutorial has been helpful and has given you ideas for your Shopify projects. Remember, the possibilities are nearly endless when customizing your e-commerce store.