Publish a Blog Post

Use this skill whenever you're adding a post under the repo-root blog/ directory, starting a new major-version section of it, or retiring a post that's out of date. The blog holds release announcements and other point-in-time posts. Release posts are dual-published here from blog.emberjs.com so that consumers who don't use Ember don't have to go looking for them there. Every post's URL is a permanent contract with readers, so most of the rules below exist to keep a post's path, date and version from ever changing under them.

For drafting the prose itself, follow Write Documentation as well; this skill covers where a post goes and how it gets listed. If the post announces a release, start from Draft a Release Blog Post, which gathers its content and says when it has to merge.

Steps

1. Read Upgrading and Blog Pages before writing anything. It owns the rules this skill relies on: URLs are never renamed or unpublished, every post is dated and versioned, and posts are organized by major version.
2. Put the post at blog/v<major>/<slug>.md, where <major> is the major version that was current when the post is published. Pick the slug as if it can never change, because it can't: the URL is also the post's ID in the RSS feed, so renaming it later shows every subscriber the post again as new.
3. If blog/v<major>/ doesn't exist yet, create it with:
   • an index.md whose frontmatter has a title (<major>.x) and a description, an H1, one sentence of intro, and <BlogPostList version="<major>" />, copying blog/v5/index.md;
   • a _meta.json with the section's title and items: ["index"];
   • the directory added to items in blog/_meta.json, so sections sort in release order, and a link to the new section added to the "browse posts by major version" sentence in blog/index.md.
4. Give the post frontmatter title, description, and date (YYYY-MM-DD, the publish date), and put the <SinceBadge> and date line under the H1, as the guide in step 1 shows. Copy an existing post such as blog/v5/introducing-upgrading-and-blog.md for the shape. The docs build fails on a post without a valid date.
5. Add the post's slug to items in its directory's _meta.json, after the posts already there. That only orders the sidebar.
6. Don't add the post to any list by hand. /blog/, each /blog/v<major>/ page and /blog/feed.xml are all generated from post frontmatter by blogPosts in docs-viewer/src/site-utils.ts, so a post appears in all three, newest first by date, as soon as it exists and isn't a draft. If a post is missing from them, fix its frontmatter, not the listing.
7. To retire a post, follow URLs are never renamed or unpublished. Its draft: true also takes it out of the listings and the feed, while its URL keeps working.
8. Run pnpm lint:docs from the repo root, then build the site as Previewing Your Changes describes and check the post's page, /blog/ and /blog/feed.xml. A post added while pnpm start is running needs a restart before it shows up in the sidebar.