Marmite Documentation

Friday, 31 July 2026 - ⧖ 11.0 min
🗒️

Markdown Makes Sites

Marmite is a fast, minimal static site generator written in Rust that converts Markdown files into HTML websites. It's designed for simplicity and includes features like live reloading, RSS feeds, and a built-in development server.

Marmite is the easiest static site generator optimized for blogs. It doesn't require specific folder structure or complex configuration - the goal is that a blog can be generated simply by running Marmite on a folder with Markdown and media files. Written in Rust, it provides very fast builds with everything included in a single binary.

Quick Start

Install

$ curl -sS https://marmite.blog/install.sh | sh

or check installation guide for more install options

Start blogging

$ marmite myblog --init-site \
    --name Mysite \
    --tagline "My Articles and Notes" \
    --colorscheme nord \
    --toc true \
    --enable-search true

$ marmite myblog --new "My First Blog Post" -t "new,post"

$ marmite myblog --serve

Documentation

Getting Started

Content Creation

Configuration

Templates and Theming

Features

Deployment

  • Hosting: Deploying to GitHub Pages, Netlify, and other platforms

Community

Tutorials

Python Tutorial Series

Release Notes

Optional

Key Features

  • Image Optimization: Automatic image resizing with configurable max widths, parallel processing using all CPU cores, and incremental builds that skip unchanged images
  • Shortcodes: Insert dynamic content using simple markers like <!-- .youtube id=VIDEO_ID -->, <!-- .spotify url="album/ID" -->, or <!-- .card slug=content-slug -->
  • Enhanced Tera Functions: New template functions including get_data_by_slug() for content lookup and enhanced group() function with sorting and limiting
  • Content Cards: Display linked previews of any content (posts, pages, tags, authors, series) with automatic data resolution
  • External URL Support: Card shortcodes automatically detect and handle external URLs with proper targeting
  • Template URL Functions: All shortcode templates use the url_for() function for proper URL generation
  • URL Preview (Dry Run): Use --show-urls command to preview all site URLs without building, perfect for verification and planning
  • Automatic Sitemap Generation: Built-in sitemap.xml generation for better SEO, enabled by default with support for absolute and relative URLs
  • File Mapping: Copy arbitrary files during site generation with flexible source and destination patterns, supporting single files, directories, and glob patterns
  • Themes: Complete theme system with remote theme installation and customization
  • Series Support: Group related content in chronological order with automatic navigation
  • Enhanced Streams: Filename-based stream detection with configurable display names
  • Configurable Markdown Parser: Full control over CommonMark extensions and rendering options
  • IndieWeb Compliance: Built-in microformats and semantic HTML for better web interoperability
  • Navigation Links: Automatic next/previous post navigation with stream-aware linking
  • Draft Content Management: Special handling of draft posts with filtering from feeds and search
  • Related Content: Configurable related content and backlinks between posts
  • Markdown Alerts: Support for GitHub-style callouts and alert boxes in markdown
  • AT Protocol Publishing: Native support for publishing blog posts to standard.site and the decentralized AT Protocol with automatic well-known verification
  • Redirect Aliases: Frontmatter aliases field generates redirect pages at old URLs when content slugs change, with meta refresh, canonical links, and conflict detection
  • Internal Link Validation: Build-time checking of internal links with configurable warning or strict failure mode via check_internal_links and strict_internal_links options. Media file links (images, PDFs, etc.) can also be validated with check_media_links: true
  • Native Mermaid Rendering: Mermaid diagrams are rendered to inline SVG at build time by default (native_mermaid_render: true). No client-side JavaScript or CDN dependency. Set native_mermaid_render: false to use client-side MermaidJS rendering instead. The renderer can be customized with mermaid_config at three cascading levels (marmite.yaml, frontmatter.yaml, .md frontmatter) with deep merge. Accepts the same keys as the mermaid-rs-renderer JSON config format (camelCase): theme (dark, forest, neutral, modern, default), themeVariables (colors, fonts), flowchart (nodeSpacing, rankSpacing), preferredAspectRatio, and more.
  • Language Streams (i18n): Multilingual content support via language streams. Languages are auto-detected from content - no configuration required. Set language: xx in frontmatter or use subfolder naming conventions (content/hello/pt-ola.md). Optionally configure languages in marmite.yaml with display_name for pretty labels. Link translations via subfolder grouping, translates: pointer (each translation points to the original slug, marmite builds bidirectional links), or translations: list. Each language gets its own stream page and RSS feed. Translation links and hreflang SEO tags are added automatically. Flat HTML output preserved. Create translations from the CLI with --new "Title" --lang pt --translates slug. A languages.html group page lists all content organized by language (always generated, even on monolingual sites). The languages_title config option controls the page heading. The language_display_name Tera function and group(kind="language") are available for custom templates.
  • Smart Content Creation: The --new CLI command auto-detects posts/ and pages/ subdirectories in structured projects and places content there automatically. Posts go to posts/, pages (with -p) go to pages/. Use -d to override. Flat projects and content-folder projects without these subdirectories are unaffected.
  • Workspace Multi-Site: Build multiple independent sites from a single workspace directory. A marmite-workspace.yaml defines sites, shared defaults, and cross-site reference rules. The default site renders at the root, others in subdirectories. Cross-site links use site::path syntax (e.g., photos::gallery.html becomes /photos/gallery.html). Config inheritance lets workspace defaults flow to all sites with per-site overrides. Watch mode and live reload cover all sites. --show-urls and --shortcodes aggregate across sites. --new --site name creates content in a specific site.
  • Development Toolbar: A floating sidebar panel injected during --serve mode. Provides tabs for viewing content metadata, editing frontmatter with autocomplete, creating/cloning/moving/deleting content, managing menu and layout, editing site config, and viewing site stats. Toolbar state persists in localStorage. A 404 "Create it!" button lets you create missing pages with one click.
  • Content Management API: REST API under /__marmite__/ available during --serve. Endpoints: POST /content (create), PATCH /content/{slug} (update frontmatter), POST /content/{slug}/clone (full copy), POST /content/{slug}/move (rename/relocate), DELETE /content/{slug} (remove), POST /config (create), PATCH /config (update), GET /data (aggregated tags, streams, series, authors, slugs, config, build stats). All responses are JSON. Per-content metadata available at /{slug}.metadata.json.

Agents

Marmite ships with an embedded agent skill following the Agent Skills open format. AI coding agents (Claude Code, Codex, Gemini CLI, Cursor, and others) can use this skill to build, configure, and manage marmite sites.

Viewing the Skill

Print the embedded skill document to stdout:

$ marmite --skill

This outputs the full SKILL.md with workflows for project setup, content authoring, configuration, templates, themes, shortcodes, and deployment.

Installing the Skill

Install the skill into a project so agents discover it automatically. No input folder argument is needed - the skill is installed in the current directory by default.

For agents that follow the standard agent-skills pattern (Codex, Gemini CLI, Cursor, etc.):

$ marmite --skill-install

This creates .agents/skills/marmite/ with the SKILL.md and all reference files.

For Claude Code, which uses .claude/skills/ instead:

$ marmite --skill-install-claude

This creates .claude/skills/marmite/ with the same files.

Both flags can be combined to install for all agents at once:

$ marmite --skill-install --skill-install-claude

The installed structure:

.agents/skills/marmite/                     # Standard agent-skills pattern
  SKILL.md                                  # Main skill document
  references/
    cli-reference.md                        # All CLI flags and options
    installation.md                         # Installation methods
    config-reference.md                     # Complete marmite.yaml reference
    frontmatter.md                          # Content frontmatter fields
    content-organization.md                 # Directory structure and taxonomy
    markdown-format.md                      # Markdown syntax and extensions
    tera-templates.md                       # Template system and variables
    shortcodes.md                           # Shortcode creation and usage
    deployment-guide.md                     # Hosting and deployment guides
    comment-system.md                       # Comment system integration

.claude/skills/marmite/                     # Claude Code
  SKILL.md                                  # Same files as above
  references/                               # Same references

How Agents Use It

Agents that support the agent-skills pattern load skills in three stages:

  1. Discovery - the agent reads the skill name and description from SKILL.md frontmatter
  2. Activation - when the task matches (e.g., "create a blog with marmite"), the agent reads the full SKILL.md
  3. Execution - the agent follows the workflows and loads reference files as needed for detailed information

Example Agent Interactions

With the skill installed, an agent can handle requests like:

  • "Create a new marmite blog about cooking with search enabled and the dracula colorscheme"
  • "Add a Python tutorial series with three parts"
  • "Set up GitHub Pages deployment for this site"
  • "Create a custom shortcode for embedding recipe cards"
  • "Add Giscus comments to the blog"
  • "Customize the homepage with a hero section and sidebar"
  • "Create a new theme based on the default one"

The skill provides the agent with the exact commands, configuration fields, frontmatter syntax, and template variables needed to complete each task correctly.

Please consider giving a ☆ on Marmite Github repository, that helps a lot!

Comments