TL;DR

hugo-mcp v2.0.0 introduces a Python plugin-system that lets anyone add hooks after each create_page / update_page / delete_page operation. 200 lines of code for the core, 3 production plugins shipped (IndexNow, Google Indexing, Cloudflare). This post explains the design, the trade-offs, the security posture, and shows how to write your own plugin in 5 minutes.

Status: thinking, decision pending

This page documents a Hugo content architecture question I have not yet decided.

Context

The LoveIt theme used by arleo.eu follows the recommended Hugo convention: blog articles go in content/posts/. The home filters where Site.RegularPages Type posts.

But due to Grav migration history, my 16 editorial articles are at the root of content/, not in content/posts/. Hugo by default treats all these folders as Type page, not Type posts. So the LoveIt home filter does not see them, and I have to either override layouts/index.html or filter manually.

The question

Should I migrate the 16 articles to content/posts/ to follow LoveIt convention, or leave them at the root?

Option A: Migrate to content/posts/

Pros:

• Theme conformity, no layout override needed
• Repo readability, instantly see which folders are articles vs reference pages
• Future-proof, if LoveIt evolves with new features on Type posts they apply for free
• Standard mental model for any Hugo dev discovering the repo

Cons:

• URL change. /csp-nonce/ would become /posts/csp-nonce/ by default. Breaks all inbound links.
• Possible mitigation via explicit url in front matter to preserve URLs
• Migration friction, 16 folders to move, 16 files to edit
• Internal links: many articles cite each other, must audit

Option B: Keep the root

Pros:

• Identical URLs without doing anything
• No migration, 0 files touched
• Internal links intact by definition
• layouts/home.html override already in place, 1 line diff

Cons:

• Custom override to maintain if LoveIt evolves
• Repo readability: reference pages and articles mixed at root
• Weird convention, a Hugo dev wonders why no posts folder

SEO considerations

SEO fears URL change. With url override on Option A, no URL change. But then what is the migration’s purpose? Just internal repo readability. Cost vs benefit, probably not worth it.

Hugo MCP considerations

The MCP tools accept a route parameter. With url override, MCP workflow is unchanged for the user.

The provisional decision

The problem

You have a Hugo site. You want to:

1. Edit content via Claude.ai (publish an article, fix a typo, update a draft) without touching an SSH terminal.
2. Version the structure (layouts, themes, hugo.toml, deploy scripts) in Git, like a serious dev.

First instinct: “everything in Git”. Articles too. The MCP commits, pushes, GitHub webhook triggers a rebuild. Clean, GitOps-philosophy.

Except it doesn’t work that well. Here’s why, and the simple solution I call Strategy 4.

Why “everything in Git” breaks in practice

Imagine your MCP git commits on every create_page. Naive strategy, often suggested. Here are the problems:

Problem 1 — MCP ↔ Git conflict

You push a new layout from your laptop (layouts/index.html modified). At the same time, the MCP is committing a new article version. Race condition: the MCP might git pull --rebase and fail, or worse, overwrite your local commit.

Problem 2 — MCP’s Git identity

Whose commits is the MCP making? With which GPG key? If you have a “signed commits required” policy, the MCP needs to manage a GPG key, which has to be secured, rotated, etc.

Problem 3 — Unwanted auto-commits

You’re testing, you create a draft article to experiment, you delete it. But the MCP already committed. Now you have a “wip test” commit in history, to rebase or squash manually.

Problem 4 — Asymmetric reversibility

A git revert repo-side has no effect on files the MCP already created. You end up with a desynchronized repo and filesystem state.

Strategy 4: separate the zones

The idea: MCP and Git never write to the same files.

Repo-side .gitignore:

content/
public/
resources/

Implications:

• The MCP can write to content/ whenever. No Git conflict possible.
• You can git reset --hard repo-side with confidence — content/ stays intact.
• No need for the MCP to manage a Git identity.
• No “commit pollution”.

Trade-off: no content versioning

You lose Git versioning of content. That’s a real loss:

• No git blame on an article to see who wrote what.
• No git log content/csp-nonce/index.fr.md for history.
• No PR review for articles.

Mitigation: VM snapshots + daily encrypted content/ backup to QNAP. That covers disaster recovery, but not fine-grained versioning (who-changed-what-when).

For my personal homelab (single author, technical articles, no editorial validation workflow), it’s an acceptable trade-off. For a 10-contributor team blog, I’d reconsider.

Final architecture