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
- Saved. The post is a draft. Its
stateisdraft. - Published.
POST repository/publish/post/<sk>copies the post into thepublishedcollection and setsstate: "published"andpublishedDate(appenginerepositories/repository.crud.service.ts1709–1739). Tested: the call answerspublished. A second call with nothing changed answersalready published. - Read by the blog. The blog asks only for the live copy (
published=true). It lists posts whose sk is inpublishedand shows the live copy'sdata,name,postandstyle(liveFilter/overlayLive, 1664–1698). - 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. - Unpublished.
POST repository/unpublish/post/<sk>removes the live copy and setsstate: "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):
| What | Call | Code |
|---|---|---|
| The list | GET repository/find-page-data/post?p=<page>&ps=10&s=publishedAt&st=desc&site=<site name>&en=true&published=true, plus categories= / tags= when filtered | modules/blog/api/blog-api.ts 322–392 |
| One post | GET repository/find-any-id/post/<slug or id>?en=true&published=true. Matches data.slug, name or sk | blog-api.ts 443–474; appengine repository.controller.ts 378–392 |
| Related posts | GET 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=true | blog-api.ts 395–440 |
| Categories | GET repository/category/post, else find-page-data/category | blog-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):
| Field | Where | What the blog does with it |
|---|---|---|
title | data.title | Card 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. |
slug | data.slug | The 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). |
summary | data.summary | Card text. If empty, the first words of content are used (blog-api.ts 753–756, 864–880). |
content | data.content | The post body, as HTML (dangerouslySetInnerHTML, BlogPostView.tsx 191). Inline <script> doesn't run. Reading time is worked out from it. |
coverImage | data.coverImage (a URL string) | Card image and the big image on the post, drawn with next/image. See the warning below. |
author | data.author { name, bio, email, website } | Name and initial on the post. |
contentType | data.contentType | Keep 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. |
sites | data.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. |
template | data.template | Studio's Organization › Template (a flexdata name). The blog does not read it. |
categories | post.categories (category names) | Category chips and ?category= filter. They must be existing category records; Studio's picker reads that collection. |
tags | post.tags | Tag chips, "Popular Tags", ?tag= filter. Free text. Tested. |
allowComment | post.allowComment | false closes comments: "Comments are closed on this post." Tested. |
allowShare, allowRating, showRelated | post.* | Not read by the blog (no reference in base-app modules/blog). Share buttons and related posts always show. |
publishAt | data.publishAt | Set 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.tsx54). - 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.ts674–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 whosesitesnames 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:
| Field | Value |
|---|---|
title | the title |
slug | lower-case words with hyphens, unique: spring-sale-2026 |
contentType | post |
summary | one or two sentences for the card |
content | the body as HTML: <p>, <h2>, <ul>, <img>, <a>. No <h1> (the title is the heading), no <script> |
coverImage | the URL of a file in the file manager |
author | { "name": "…" } |
sites | leave 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_appenginePOST repository/publish/post/<sk>. It answerspublished. - At a time:
call_appenginePOST content-studio/<sk>/schedulewith{ "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.ts114–133). At that time the engine publishes it, then setsdata.publishedOnScheduleand clearspublishAt. 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_appenginePOST repository/unpublish/post/<sk>. The post stays as a draft. - To delete it:
delete_recordonpost. 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.tsx194–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.ts38). - The view count always reads 0. It reads
data.views; the engine counts views instats.views(blog-api.ts784–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 keepspublishedDate(blog-api.ts327, 780). Posts come out newest-created first because the record id breaks the tie. allowShare,allowRatingandshowRelateddo nothing on the blog, and the post's Template isn't used.siteshides 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
categoriesortagsindata. They belong in thepostblock. - Don't write
{ "post": { … } }or{ "data": { … } }toupdate-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.