docs
/
AI skills

Write and publish a blog post

Take a post from draft to live on the site's built-in blog. Covers the post's fields, publishing, scheduling and the Content Studio preview, how /blog draws the list and each post, which page frames it, and what sharing, RSS and search can and can't do.

A blog post is a post record (post, contentType: "post"). The Blog feature draws every published post at /blog and each post at /blog/<slug>. The page is drawn by the platform, not by a page of the site. A post is written and published in Content Studio (/content-studio). This skill covers the post itself. How /blog gets its address, and how it is moved or switched off, is in Site page routing. Which page frames it is in Built-in pages and templates. Comments under the post are in Moderate comments and reviews.

"Tested" below means checked on the local engine with test posts, and on a test site with the Blog switched on for a few minutes. Everything was deleted afterwards. Everything else is read from the code, with the file named.

How a post gets to /blog

  1. Saved. The post is a draft. Its state is draft.
  2. Published. POST repository/publish/post/<sk> copies the post into the published collection and sets state: "published" and publishedDate (appengine repositories/repository.crud.service.ts 1709–1739). Tested: the call answers published. A second call with nothing changed answers already published.
  3. Read by the blog. The blog asks only for the live copy (published=true). It lists posts whose sk is in published and shows the live copy's data, name, post and style (liveFilter / overlayLive, 1664–1698).
  4. Edited later. Any save sets the source back to draft, but visitors still see the old live copy until it is published again. Tested: after an edit the post page still showed the old text, and a second publish brought the new one.
  5. Unpublished. POST repository/unpublish/post/<sk> removes the live copy and sets state: "draft" (1742–1757). Tested: the post leaves the list. Its link shows "We can't find that post".

The blog is a client page. The browser calls the site's own /api (base-app modules/blog/api/endpoints.ts):

WhatCallCode
The listGET repository/find-page-data/post?p=<page>&ps=10&s=publishedAt&st=desc&site=<site name>&en=true&published=true, plus categories= / tags= when filteredmodules/blog/api/blog-api.ts 322–392
One postGET repository/find-any-id/post/<slug or id>?en=true&published=true. Matches data.slug, name or skblog-api.ts 443–474; appengine repository.controller.ts 378–392
Related postsGET repository/find-related/post/<id>?limit=4&published=true&site=<site name>blog-api.ts 519–548
Search (?q=)GET repository/search/post?…&site=&published=trueblog-api.ts 395–440
CategoriesGET repository/category/post, else find-page-data/categoryblog-api.ts 266–320

The post's fields

data fields (dbsdk models/post.ts) and the record's post block (dbsdk base.model.ts PostSubSchema 155–215):

FieldWhereWhat the blog does with it
titledata.titleCard and post heading. A leading <h1> in content that repeats the title is dropped, so it isn't shown twice (BlogPostView.tsx 33, 191). The record's name is set to the title.
slugdata.slugThe address: /blog/<slug>. Set it yourself. The engine makes none, and its schema pattern (^[a-zA-Z_\-0-9]*$, 3–100 characters) is not enforced. Tested: "Bad Slug!" was saved. A slug already used by another post is refused: 409 A post with slug "…" already exists. (tested). Studio fills it from the title as you type (post-form.tsx 345–354). With no slug, links fall back to the record's name, which is the title with its spaces (blog-api.ts 752).
summarydata.summaryCard text. If empty, the first words of content are used (blog-api.ts 753–756, 864–880).
contentdata.contentThe post body, as HTML (dangerouslySetInnerHTML, BlogPostView.tsx 191). Inline <script> doesn't run. Reading time is worked out from it.
coverImagedata.coverImage (a URL string)Card image and the big image on the post, drawn with next/image. See the warning below.
authordata.author { name, bio, email, website }Name and initial on the post.
contentTypedata.contentTypeKeep post. documentation, course and ebook are hidden from the blog unless Content Player is on; then their cards link to the player (blog-api.ts 193, 355–361). See Course with a quiz.
sitesdata.sites (site names)Empty: the post is on every site of the business. Listed: only those sites list it. Tested. Studio has no field for it.
templatedata.templateStudio's Organization › Template (a flexdata name). The blog does not read it.
categoriespost.categories (category names)Category chips and ?category= filter. They must be existing category records; Studio's picker reads that collection.
tagspost.tagsTag chips, "Popular Tags", ?tag= filter. Free text. Tested.
allowCommentpost.allowCommentfalse closes comments: "Comments are closed on this post." Tested.
allowShare, allowRating, showRelatedpost.*Not read by the blog (no reference in base-app modules/blog). Share buttons and related posts always show.
publishAtdata.publishAtSet by scheduling (step 4). Don't write it by hand.

A cover on an unknown image host breaks the whole blog. next/image only accepts picsum.photos, via.placeholder.com, *.public.blob.vercel-storage.com, avatars.githubusercontent.com and **.digitaloceanspaces.com, which is where files uploaded to the business's file manager live (base-app next.config.ts 62–93). Tested: one published post with its cover at https://example.com/… crashed /blog and every post that showed it as a related card. Use a file from the file manager. Never use an image from the business's own domain or another website.

The record's post block is not inside data. create_record, update_record_partial, repo_create and repo_update write data only. Set categories, tags and allowComment with call_appengine POST repository/update-partial/post/<sk> and dot paths: { "post.categories": ["News"], "post.tags": ["launch"] }. Tested: this keeps the post published. In Content Studio's editor, update_data with an _envelope key does the same (ai/skills/post-studio.skill.ts).

What the reader sees

The list (/blog, modules/blog/BlogView.tsx). Tested.

  • A "Blog / Discover insights, tutorials, and updates from our team" heading. It shows only while the blog is at /blog; at a moved address the page's own design is the heading (BlogRoute.tsx 54).
  • A search box and the category chips. Every category of the business is listed, not just the ones posts use. Tested: a shop category showed.
  • The cards: cover, title, summary, author and reading time. Ten per page, with page numbers.
  • A sidebar with "Popular Tags", from the posts shown.
  • A sidebar "Subscribe to our newsletter" box. It posts to the promotion named newsletter (blog-api.ts 674–700). See Newsletter setup before telling anyone it works.

The post (/blog/<slug>, modules/blog/BlogPostView.tsx). Tested.

  • Breadcrumb (Home › Blog › title), cover, title, author, reading time, "N views", a like button, then category and tag chips.
  • The body.
  • "Share this post": Twitter, Facebook and LinkedIn buttons.
  • The comments (Moderate comments and reviews).
  • Related Posts.

Frame. The blog sits inside the page at its address if there is one (that page's first screen above, its second below), else account-layout. ?embed=true drops the frame. See Built-in pages and templates. To change the blog's look, change that template page; the post itself has no layout setting.

Sharing. Each post page carries the site's default title and share card, not the post's own. Tested: <title> was the site title and og:type was website; base-app app/[[...slug]]/page.tsx generateMetadata has no post case. A link pasted into Facebook or LinkedIn shows the site, not the post. The site defaults are set in Site identity, SEO and sharing.

Ask first

  • Which site? A business can have several. The blog lists posts with no sites, or whose sites names this site.
  • Is the Blog switched on, and at which address? Read site.data.features (step 1). If it's off, the person must decide to turn it on.
  • The post: title, the text (or what to write about), the summary for the card, the cover image (a file in their file manager), the author, categories (existing ones) and tags.
  • When: publish now, at a set time (with the time zone), or leave as a draft for review.

Steps

1. Site Config: is the blog on?

repo_find on site by data.name, then repo_find_one by its id. Look at data.features: blog, or a row { "feature": "blog", "enabled": true, "page": "<page name>" }. A row with a page puts the blog at that page's address.

If it's off and the person wants a blog, switch it on as Site page routing says: write the whole list with the dot path data.features.

Stop: switching the Blog on makes /blog live, showing every published post the business has. Read out the published posts first (step 6), and wait for yes.

Hands on: the site name and the blog's address. Check: open <site>/blog. 200 and the blog list means it's on; 404 means it's off.

2. Content Studio: write the post

create_record with datatype post:

FieldValue
titlethe title
sluglower-case words with hyphens, unique: spring-sale-2026
contentTypepost
summaryone or two sentences for the card
contentthe body as HTML: <p>, <h2>, <ul>, <img>, <a>. No <h1> (the title is the heading), no <script>
coverImagethe URL of a file in the file manager
author{ "name": "…" }
sitesleave it out, or ["<site name>"] to keep it to one site

Then set the post block. Use call_appengine POST repository/update-partial/post/<sk> with { "post.categories": [ … ], "post.tags": [ … ] }. By API in one call, the same record can be sent to POST repository/create with "isNew": true and a top-level "post": { "categories": [], "tags": [], "allowComment": true } (tested).

Studio: Content Studio → new post. Fill Title and Content. Basic Information holds Status, URL Slug and Summary; then fill Author and Cover Image. Categorization holds categories, tags and the switches.

Hands on: the post's sk and slug. Check: repo_find_one on post with the sk: the slug, summary, cover and the post block are there, and state is draft.

3. Content Studio: preview it

call_appengine POST content-studio/<sk>/preview-key returns a key that works for one hour (staff only; tested 403 without sign-in). The preview address is:

<site>/__preview/post/<slug or sk>?key=<key>

It shows the draft in the Content Player's reading layout, not the blog's (base-app components/content-player/ContentPlayerRoute.tsx 177–215). Tested: with the key it showed the draft. Without it the page said "This preview can't open. Open the preview from the content studio." In Studio, the Preview button in the post editor does this.

The address Studio's Preview button opens also carries the staff member's email (?email=…, websitemint post/post-preview.ts 29). Don't paste that link anywhere public. Build the link above instead.

Hands on: the preview link. Check: it opens and shows the title, cover and body.

4. Content Studio: publish now, or schedule

If the org has publishing review on, ask first, exactly as in Publish, unpublish and restore a page step 4 (POST /approval/ask with the post). Studio's Publish button asks for you (post-store.ts 257).

  • Now: call_appengine POST repository/publish/post/<sk>. It answers published.
  • At a time: call_appengine POST content-studio/<sk>/schedule with { "at": "<ISO date-time with offset>" }. The answer is { sk, state: "scheduled", publishAt }. The time must be at least 30 seconds ahead, or you get 400 "Pick a time in the future." (content-studio/content-schedule.service.ts 114–133). At that time the engine publishes it, then sets data.publishedOnSchedule and clears publishAt. A sweep every minute catches any run that was lost (8–10, 150–160). Tested: a post scheduled 100 seconds ahead went live on time.
  • Cancel a schedule: POST content-studio/<sk>/unschedule. The post stays a draft.

Studio: Basic Information › Status → Scheduled, then Publish at.

A scheduled post publishes without the publishing review: the job calls the publish directly (content-schedule.service.ts 157). On an org with review on, get approval before scheduling.

Stop: publishing puts the post on the live site for anyone. Scheduling does the same later, with no one there. Show the person the title, address, summary and cover (and the time, in their time zone), and wait for yes.

Hands on: published, or the publishAt that came back. Check: repo_find_one on the post: state is published (or scheduled with publishAt). Open <site>/blog/<slug>: the post shows. Open <site>/blog: its card is there.

5. Changing or removing a live post

  • To change it: save the change, then publish again. Until then the old version stays live.
  • To take it down: call_appengine POST repository/unpublish/post/<sk>. The post stays as a draft.
  • To delete it: delete_record on post. It goes to the Trash. Unpublish it first.

Stop: unpublishing breaks every link to the post. Say so, and wait for yes.

Check: <site>/blog/<slug> shows "We can't find that post" after an unpublish.

6. Check what is really live

call_appengine GET repository/find-page-data/post?published=true&site=<site name>&ps=50 lists exactly what the blog lists. Compare it with what the person expects.

When it's done

Tell the person:

  • the post's address (/blog/<slug>), whether it is live, scheduled (and when, in their time zone) or a draft;
  • that later edits need Publish again to go live;
  • that a shared link shows the site's own title and image, not the post's (see below).

Open the post in Content Studio (navigate to /post with { openId: "<sk>" }) and the live page.

What it can't do yet

Visitors only ever read the live copy. For anyone but staff, every post and page read (find-page-data, search, find, find-any-id, find-by-attribute) is held to published records and answers their live content, with or without published=true; drafts and scheduled posts are staff only (repository.controller.ts visitorContent). To show someone a draft, use the preview key (step 3).

  • No per-post title, description or share card. Every post page carries the site's defaults. There is no Article JSON-LD either. Tested.
  • Share buttons do nothing. Twitter, Facebook and LinkedIn have no action (BlogPostView.tsx 194–207). Tested.
  • No RSS or Atom feed, anywhere in base-app or appengine.
  • Posts are not in the sitemap. It lists page records only (Sitemap, robots and search indexing).
  • The like button doesn't save. It posts to crm/activity/manage, which doesn't exist (404, tested; api/endpoints.ts 38).
  • The view count always reads 0. It reads data.views; the engine counts views in stats.views (blog-api.ts 784–785). Tested.
  • No date on the post, and the list is not in date order. The blog reads and sorts on publishedAt, which no post has; the engine keeps publishedDate (blog-api.ts 327, 780). Posts come out newest-created first because the record id breaks the tie.
  • allowShare, allowRating and showRelated do nothing on the blog, and the post's Template isn't used.
  • sites hides a post from other sites' lists, but its direct link still opens on them. Tested.
  • The category chips list every category of the business, shop categories included. Tested.
  • Fixed light-theme colours. The blog's text is dark grey on no background of its own. On a dark site it can be nearly unreadable. Tested. Give the blog a light template page, or warn the person.
  • No slug is made by the engine and its pattern isn't checked. Only Studio fills it.

Don'ts

  • Don't publish or schedule without a yes, and don't publish around publishing review.
  • Don't set a cover from another website or the business's own domain. Upload it to the file manager first.
  • Don't put categories or tags in data. They belong in the post block.
  • Don't write { "post": { … } } or { "data": { … } } to update-partial: each replaces the whole block. Use dot paths.
  • Don't say a post's edit is live until it is published again.
  • Don't promise visitors a share preview, an RSS feed, likes or view counts.
  • Don't turn the Blog on, or move it, without the person's yes.