Marmite Documentation

Marmite Documentation

by rochacbruno
📋 Table of Contents

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

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!

Related "docs" content:

Comments