Articles
The SEO app writes pages into your repository as files, and your own site builds them — what it does, what it does not, and how the wiring goes.
You have a site. You want pages on it that a search engine finds and a person
reads to the end. The SEO app is where those pages are written, and where they
are written to is your repository.
[!NOTE]
Writing pages is afk, not the free plan. The screen opens
on a Local machine and you can see what it is; the machine refuses to write
one, and says which plan it wants. See Local.
What it does, and where it stops
An article is a file: .beafk/seo/<collection>/<slug>.mdx, in the project the
panel is standing in. A collection is a folder in there — blog, changelog,
compare — and it is committed with the rest of your work, reviewed the way
your code is reviewed, and deployed by whatever already deploys your site.
beafk serves nothing. There is no CDN of ours and nothing of ours runs when
a reader arrives. beafk writes the file; your build turns it into a page; your
host puts it on the web. If your site deploys from a push, nothing is on the
web until somebody pushes.
beafk writes nothing either. No model of ours runs on your articles. The
agent on your machine — Claude, GPT, Grok, Kimi, on the
subscription you already pay for — is the writer, and the app is where you ask
it and where you read what it wrote.
The file
Five lines of front matter, then the page:
---
title: Nothing is deleted — a thirty day drawer instead
description: One sentence, under 160 characters, that a result will show.
tags: [trash, design]
cover: /covers/piece-a1b2c3.png
coverAlt: the trash screen, thirty days of it
---
Those five and nothing else. The description is what a search result shows
and is cut at 160 characters. The cover is the URL a reader's browser will
fetch — never a path relative to the file, because that previews perfectly and
ships a broken image.
The body is markdown, and it may use your site's own components as tags —
<Callout>, <Figure> — without importing them. Your site supplies them by
name when it renders. Keep the body to markdown and tags: an export or a
{rows.map(…)} compiles on Astro and Next and prints as text on Hugo,
Eleventy and SvelteKit.
Making your site read it
Your framework has to be pointed at the folder once, per collection. Every
framework can be: Astro's glob loader takes a base, Hugo takes a module
mount, Nuxt Content takes a cwd, Next reads the folder with
next-mdx-remote, Eleventy takes a symlink or a virtual template. That is a
job for the agent, and the page it reads first is the setup-articles
skill — it is on every machine, and it is what an agent given "the site does
not show my articles" opens before touching a config file.
Two things it will need from you:
- The site's public address.
og:image and the canonical link have to be
absolute, and a build that does not know its own origin ships
http://localhost:3000 in the head of every page. It is site in Astro,
metadataBase in Next, baseURL in Hugo. Have it in the config, or say it.
- Where the pictures go. A cover's bytes must be somewhere the site
serves. Either the folder your build already serves —
public/, static/ —
or a bucket you own (S3, R2, Backblaze, MinIO), where the object is public
and the URL is permanent. A covers/ folder beside the articles is not
served by anything until it is copied or mounted.
Then the check that matters is not the build's exit code. It is the built HTML
of one article: the six head tags, the cover the head names present in the
output, and no component printed as text.
What "published" means
A draft is a file whose name starts with _. Every loader the skill sets up
skips it, so a draft stays in the folder, in the repository, and off the site.
Publishing is the person's press, not the agent's. An agent asked to write a
page writes the file and says it is ready; committing it and pushing it are
yours, and so is renaming a slug — a slug is a live URL, and a rename without a
redirect is a page that was indexed and is now a 404.
The screen is the page, not an editor
There is nothing to type into. An article's screen is the page your site
draws, photographed at your phone's width, with its standing over it — draft,
not on the web yet, on the web, changed since it went up — and one button under
it. Tap a paragraph and the button becomes that paragraph's chips; say
"shorter" and the agent rewrites that block and nothing else, with an undo in
the same place.
The button is the publish: Publish for a draft or a page that has never
been out, Update the page for one that has changed since it went up, and
On the web — unpressable — when the file and the commit agree. ⋯ has the
rest: open it on the web, open the file, take it off the web, discard the edits
since the commit, move it to the trash.
What is still yours
- Bucket credentials are not stored. Put a cover's bytes where the site
serves them, or upload them with your own tooling, and write the URL into the
front matter.
- Nothing pushes. A publish is a commit in your repository; the push, and
the build that follows it, are your pipeline's.
The two skills, write-an-article and setup-articles, were tested on
Astro, Next, Hugo, Eleventy, SvelteKit and Nuxt with four different agents.