mettu (మెట్లు, /ˈmɛt.t̪u/) is a simple, flexible, high-performance static site generator that combines Python for backend processing (Markdown, YAML frontmatter, Pygments, Jinja2) and Vite for frontend development (Tailwind CSS v4 and DaisyUI v5).
It is built for personal blogs, portfolio sites, and first-class documentation portals with client-side search, callouts, and automatic navigation.
"mettu" is a Telugu word meaning a stair or step. It represents a step towards building your own tools, and conveniently, a step towards publishing your website!
- Hybrid Architecture: Fast Python engine for Markdown parsing, syntax highlighting, and feed generation + Vite for Tailwind CSS v4, DaisyUI v5, and HMR.
- High Performance: In-memory and disk caching for Markdown ASTs, dependency hash tracking to skip redundant
pip installchecks, and sub-300ms builds. - First-Class Documentation Sites:
- Dedicated 3-column documentation layout with sticky on-page Table of Contents.
- Automatic hierarchical sidebar tree with section grouping and
order:sorting. - Sequential Previous / Next pagination links and breadcrumb trails.
- Built-in
⌘K/Ctrl+Kclient-side instant search modal (/search-index.json). - GitHub-style callouts (
> [!NOTE],> [!TIP],> [!IMPORTANT],> [!WARNING],> [!CAUTION]). - One-click Copy button on all code blocks.
- Zero-Boilerplate Content Authoring:
- Optional frontmatter: automatic title inference from
# Headingor filename stem. - Directory-based default layout inference (
posts/→post,docs/→docs, others →page). - Automated reading time calculation and plain-text excerpt generation.
- Custom
permalinkoverrides for fine-grained URL routing. - Universal tagging across all content pages with dedicated tag index pages.
- Optional frontmatter: automatic title inference from
- Theming & Design:
- DaisyUI v5 presets and custom CSS color definitions.
- Built-in navbar theme switcher with pre-paint
localStoragepersistence. - Pygments code syntax highlighting with auto-generated stylesheet.
- Responsive Image Optimization:
- Automatic WebP, AVIF, and JPEG generation at multiple breakpoints via Sharp.
- Automatic markup rewrite into responsive
<picture>elements withsrcset. - Optional remote upload and sync with S3/Backblaze B2 buckets.
- Web Feeds & SEO:
- Automatic Atom/RSS feed generation with human-readable styling (
pretty-feed-v3.xsl). - XML sitemap (
/sitemap.xml) generation with valid<loc>and<lastmod>timestamps. - OpenGraph and meta description tags.
- Automatic Atom/RSS feed generation with human-readable styling (
- Developer Experience (DX):
- Scaffolding CLI:
npm run new -- "My New Post". - Site health & link validator:
npm run check. - Zero-dependency unit test suite:
npm test.
- Scaffolding CLI:
- Python: 3.9+
- Node.js: 18+ and npm
- Vite, Tailwind CSS v4, and DaisyUI v5 (managed via npm)
-
Clone the repository:
git clone https://github.com/Andy34G7/mettu.git cd mettu -
Install dependencies:
npm install
Note: Python dependencies (
Markdown,Jinja2,PyYAML,Pygments,python-dotenv) are automatically installed into a local.venvon first run. -
Start the development server:
npm run dev
Open
http://localhost:5173in your browser. Changes to Markdown files, templates, or styles update live via Vite's HMR. -
Build for production:
npm run build
The fully bundled, self-contained static site will be written to
./dist.
| Command | Description |
|---|---|
npm run dev |
Starts the Vite dev server with live reloading and Python build watcher. |
npm run build |
Compiles pages, feeds, sitemaps, search indices, and assets into ./dist. |
npm run preview |
Serves the production ./dist directory locally to test before deployment. |
npm run new -- "<Title>" |
Scaffolds a new post, doc, or page with starter frontmatter. |
npm run check |
Validates configuration, frontmatter syntax, layouts, URLs, and image links. |
npm test |
Runs the automated Python unit test suite (tests/test_ssg.py). |
npm run clean |
Cleans temporary build artifacts and caches. |
Quickly scaffold new content with safe URL slugs and boilerplate frontmatter:
# Scaffold a blog post in content/posts/my-new-post.md
npm run new -- "My New Post"
# Scaffold a documentation page in content/docs/api-guide.md
npm run new -- --kind doc "API Guide"
# Or prefix with docs/
npm run new -- "docs/api-guide"
# Scaffold a general standalone page in content/about.md
npm run new -- --kind page "About"Configure site-wide settings in config.yaml:
site_name: "My Site"
author: "Your Name"
base_url: "https://example.com"
base_path: "" # Optional path prefix, e.g. "/subsite"
runtime:
python_executable: "python3" # Optional; defaults to .venv or system python
theme:
default: "cupcake" # Active theme
include: # Themes included in the switcher
- "cupcake"
- "dracula"
custom:
mytheme:
primary: "#570df8"
secondary: "#f000b8"
accent: "#37cdbe"
fonts:
imports:
- "https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&family=Space+Grotesk:wght@500;700&display=swap"
families:
body: "'Inter', sans-serif"
heading: "'Space Grotesk', sans-serif"
mono: "'JetBrains Mono', monospace"
syntax:
pygments_theme: "dracula" # Controls syntax highlighting theme
markdown:
default_layout: "page"
default_layouts:
posts: "post"
docs: "docs"
extensions:
- fenced_code
- codehilite
- footnotes
- tables
- attr_list
- sane_lists
- md_in_html
- nl2br
- toc:
permalink: true
images:
formats:
- webp
- jpg
navigation:
- name: "Home"
url: "/"
- name: "Blog"
url: "/blog/"
- name: "Docs"
url: "/docs/"
feeds:
- filename: "feed.xml"
layouts: ["post"]
title: "My Site Feed"
subtitle: "Thoughts and findings"
content: trueCreate Markdown (.md) files in the content/ directory.
All frontmatter is optional. Sensible defaults are inferred whenever fields are omitted:
---
title: "Understanding Architecture" # Inferred from first # Heading or filename if omitted
layout: "post" # Inferred by folder: posts/ -> post, docs/ -> docs, else -> page
date: "2026-11-10" # Publication date (YYYY-MM-DD)
tags: # List or single string; normalized safely to URL slugs
- "architecture"
- "web-dev"
permalink: "/articles/architecture/" # Optional custom route override
show_toc: true # Displays collapsible on-page Table of Contents
description: "A deep dive into system..." # Inferred from the first paragraph if omitted
draft: false # Set to true to exclude from builds and feeds
---
Content goes here...Write GitHub-style admonitions inside blockquotes. They automatically transform into DaisyUI alert elements:
> [!NOTE]
> Useful background context or general information.
> [!TIP]
> Pro-tips or performance suggestions.
> [!IMPORTANT]
> Key requirements or crucial information.
> [!WARNING]
> Warnings and potential breaking changes.
> [!CAUTION]
> High-risk actions that could cause data loss or security issues.mettu provides complete documentation site generation out of the box. Any file placed under content/docs/ automatically receives the docs layout.
Organize documentation files into folders or assign sections via frontmatter:
content/docs/
├── index.md # Overview (order: 1)
├── getting-started.md # Overview (order: 2)
└── guide/
├── configuration.md # Section: Guide (order: 3)
└── authoring.md # Section: Guide (order: 4)
Or specify in frontmatter:
---
title: "Configuration"
section: "Advanced Guide"
order: 3
---
7E3F
- Sidebar Navigation Tree: Automatically groups pages by
section(with"Overview"first), ordered byorder:and title. - Previous & Next Links: Sequential bottom pagination linking the reader through the documentation flow.
- Breadcrumbs: Automatically generated breadcrumb hierarchy.
- On-Page TOC: Sticky right-hand navigation for
h2andh3headings. - Instant Search (
⌘K/Ctrl+K): Fast client-side modal filtering through titles, sections, headings, tags, and excerpts. - Code Copy: Every code block features an automatic one-click Copy button.
- Place source images into
assets/images/. - When building or developing, Sharp automatically resizes images to responsive widths (e.g. 640px, 1280px, 1920px) and converts them into modern formats (
.webp,.jpg). - Local
<img src="/assets/images/example.png">references are automatically converted into<picture>elements with responsivesrcsetdefinitions.
To host processed images on an S3-compatible bucket:
- Copy the environment template:
cp .env.example .env
- Configure credentials in
.env:S3_BUCKET="my-bucket" S3_REGION="us-east-1" S3_ENDPOINT="https://s3.us-east-1.amazonaws.com" S3_ACCESS_KEY="your-access-key" S3_SECRET_KEY="your-secret-key" S3_PUBLIC_URL="https://cdn.example.com"
- Atom/RSS Feeds: Feeds specified in
config.yamlare generated with RFC-compliant timestamps, full post content (optional), and styled viapublic/pretty-feed-v3.xslfor direct browser viewing. - Excluding from Feeds: Add
feed: falseto any page's frontmatter. - Sitemap:
/sitemap.xmlis automatically generated with valid URLs and<lastmod>timestamps derived from post dates or file modification times.
Run the built-in validator to inspect site integrity before committing or deploying:
npm run checkValidates:
- Syntax and required keys in
config.yaml. - Frontmatter validity across all Markdown files.
- Existence and syntax of referenced layout templates in
templates/. - Duplicate URL or permalink collisions.
- Existence of local images referenced in Markdown or frontmatter.
This project is licensed under the ISC License.