Blog CMS

Overview

The Blog CMS in TanStack Ship provides a complete, production-ready content management system designed for technical blogging at scale. Built with support for rich technical content, code highlighting, and diagram rendering, it enables creating code tutorials, architecture documentation, and multi-language publishing workflows.

As part of the platform, the Blog CMS integrates with R2 storage for media assets, the XML sitemap system for SEO visibility, and a full admin interface for content workflow management. Posts are stored with full CRUD operations, while the public blog features pagination, related post suggestions, and seamless multi-language switching for global audiences.

Design Flow

The Blog CMS orchestrates the complete content publishing pipeline, from author creation through MDX compilation to multi-language delivery:

Core Capabilities

Rich Content Creation

Blog posts support rich formatting for technical content:

• Full Markdown — Standard Markdown including headings, tables, lists, links, images, and blockquotes
• Code Blocks — Syntax-highlighted code with support for 100+ languages and copy-to-clipboard functionality
• Mermaid Diagrams — Render flowcharts, sequence diagrams, Gantt charts, and class diagrams directly in blog content
• Frontmatter Metadata — Structured metadata including title, description, tags, author, publish date, and locale

Multi-Language Publishing

Each blog post can exist in multiple languages:

• Sibling Linking — Posts in different languages are linked together, enabling synchronized content across locales
• hreflang SEO Tags — Automatically generated hreflang meta tags signal language targeting to search engines
• Language Switcher — Readers can switch between available language versions on the post detail page
• Shared Slug — All language versions share a common slug, with locale prefix differentiating URLs

Content Organization and Discovery

The system provides robust content categorization:

• Tag System — Posts can be tagged with color-coded taxonomy entries. Tags have names, slugs, and visual color identifiers for UI display
• Tag Aggregation Pages — Dedicated pages that list all posts sharing a specific tag, with pagination
• Related Post Suggestions — The system recommends related posts based on shared tag overlap
• Pagination — The main blog listing page supports configurable pagination for large content volumes

Author Management

Each blog post is attributed to an author with a complete profile:

• Author Profiles — Biographical information including name, bio, avatar, and social media links
• Author Detail Pages — Automatic aggregation of all posts by a given author
• Collaborative Publishing — Multiple authors can contribute to the same blog

Client-side blog post list example:

import { useQuery } from '@tanstack/react-query'

export function BlogList() {
  const { data } = useQuery({
    queryKey: ['blog-posts'],
    queryFn: () =>
      fetch('/api/blog/posts?page=1&limit=5').then((r) => r.json()) as Promise<
        Array<{
          slug: string
          title: string
          description: string
          tags: Array<{ name: string }>
          readingTime: number
          author: { name: string }
        }>
      >,
  })

  return (
    <div className="space-y-4">
      {data?.map((post) => (
        <article key={post.slug} className="rounded-lg border p-4">
          <h3 className="font-semibold">{post.title}</h3>
          <p className="mt-1 text-sm text-muted-foreground">{post.description}</p>
          <div className="mt-2 flex items-center gap-2 text-xs text-muted-foreground">
            <span>{post.author.name}</span>
            <span>·</span>
            <span>{post.readingTime} min read</span>
            <span>·</span>
            {post.tags.map((t) => (
              <span key={t.name} className="rounded-md bg-muted px-2 py-0.5">{t.name}</span>
            ))}
          </div>
        </article>
      ))}
    </div>
  )
}

Design Philosophy

Technical Content First

The Blog CMS is purpose-built for technical content that includes code, diagrams, and interactive elements. Unlike general-purpose CMS platforms that treat code blocks as second-class formatting, MDX content with Shiki syntax highlighting and Mermaid diagram rendering are first-class citizens. This technical-content-first approach ensures that developers can write documentation with the tools they expect — syntax-highlighted code samples, architecture flowcharts, sequence diagrams — without workarounds or compromises. Unlike WordPress or Contentful — which require plugins for code highlighting and embed-based diagram tools — our blog CMS has Shiki syntax highlighting and Mermaid diagram rendering built directly into the content pipeline with no third-party services or iframe embeds required.

Multi-Language SEO by Design

Multi-language publishing isn't an afterthought — it's built into the content model through sibling post relationships, shared slugs, and locale-prefixed URLs. Each post automatically generates hreflang meta tags that tell search engines about language variants, preventing duplicate content penalties while maximizing multilingual search visibility. The locale-specific URL structure (/en/blog/slug, /zh/blog/slug, /de/blog/slug) provides clear language signals to both users and search crawlers.

Performance Through Caching

MDX compilation — including Shiki syntax highlighting and Mermaid diagram rendering — is computationally expensive. Rather than compiling on every request, the system caches compiled output and invalidates the cache only when a post is updated. This caching-first approach means that blog posts load instantly for readers, even when they contain complex code blocks or diagrams, while content authors still see their edits reflected immediately through cache-invalidation triggers.

Best Practices

SEO-Optimized Content Structure

Structure blog posts with a clear heading hierarchy: use a single H1 for the title (auto-generated), descriptive H2s for sections, and H3s for subsections. This hierarchy improves both reader comprehension and search engine crawling. Always include a compelling meta description for rich snippet display.

Multi-Language Content Strategy

When publishing multi-language content, write each version independently rather than using machine translation. Each version should be culturally appropriate for its target audience. Use the sibling linking system to connect versions.

Image and Media Management

Upload blog images to storage and reference them via public URLs. Optimize images before upload — compress PNGs, use WebP format where possible, and include descriptive alt text for accessibility and SEO.

Content Caching

Content compilation (syntax highlighting, diagram rendering) is computationally expensive. Cached posts serve instantly. Configure cache invalidation to trigger on post updates, ensuring readers always see the latest version.

Frequently Asked Questions

How do I create a new blog post? Navigate to the blog section in the admin dashboard and click "New Post." Fill in the title, content, description, tags, and author information. Set the locale and publish status, then save. For multi-language posts, create sibling versions and link them.

Can I use custom React components in blog posts? Yes. The content format allows embedding custom components directly in blog content. Common use cases include interactive code sandboxes, data tables, and callout boxes.

How does the tag system work? Each post can have multiple tags. Tags are managed from the admin panel and support color coding. The blog listing includes tag filters, and dedicated tag pages aggregate all posts sharing a tag.

How does reading time estimation work? Reading time is calculated based on word count, using average reading speeds for different languages.

Can authors edit their own posts after publishing? Yes. Authors with permissions can edit published posts. Edited posts retain their original slug and publication date.

How are blog posts included in the XML sitemap? Blog posts are automatically included in the XML sitemap with locale-appropriate URLs and hreflang alternate links.

What analytics are available for blog content? Blog post view tracking is available through the analytics system, with per-post view counts, reading time metrics, and engagement data.

Configuration

Blog content is managed through the admin interface. Key administrative routes include:

• Posts — Post listing, creation, editing, and deletion
• Tags — Tag creation, editing, color assignment, and deletion
• Authors — Author profile management (name, bio, avatar, social links)

No additional environment variables are required for basic blog functionality. For image uploads, configure storage as described in the R2 File Management documentation.

Integration Points

The Blog CMS integrates with these platform modules:

• R2 Uploads — Blog post images, cover photos, and media assets are stored and served
• Sitemap System — Blog posts are included in XML sitemaps with hreflang annotations
• SEO Framework — Full Open Graph meta tags, canonical URLs, and hreflang support
• Site Search — Blog content is indexed and accessible through site-wide search
• Analytics — Post view tracking and engagement metrics
• Email Marketing — New post notifications for subscriber engagement