# 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
- [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
- [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
- [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

### 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
- [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

### 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
