Showing posts in your own pages¶

The built-in reader at /blog/ is deliberately plain. Most projects want posts somewhere else too: a "Latest from the blog" strip on the home page, a /news/ page in the project's own theme, a React or Astro front end, a static site. This page is the recipe for each of those, and for publishing into a blog from your own code.

Everything below rests on one rule: never filter posts yourself. Which posts a visitor may see depends on the blog's visibility (private / members / public), the post's status, and whether its publish time has passed — a scheduled post is published with a future published_at. The scopers in apps.blog.permissions and the public JSON API encode all three. Use them and your page shows exactly what /blog/ shows.

Pick the route¶

In a Django template (same project)¶

Query through the permission scopers, then render the stored HTML.

# apps/website/views.py
from django.shortcuts import render

from apps.blog import permissions
from apps.blog.models import Post


def home_view(request):
    latest = (
        permissions.viewable_posts(request.user)       # what THIS visitor may read
        .filter(blog__slug="field-notes")             # optional: one blog
        .select_related("blog", "author")
        .prefetch_related("tags")
        .order_by("-published_at", "-id")[:3]
    )
    return render(request, "website/home.html", {"latest_posts": latest})

{# templates/website/home.html #}
<section class="card">
  <h2>Latest from the blog</h2>
  {% for post in latest_posts %}
    <article>
      <h3><a href="{{ post.get_absolute_url }}">{{ post.title }}</a></h3>
      <p>{{ post.excerpt }}</p>
      <small>
        {{ post.published_at|date:"j M Y" }} · {{ post.blog.name }}
        {% for tag in post.tags.all %} · {{ tag.name }}{% endfor %}
      </small>
    </article>
  {% empty %}
    <p>Nothing published yet.</p>
  {% endfor %}
  <a href="{% url 'blog:blog_detail' 'field-notes' %}">All posts →</a>
</section>

Two scopers cover every case:

• permissions.viewable_posts(user) — everything user may read: live posts in blogs they can see, plus their own drafts if they are an author. Pass request.user and an anonymous visitor, a colleague on a members blog and the owner previewing a draft all get the right answer from one line.
• permissions.public_posts() — the anonymous subset only (live posts in public blogs). Use it for anything cached or shared between visitors, such as a sitemap, a home-page strip rendered into a page cache, or a feed.

Both accept an optional queryset to narrow first: permissions.public_posts(Post.objects.filter(is_featured=True)).

A full post page in your theme¶

If you want the article itself inside your own base template rather than the built-in reader:

from django.shortcuts import get_object_or_404, render

from apps.blog import permissions


def article_view(request, blog_slug, post_slug):
    post = get_object_or_404(
        permissions.viewable_posts(request.user).select_related("blog"),
        blog__slug=blog_slug,
        slug=post_slug,
    )
    return render(request, "website/article.html", {"post": post})

{% extends "smallstack/base.html" %}
{% load static %}
{% block extra_css %}<link rel="stylesheet" href="{% static 'blog/public.css' %}">{% endblock %}
{% block content %}
  <article class="blog-article">
    <h1>{{ post.title }}</h1>
    {% if post.cover_image %}<img src="{{ post.cover_image.url }}" alt="{{ post.cover_alt }}">{% endif %}
    {% if post.body_toc %}<nav aria-label="On this page">{{ post.body_toc|safe }}</nav>{% endif %}
    {{ post.body_html|safe }}
  </article>
{% endblock %}

The fields you will reach for:

Linking back into the built-in reader works with the blog URL namespace: {% url 'blog:post_detail' post.blog.slug post.slug %}, {% url 'blog:tag' post.blog.slug tag.slug %}, {% url 'blog:archive' blog.slug %}.

Search on your own page¶

apps.search.registry.search_all(query, user=request.user) returns ranked hits across every searchable model, already scoped per visitor; keep the ones with model_label == "smallstack_blog.Post". Each hit's extra carries the blog name, publish date, reading time, tags and cover (the blog's transform_hit), so you can render a rich result without a second query.

From another front end (the JSON API)¶

Anonymous, no token, published content only, mounted next to the reader:

A post object in a list:

{
  "uid": "7b1b2c0e-…",
  "slug": "running-postgres-without-surprises",
  "title": "Running Postgres Without Surprises",
  "excerpt": "SQLite forgives a great deal. Postgres does not…",
  "url": "/blog/field-notes/running-postgres-without-surprises/",
  "canonical_url": null,
  "published_at": "2026-10-11T09:00:00+00:00",
  "updated_at": "2026-10-11T09:12:41+00:00",
  "tags": [{"slug": "ops", "name": "ops"}, {"slug": "postgres", "name": "postgres"}],
  "author": "everett",
  "cover": {"url": "/media/blog/covers/2026/10/….jpg", "alt": "A dashboard"}
}

url and cover.url are site-relative. Prefix them with the site origin when the front end lives on another host. cover is null when there is no image. Page size follows SMALLSTACK_BLOG_PAGE_SIZE (default 10); walk page until it equals pages.

// A React / Astro / plain-fetch client
const ORIGIN = "https://example.com";

export async function latestPosts(blog, page = 1) {
  const res = await fetch(`${ORIGIN}/blog/api/blogs/${blog}/posts/?page=${page}`);
  if (!res.ok) throw new Error(`blog api ${res.status}`);
  const data = await res.json();
  return data.posts.map((p) => ({ ...p, url: ORIGIN + p.url }));
}

export async function post(blog, slug) {
  const res = await fetch(`${ORIGIN}/blog/api/blogs/${blog}/posts/${slug}/`);
  if (res.status === 404) return null;
  const { post } = await res.json();
  return post;            // post.body_html is sanitised; render it as HTML
}

# A static-site generator, or any Python caller
import requests

ORIGIN = "https://example.com"

def all_posts(blog: str) -> list[dict]:
    posts, page, pages = [], 1, 1
    while page <= pages:
        data = requests.get(f"{ORIGIN}/blog/api/blogs/{blog}/posts/", params={"page": page}, timeout=10).json()
        posts += data["posts"]
        page, pages = data["page"] + 1, data["pages"]
    return posts

What to expect from the API:

• Visibility is enforced the same way as the reader. A private blog is a 404 (its existence is not public). A members blog is a 404 to an anonymous caller — a JSON client cannot follow a login redirect — but a browser with a signed-in session gets it, so a same-origin front end for a team blog works without tokens.
• Drafts and scheduled posts never appear, for anyone, including the author. This API is the anonymous read surface; authors see drafts in the studio and the console.
• Responses carry Cache-Control: public, max-age=60. A CDN or browser may serve a post for up to a minute after an edit.
• Cross-origin browsers need CORS. Set CORS_ALLOWED_ORIGINS in .env (comma-separated) to the front end's origins; server-to-server callers need nothing.
• Switching the public surface off (SMALLSTACK_BLOG_PUBLIC_ENABLED=False) makes every route here a 404, the HTML pages included. Drafting internally with nothing public yet is a supported state.
• Permalinks survive renames via /blog/p/<uid>/, which redirects to the current url. Store uid if you cache posts on your side.

Do not point a public front end at /smallstack/api/blog/posts/. That is the authenticated write API; it answers 401 to anonymous requests and, with a token, returns only what that token's owner may edit.

Publishing from your own code¶

Three ways in, in order of preference.

Python, inside the project — the service layer is the only write path the blog itself uses, so going through it gets the same slug generation, HTML rendering, excerpt derivation, search indexing and webhook events as the studio:

from apps.blog import service
from apps.blog.models import Blog

blog = Blog.objects.get(slug="field-notes")
post = service.create_post(
    blog,
    title="Release notes, October",
    body_markdown=markdown_text,
    tags=["release"],
    author=request.user,
    actor=request.user,          # permission-checked; None means a trusted internal caller
)
service.publish_post(post, actor=request.user)                 # now
service.schedule_post(post, when=aware_datetime, actor=request.user)  # or later

update_post refuses status and the timestamps; publishing, scheduling, unpublishing and archiving are explicit calls so nothing goes live by accident. A runbook document can be published with service.publish_document(document, blog, sync="auto") — see Publishing runbook pages.

REST, from outside — mint a token under API Tokens, then:

POST /smallstack/api/blog/posts/
Authorization: Bearer <token>
{"blog": 1, "title": "…", "body_markdown": "…"}

This creates a draft. Publishing is not a field you can PATCH; a human publishes in the studio, or an agent calls the MCP tool below.

MCP, from an AI client — blog_draft_post (markdown + tag names), blog_publish_post, blog_unpublish_post, blog_publish_runbook_document. Each sees exactly what the token's owner may see.

Keeping your pages fresh¶

If your front end caches or pre-renders, subscribe a webhook endpoint under Webhooks to smallstack_blog.post.created, .updated and .deleted and rebuild the affected page on delivery. On created and updated the envelope's data is the post as the REST API serialises it (id, uid, slug, blog, status, published_at, …), so a static site can rebuild one page rather than all of them; a deleted event carries only id, so key your cache by id as well as uid. There is no event for a post merely becoming live at its scheduled time without an edit, so a site that shows scheduled posts promptly should also re-fetch on a short timer, or simply rely on the API's one-minute cache.

Gotchas¶