# Marmite Documentation

**Mar**kdown **M**akes S**ite**s

> 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

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

<small> or check [installation guide](https://marmite.blog/installation.html) for more install options </small>

### Start blogging

```console
$ 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

- [Why to use Marmite?](https://marmite.blog/why-to-use-marmite.html): Learn about Marmite's features and design philosophy
- [Getting Started](https://marmite.blog/getting-started.html): Quick start guide to create your first blog with Marmite
- [Python Installation](https://marmite.blog/python-installation-with-pip.html): Installing marmite via pip or uvx
- [Command Line Interface](https://marmite.blog/marmite-command-line-interface.html): Complete reference for all CLI commands and options

### Content Creation

- [Content Types and Taxonomy](https://marmite.blog/content-types.html): Understanding posts, pages, tags, and streams
- [Markdown Format](https://marmite.blog/markdown-format.html): Supported markdown syntax and extensions
- [Wikilinks Guide](https://marmite.blog/wikilinks-demo-how-to-guide.html): Obsidian-style wikilinks with slug resolution
- [Using Markdown to Customize Layout](https://marmite.blog/using-markdown-to-customize-layout.html): Special markdown files for layout customization
- [Streams Guide](https://marmite.blog/streams-guide.html): Organizing content with streams
- [Filename-Based Streams](https://marmite.blog/filename-based-streams-organize-content-with-file-naming.html): Automatic stream detection from filename prefixes
- [Language Streams (i18n)](https://marmite.blog/language-streams.html): Multilingual content with auto-detected languages, translation linking, per-language streams and RSS, hreflang SEO tags
- [Creating Translated Content from CLI](https://marmite.blog/creating-translated-content-from-cli.html): Create translations via `--new "Title" --lang pt --translates slug`, with JSON output and automatic subfolder placement
- [Series Feature](https://marmite.blog/organizing-content-with-series-in-marmite.html): Creating ordered content series
- [Draft Posts Guide](https://marmite.blog/how-to-use-draft-posts-in-marmite.html): Working with draft content
- [Folder-Level Frontmatter Defaults](https://marmite.blog/folder-level-frontmatter-defaults.html): Inherit shared frontmatter (stream, tags, date, etc.) from a folder-level frontmatter.yaml file at any nesting depth, with layered inheritance and support for nested translation groups

### Configuration

- [Configuration Reference](https://marmite.blog/configuration-reference.html): Complete reference for all marmite.yaml options
- [Configurable Markdown Parser](https://marmite.blog/configurable-markdown-parser-options.html): Customizing markdown processing
- [IndieWeb Compliance](https://marmite.blog/indieweb-compliance.html): Making your site IndieWeb compatible

### Templates and Theming

- [Customizing Templates](https://marmite.blog/customizing-templates.html): How to customize templates and create themes
- [Template Reference](https://marmite.blog/template-reference.html): Tera template language reference
- [Themes Feature](https://marmite.blog/introducing-themes-in-marmite.html): Using and creating custom themes
- [Remote Themes](https://marmite.blog/remote-theme-download.html): Installing themes from remote repositories

### Features

- [Image Optimization and Resizing](https://marmite.blog/image-optimization-and-resizing.html): Automatic image resizing with parallel processing and incremental builds
- [Image Gallery](https://marmite.blog/image-gallery.html): Create and display image galleries with automatic thumbnail generation
- [Shortcodes Guide](https://marmite.blog/shortcodes-guide.html): Using shortcodes to add dynamic content to posts and pages
- [Shortcodes Demo](https://marmite.blog/shortcodes-demo.html): Examples of all available shortcodes including YouTube, Spotify, cards, and content listings
- [Show URLs Dry Run Command](https://marmite.blog/show-urls-dry-run-command.html): Preview all site URLs without building - perfect for verification and planning
- [Automatic Sitemap Generation](https://marmite.blog/automatic-sitemap-generation.html): Built-in sitemap.xml generation for better SEO with configurable options
- [File Mapping Feature](https://marmite.blog/file-mapping-feature.html): Copy arbitrary files during site generation using configurable mappings
- [Automatic Image Download](https://marmite.blog/automatic-image-download.html): Auto-generating banner images
- [Media Organization](https://marmite.blog/media-organization-with-slug-based-subfolders.html): Slug-based media subfolders, @/ shorthand, and content subfolder media (content/{slug}/media/) with shared inheritance for translations
- [Markdown Source Publishing](https://marmite.blog/markdown-source-publishing.html): Publishing source files alongside HTML
- [Link Checker with Lychee](https://marmite.blog/how-to-run-a-link-checker-on-your-marmite-website.html): Checking for broken links
- [Enabling Comments](https://marmite.blog/enabling-comments.html): Adding comment systems to your blog
- [Draft Posts Guide](https://marmite.blog/how-to-use-draft-posts-in-marmite.html): Working with draft content and publishing workflow
- [Workspace Multi-Site](https://marmite.blog/workspace-multi-site-support.html): Build and manage multiple sites from a single workspace with cross-site references, shared config, and unified builds
- [AT Protocol standard.site](https://marmite.blog/atproto-standard-site.html): Complete guide to publishing your Marmite blog posts to the decentralized AT Protocol
- [Redirect Aliases](https://marmite.blog/redirect-aliases.html): Generate redirect pages for old URLs when content slugs change
- [Internal Link Validation](https://marmite.blog/internal-link-validation.html): Build-time validation of internal links with warning and strict failure modes
- [Marmite Playground](https://marmite.blog/marmite-playground.html): Try marmite in the browser with a live editor and real-time preview
- [Marmite Editor](https://marmite.blog/marmite-editor.html): Three-panel content editor with CodeMirror 6, live preview, metadata sidebar, auto-save, autocomplete, raw file editing, and config dialog during --serve mode
- [Marmite Toolbar](https://marmite.blog/marmite-toolbar.html): Floating dev toolbar for creating, editing, moving, cloning, and deleting content from the browser during --serve mode
- [Content Management API](https://marmite.blog/content-management-api.html): REST API under /__marmite__/ for programmatic content and config management during --serve mode

### Deployment

- [Hosting](https://marmite.blog/hosting.html): Deploying to GitHub Pages, Netlify, and other platforms

### Community

- [Contributors](https://marmite.blog/contributors.html): List of project contributors
- [Showcase](https://marmite.blog/showcase.html): Sites built with Marmite

## Tutorials

### Python Tutorial Series

- [Python Tutorial Part 1](https://marmite.blog/tutorial-python-tutorial-part-1-getting-started.html): Introduction to Python basics
- [Python Tutorial Part 2](https://marmite.blog/tutorial-python-tutorial-part-2-data-types-and-variables.html): Control flow and functions
- [Python Tutorial Part 3](https://marmite.blog/tutorial-python-tutorial-part-3-collections-and-data-structures.html): Data structures and modules

## Release Notes

- [Marmite 0.2.6 Release Notes](https://marmite.blog/marmite-0-2-6-release-notes.html): Latest features and improvements

## Optional

- [About](https://marmite.blog/about.html): About the project
- [Pagination](https://marmite.blog/pagination.html): How pagination works
- [Content without metadata](https://marmite.blog/no-metadata.html): Example of content without frontmatter

## 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](https://agentskills.io) 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:

```console
$ 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.):

```console
$ marmite --skill-install
```

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

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

```console
$ 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:

```console
$ 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.