Authors

Ghost-style author management. The people a site's posts are by each have a profile, kept as one JSON file in the site's own content (src/content/authors/<slug>.json by default), so the site's build reads them like any other content and git keeps their history. A post names its author by slug, and may list co-authors.

What an editor sees:

• Authors (More menu, #/authors): every author with their role, slug, post counts and author page; add, edit, archive, change a slug, delete.
• Post settings → Author: a searchable list of the site's authors instead of a text box, "Add … as a new author" when the name is not there, co-authors as chips, and a plain warning (never an error) when the post names an author the site does not have.

Code: packages/core/src/authors.mjs (pure: config, profiles, checks, Person JSON-LD), packages/server/src/authors/ (the server's routes), packages/astro/src/api-authors.mjs (the same routes in astro dev), packages/astro/src/authors.mjs (@markstage/astro/authors, the site's helpers), and in the editor src/admin/authors/ (the screen) and src/settings/author-field.ts (the field).

Turning it on

In markstage.config.mjs (docs/CONFIG.md, key authors):

export default defineConfig({
  authors: { coAuthors: 'coAuthors' },   // or `authors: true` for every default
  collections: [
    {
      id: 'posts', format: 'md', dir: 'src/content/posts', hasStatus: true,
      // a text or select setting of the author key becomes the author picker
      settings: [{ type: 'text', key: 'author', label: 'Author' }],
    },
  ],
});

The default keys follow a common shape (designation, avatar, a nested seo), so an existing folder of author files works as it is:

An entry names its author in its author field (the collection's fields.author). A value that is not a slug of the site (an old free-text name) keeps working: the post is not touched, the picker shows a warning, and the next save that changes the author picks a real one.

The checks

• On save. An entry save (editor, Source mode, a new entry, bulk changes, the dev API) may not add an author the site does not have, or one that is archived: 422 unknown-author, with fields: {author: "…"} and authors: [{slug, problem: "unknown"|"archived", message}]. An author the entry already named is left alone, so old posts still save.
• In the build. The integration's build step reads every entry of the author collections: one that names an author the site does not have fails the build, naming the file and the author:

  markstage: an entry names an author the site does not have (src/content/authors):
    src/content/posts/old.md: “guest-writer” is not one of the site's authors. Pick an author, or add “guest-writer” as an author first.

  An archived author passes (their old posts still build). markstage({checkAuthors: false}) turns the check off.

Routes

The same on the Markstage server (/markstage/api/…, signed in, each change one git commit by the person) and in astro dev (no sign-in, no git). Every answer that is not a GET takes the author's version (the file's hash): a stale one is 409 conflict.

Author is the profile (the fields above) plus url (the author page, a site path, or null), version, posts and live (how many entries name them, and how many of those are published). email is there only for editors and above and the person themselves. Errors: 422 invalid with fields: {<field>: words} (a name missing, a website or profile link that is not an https address, a slug with other characters), and 422 posts-refused when any post to be changed would fail its own save checks: then nothing is changed.

Audit actions: author.create, author.update, author.archive, author.rename, author.delete. The ability is authors.manage (editors and above, docs/API-PERMISSIONS.md).

A change to a profile is not published by itself (the site shows it after the next build): the screen's toast offers Publish now when the author has live posts.

The Authors screen

Every state is in the URL, so each can be linked to, reloaded and gone back from:

An author signed in as themselves (Users → author) sees the list and may edit their own profile; another author's email and the add, archive, rename and delete actions are not there for them, and the server refuses them anyway.

The site's pages: @markstage/astro/authors

import { getAuthors, getAuthor, getEntriesByAuthor, personJsonLd } from '@markstage/astro/authors';

They read the files the config names, during the build and in astro dev; authorsOf(cfg) gives the same helpers for a normalized config (scripts, tests).

An author hub and author pages

The example blog has both (examples/blog/src/pages/author/).

src/pages/author/index.astro, the hub:

---
import { getAuthors, getEntriesByAuthor } from '@markstage/astro/authors';
const authors = await Promise.all((await getAuthors()).map(async (a) => ({ ...a, posts: (await getEntriesByAuthor(a.slug)).length })));
---
<ul>{authors.map((a) => <li><a href={a.url}>{a.name}</a> {a.role} · {a.posts} posts</li>)}</ul>

src/pages/author/[slug].astro, one page per author (archived ones too, so old links keep working):

---
import { getAuthors, getEntriesByAuthor, personJsonLd } from '@markstage/astro/authors';
export async function getStaticPaths() {
  return (await getAuthors({ archived: true })).map((author) => ({ params: { slug: author.slug }, props: { author } }));
}
const { author } = Astro.props;
const posts = await getEntriesByAuthor(author.slug);
const json = JSON.stringify(await personJsonLd(author)).replace(/</g, '\\u003c');
---
<div><script type="application/ld+json" set:html={json} /></div>
<h1>{author.name}</h1>
<ul>{posts.map((p) => <li><a href={p.url}>{p.title}</a></li>)}</ul>

A post's byline links each author: getAuthor(post.data.author), then the coAuthors list. Add author (a string) and coAuthors (a list of strings) to the collection's schema in content.config.ts.