Blog engine

Blog engine

The nself.org blog is powered by the ɳSelf stack itself: MDX files served by Next.js with optional Hasura-backed storage for the admin editor workflow.

Publishing a post (MDX file workflow)

Posts live at web/org/src/content/blog/. Create a new .mdx file:

# File name becomes the URL slug
touch web/org/src/content/blog/my-new-post.mdx

Every post file requires a frontmatter block at the top:

---
title: "Your post title"
date: "2026-04-23"
author: "Your Name"
excerpt: "One or two sentence summary shown on the index page."
tags:
  - changelog
  - product
---

Your post content in MDX format...

Required frontmatter fields

Field	Type	Description
title	string	Displayed as the <h1> on the post page and in the index
date	string	ISO date (YYYY-MM-DD). Used for ordering and the RSS feed
author	string	Author display name
excerpt	string	Short summary for index cards and RSS item descriptions
tags	string[]	Canonical tags (see tag taxonomy below)

Tag taxonomy

Use these canonical tags so the tag filter on the index page works correctly:

Tag	When to use
changelog	Release notes and product updates, triggers newsletter N1
product	New features and product direction
technical	Architecture and engineering deep dives
founding	Why we built ɳSelf and origin story
self-hosted	Self-hosting guides and best practices
ai	AI, ML, and intelligent tooling
nself	ɳClaw personal AI assistant posts
vision	Product vision and philosophy

Posts tagged changelog automatically trigger the newsletter N1 pipeline (I05 integration).

Writing MDX

Posts support full MDX: React components, code blocks with syntax highlighting, tables, and GitHub Flavored Markdown.

Code blocks

Use fenced code blocks with a language identifier:

```bash
nself plugin install ai claw
nself build && nself start
```

Callouts

Import a callout component inline:

import { Callout } from '@/components/Callout'

<Callout type="info">
  This only applies when running the full nSelf stack.
</Callout>

Publishing workflow

Draft a post

1. Create the .mdx file in src/content/blog/
2. Add frontmatter
3. Run pnpm dev:org to preview at localhost:3010/blog/your-slug

Review

Share the Vercel preview URL from the PR with reviewers.

Publish

Merge to main. Vercel auto-deploys. The post appears at nself within 60 seconds.

Admin editor (web/base)

The staff admin at base.nself.org/blog provides a browser-based MDX editor backed by Hasura. This is useful for quick edits or when you want a preview pane without running the dev server locally.

Creating a post from the admin

1. Log in to base.nself.org
2. Navigate to Blog in the sidebar
3. Click New post
4. Fill in title, body (MDX), excerpt, tags, and status
5. Set status to Published and click Save

Posts created via the admin are stored in np_blog_posts in the Hasura database and served at nself{slug} via ISR (revalidated every hour).

RSS feed

The RSS feed is available at https:/nself. It includes all published posts with title, excerpt, author, and publication date.

Link the feed in email clients, RSS readers, or your newsletter tool. The I05 newsletter integration reads this feed automatically.

Database schema

The np_blog_posts table:

create table np_blog_posts (
  id               uuid        primary key default gen_random_uuid(),
  slug             text        unique not null,
  title            text        not null,
  body_mdx         text        not null,
  body_html        text,                          -- cached compiled HTML
  excerpt          text,
  author_id        uuid        references nself_accounts(id),
  published_at     timestamptz,
  tags             text[]      not null default '{}',
  status           text        not null default 'draft',
  og_image_url     text,
  source_account_id text       not null default 'primary',
  created_at       timestamptz not null default now(),
  updated_at       timestamptz not null default now()
);

Anonymous users can read rows where status = 'published'. Admins have full read/write access. No published post is writable by non-admin roles.

Comment threads

Each post can display a comment thread backed by the claw plugin. Set nself=blog-comments in web/backend/.env.prod to activate.

Comment threads are associated with the post by its id. Anonymous comments require moderation before appearing. Registered ɳSelf users can comment without moderation.