Moosey CMS 🫎

A lightweight, drop-in Markdown CMS for FastAPI.

Moosey CMS transforms your FastAPI application into a content-driven website without the need for a database. It bridges the gap between static site generators and dynamic web servers, offering hot-reloading, intelligent caching, SEO management, and a powerful templating hierarchy.

Check out the /example for templating and content samples used to generate the images above.

🚀 Features

• No Database Required: Content is managed via Markdown files with YAML Frontmatter.
• Intelligent Routing: URL paths automatically map to your content directory structure.
• Smart Templating: "Waterfall" inheritance logic (Singular/Plural) to automatically find the best layout for every page.
• Hot Reloading: Instant browser refresh when Content or Templates change (Development mode only).
• High Performance: Built-in caching (TTL-based) that auto-clears on file changes.
• SEO Ready: Automatic OpenGraph, Twitter Cards, JSON-LD, and Meta tags generation.
• Site Management: Built-in sitemap.xml, robots.txt, RSS feeds, and a reusable content index.
• Rich Markdown: Supports tables, emojis, task lists, and syntax highlighting out of the box.
• Jinja2 Power: Use Jinja2 logic directly inside your Markdown files (Securely Sandboxed).
• Admin API: Built-in REST API for programmatic content management (create, update, delete files and directories).
• Guided Frontmatter: Add supported metadata in the editor and extend its registry through an automatically discovered project override.

🛠️ Features That Replace Paid Services

📦 Installation

Using UV (Recommended)

uv add moosey-cms

Using Pip

pip install moosey-cms

💻 CLI

moosey-cms ships with a CLI for scaffolding sites, installing admin templates, and running servers.

# Scaffold a new site from the example app
moosey-cms init ./my-site

# Initialize or update config for existing project
moosey-cms config

# Install admin templates into your project
moosey-cms admin --templates ./templates

# Run dev server (hot-reload)
moosey-cms dev

# Run production server
moosey-cms prod

See CLI Reference for all commands and options.

🧪 Running Tests

# Install dev dependencies (pip)
pip install -e ".[dev]"

# Install dev dependencies (uv)
uv add moosey-cms --dev
uv sync

# Run all tests
pytest

# Run a specific test file
pytest tests/test_schemas.py

# Run a specific test class
pytest tests/test_schemas.py::TestSchemaArticle

# Run with verbose output
pytest -v tests/test_schemas.py

⚡ Quick Start

Integrate Moosey CMS into your existing FastAPI app in just a few lines.

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from pathlib import Path
from moosey_cms import init_cms

app = FastAPI()

# 1. Define your paths
BASE_DIR = Path(__file__).resolve().parent
CONTENT_DIR = BASE_DIR / "content"
TEMPLATES_DIR = BASE_DIR / "templates"

# 2. Mount static files (Optional, but recommended for CSS/Images)
app.mount("/static", StaticFiles(directory="static"), name="static")

# 3. Initialize the CMS
init_cms(
    app,
    host="localhost",
    port=8000,
    dirs={
        "content": CONTENT_DIR, 
        "templates": TEMPLATES_DIR
    },
    mode="development",  # Enables hot-reloading
    site_data={
        "name": "My Awesome Site",
        "description": "A site built with Moosey CMS",
        "author": "Jane Doe",
        "keywords": ["fastapi", "cms", "python"],
        "open_graph": {
             "og_image": "/static/cover.jpg"
        },
        "social": {
            "twitter": "https://x.com/myhandle",
            "github": "https://github.com/myhandle"
        },
        "web": {
            "site_url": "https://example.com",
            "feed": {
                "collection": "/blog",
                "title": "My Awesome Site Feed"
            }
        }
    },
    reload_delay=2.5 # Triggers hot-reload after this duration
)

Admin Setup

Moosey CMS includes a built-in admin UI for editing content directly in the browser. The admin UI features a tabbed editor with WYSIWYG (TUI Editor) and metadata editing (Guifier).

1. Enable admin in init_cms():

init_cms(
    app,
    # ... other params ...
    admin={
        "prefix": "admin/content",  # Route prefix for admin UI
        "templates": "admin"         # Subdirectory in templates/ for admin templates
    }
)

2. Install admin templates:

# Install admin templates into your project
moosey-cms admin --templates ./templates

This creates templates/admin/ with the default editor and base layout templates.

3. Template structure:

templates/
├── admin/
│   ├── base.html      # Admin layout (sidebar, navigation)
│   ├── editor.html    # Tabbed file editor (main UI)
│   └── admin.js       # Shared admin utilities
├── layout/
│   └── base.html      # Public site layout
└── ...

4. Static files (required for file uploads):

from fastapi.staticfiles import StaticFiles

# Mount static files directory
app.mount("/static", StaticFiles(directory="static"), name="static")

The admin UI allows:

• Browsing and editing Markdown files with frontmatter
• Creating new files and directories
• Uploading images and other static assets
• Live preview of content changes
• Metadata editing via JSON schema form

See Admin Documentation for full details.

⚙️ Configuration File

Moosey CMS uses a YAML configuration file (.moosey-cms.yaml) in your project root. This file is auto-generated when you run moosey-cms init.

Default config structure:

server:
  host: "0.0.0.0"
  port: 8000
  reload_delay: 0.25

site:
  name: "My Site"
  admin:
    prefix: "admin/content"
    templates: "admin"

crypto:
  key: "your-generated-key-here"

cache:
  backend: "memory"       # "memory" or "redis"
  ttl: 2592000            # 30 days in seconds
  maxsize: 10000          # max entries (memory only)
  redis_url: "redis://localhost:6379/0"  # only used when backend="redis"

How it works:

• init_cms() automatically loads .moosey-cms.yaml from your project root
• Python arguments passed to init_cms() override YAML values
• The crypto.key is required - the CMS will not start without it

Cache backends:

• memory (default): In-process LRU cache. Fastest, resets on restart.
• redis: Shared cache across workers/processes. Requires a running Redis server. The Redis client is auto-created from redis_url.

Advanced configuration (uncomment in your config file):

# Image CDN configuration
# image_cdn:
#   provider: cloudflare  # cloudflare, cloudinary, imgix, imagekit
#   base_url: "https://cdn.example.com"

# Image processing defaults
# image_processing:
#   quality: 85
#   format: webp

# HTML sanitize settings
# sanitize:
#   allowed_tags: ["p", "a", "img", "h1", "h2", "h3"]
#   allowed_attributes: ["href", "src", "alt"]

Important: Do not change the crypto.key after initialization. Assets encrypted with this key cannot be decrypted with a different key.

📂 Directory Structure

Moosey CMS relies on a convention-over-configuration file structure.

.
├── main.py
├── content/               <-- Your Markdown Files
│   ├── index.md           <-- Homepage (/)
│   ├── about.md           <-- About Page (/about)
│   └── blog/
│       ├── index.md       <-- Blog Listing (/blog)
│       ├── post-1.md      <-- Blog Post (/blog/post-1)
│       └── post-2.md
└── templates/ 
    ├── layout          
        ├── base.html          <-- Base layout
    ├── index.html         <-- Home Page layout
    ├── page.html          <-- Default fallback
    ├── blog.html          <-- Layout for /blog (Listing)
    └── post.html          <-- Layout for /blog/post-1 (Single Item)

🎨 Templating Logic (The Waterfall)

When a user visits a URL, Moosey CMS searches for templates in a specific cascading order. This allows you to set global defaults while retaining the ability to customize specific pages or sections.

Example Scenario: A user visits /posts/post-1.

Directory Structure:

.
├── content/
│   └── posts/
│       ├── index.md        <-- Required for the '/posts' listing page to work
│       ├── post-1.md       <-- The article being requested
│       └── post-2.md
└── templates/
    ├── posts/
    │   └── post-1.html     <-- 1. Specific Override
    ├── post.html           <-- 2. Singular (Item) Layout
    ├── posts.html          <-- 3. Plural (Section) Layout
    └── page.html           <-- 4. Global Fallback

Resolution Order:

1. Frontmatter Override: If post-1.md contains template: special.html, that template is used immediately.
2. Exact Match: templates/posts/post-1.html.
3. Singular Parent: templates/post.html (Perfect for generic blog posts).
4. Plural Parent: templates/posts.html (Perfect for section indexes).
5. Fallback: templates/page.html.

📝 Frontmatter Configuration

You can control routing, visibility, and layout directly from the Markdown file YAML frontmatter.

Basic Metadata

title: My Amazing Post
date: 2024-01-01
description: A short summary for SEO.

Organization & Navigation

Advanced Routing

Publishing, SEO & Feeds

Example:

---
title: API Documentation
nav_title: API Docs
order: 1
group: "Developer Tools"
external_link: "https://api.mysite.com"
---

🕸️ Built-in Website Routes

Moosey automatically registers everyday site-management routes before the content catch-all route:

Configure them in site_data.web:

site_data = {
    "name": "My Site",
    "web": {
        "site_url": "https://example.com",
        "sitemap": {
            "default_changefreq": "weekly",
            "default_priority": "0.5",
        },
        "robots": {
            "production": {"allow": ["/"], "disallow": []},
            "staging": {"disallow": ["/"]},
            "testing": {"disallow": ["/"]},
        },
        "feed": {
            "collection": "/blog",
            "limit": 50,
            "title": "My Site Blog",
            "description": "Latest articles from My Site",
        },
    },
}

Set any feature to false to disable it, for example "feed": false.

🧩 Custom Filters & Logic

Moosey CMS comes packed with a comprehensive library of Jinja2 filters to help you format your data effortlessly.

Date & Time

Currency & Numbers

Geography & Locale

Text Formatting

Utilities

🛡 Sanitize

🔧 SEO & Data

🖼 Images

Enabling on-disk processing requires passing "static": <path> in dirs to init_cms. Full reference: docs/images.md. Face detection via focus=face requires moosey-cms[faces] (~30MB).

Path convention: image source paths passed to image should omit the /static/ prefix. Since the static directory is already configured in dirs, use paths relative to it - e.g. /images/team/martin.jpg instead of /static/images/team/martin.jpg. The filter will resolve these against the configured static_dir automatically.

🔗 Content Helpers

More On Filters and how to use some interesting ones such as stripping comments.

⚙️ Configuration Reference

The init_cms function accepts the following parameters:

🛡️ Security & Mitigation

Moosey CMS takes security seriously. We have implemented several layers of protection to ensure your site remains safe:

1. Path Traversal Protection: All URL requests are securely resolved against the content root using strict pathlib checks. It is impossible to access files outside the content directory (e.g., ../../etc/passwd).
2. SSTI Sandbox: While we allow Jinja2 logic inside Markdown files, this is executed in a Sandboxed Environment. Dangerous attributes (like __class__, __subclasses__) are stripped, preventing Remote Code Execution (RCE) attacks.
3. DoS Prevention: The Hot-Reload middleware includes size checks to prevent memory exhaustion attacks from large file uploads/downloads.

🐛 Bug Reporting

Security is an ongoing process. If you discover a vulnerability, bug, or potential risk, please open an issue on our GitHub repository immediately. We appreciate community feedback to keep Moosey secure for everyone.

Documentation

Get Started →

Gratitude

This project is inspired by fastapi-blog by Daniel. Initially, I wanted to use fastapi-blog and it worked really well till I needed features like hot-reloading.

License

MIT License. Copyright (c) 2026 Anthony Mugendi.