Minuto

A minimal static site generator for markdown content with Alpine.js and Tailwind support.

Convention over configuration. Just create content and it works.

Installation

npm install minuto

Or use directly with npx:

npx minuto build

Quick Start

Option 1: Start with examples

# Create new project
mkdir my-site && cd my-site
npm init -y
npm install minuto

# Initialize with example content
npx minuto init

# Install dependencies and start
npm install
npm run dev

Option 2: Start from scratch

# Install
npm install minuto

# Create your content structure
mkdir -p content templates static

# Start development server (watches for changes)
npx minuto dev

# Build for production
npx minuto build

# Serve built site
npx minuto serve

Commands

• minuto init [directory] [--template <type>] - Initialize a new project with example content
  • Templates: default, blog, portfolio, docs
• minuto build - Build the static site
• minuto serve - Serve the built site locally (http://localhost:3000)
• minuto dev - Watch for changes and rebuild automatically + serve

Templates

Minuto comes with several starter templates:

Default Template

A clean, minimal template perfect for simple websites.

npx minuto init my-site
# or
npx minuto init my-site --template default

Blog Template

Optimized for blogging with post layouts and beautiful typography.

npx minuto init my-blog --template blog

Portfolio Template

Showcase your projects with a modern, dark-themed portfolio.

npx minuto init my-portfolio --template portfolio

Documentation Template

Perfect for documentation sites with sidebar navigation.

npx minuto init my-docs --template docs

Directory Structure

.
├── content/          # Your markdown files
│   └── index.md
├── data/             # Optional JSON/YAML data files exposed as site.data
├── collections/      # Optional collection manifests for data-driven pages
├── templates/        # Handlebars templates
│   ├── default.hbs
│   └── partials/    # Optional partials
├── styles/          # Tailwind CSS source (optional)
│   └── main.css
├── static/          # CSS, JS, images (copied as-is)
│   └── script.js
└── build/           # Generated site (created on build)

Writing Content

Create .md files in the content/ directory with frontmatter:

---
title: My Post Title
date: 2025-10-26
template: default
---

# Your content here

Write your post in **Markdown**!

Frontmatter Options

• title: Page title
• date: Publication date
• template: Template name (without .hbs extension, defaults to "default")
• Any custom fields you want to use in your templates

Templates

Create .hbs files in the templates/ directory. Use {{{content}}} (triple braces) for the rendered markdown HTML.

Available variables:

• {{{content}}} - Rendered markdown HTML
• {{title}} - From frontmatter
• {{date}} - From frontmatter
• {{site.data}} - Data loaded from the optional data/ directory
• Any custom frontmatter fields

Partials

Create reusable template parts in templates/partials/:

<!-- templates/partials/header.hbs -->
<header>
  <nav>...</nav>
</header>

Use in templates:

{{> header}}

Static Assets

Put your CSS, JavaScript, images, etc. in the static/ directory. They'll be copied to the build output as-is.

Data Files

If a project includes a data/ directory, Minuto loads .json, .yaml, and .yml files and exposes them under site.data.

Example:

data/
  site.json
  reports/
    songs.json

This becomes available in templates as:

{{site.data.site.name}}
{{site.data.reports.songs}}

Collection-Driven Pages

If a project includes a collections/ directory, each JSON/YAML manifest can generate multiple pages from a dataset in site.data.

Example manifest:

{
  "source": "reports.songs",
  "template": "report",
  "output": "reports/:slug.html"
}

Given object entries like song-a and song-b, Minuto will generate:

build/reports/song-a.html
build/reports/song-b.html

Within the template, Minuto exposes:

• item - current collection item
• slug - generated slug for the page
• site.data - global loaded data

Features

• ✅ Markdown to HTML conversion
• ✅ Frontmatter support (YAML)
• ✅ Handlebars templates with partials
• ✅ Automatic static file copying
• ✅ Nested content directories
• ✅ Development server with auto-rebuild
• ✅ Automatic sitemap generation
• ✅ HTML files support (alongside markdown)
• ✅ Zero configuration needed
• ✅ Alpine.js ready
• ✅ Tailwind CSS v4 with automatic compilation

Tailwind CSS v4 Support

Minuto has built-in support for Tailwind CSS v4 with automatic compilation during build.

Setup Tailwind

1. Create a styles/main.css file:

@import "tailwindcss";

/* Your custom CSS here */

2. Minuto will automatically:

   • Detect your Tailwind CSS file
   • Compile it during minuto build
   • Watch for changes in minuto dev mode
   • Output to build/styles.css

3. Include the compiled CSS in your templates:

<!-- templates/default.hbs -->
<!DOCTYPE html>
<html>
<head>
  <title>{{title}}</title>
  <link rel="stylesheet" href="/styles.css">
</head>
<body>
  {{{content}}}
</body>
</html>

Tailwind Configuration

Tailwind v4 uses CSS-based configuration. Add your custom theme in your CSS file:

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --font-display: "Inter", sans-serif;
}

/* Your custom utilities */
@utility tab-* {
  tab-size: *;
}

Supported Entry Points

Minuto looks for Tailwind CSS in these locations (in order):

• styles/main.css
• styles/styles.css
• styles/tailwind.css
• tailwind.css
• styles/index.css

Any file containing @import "tailwindcss" will be detected and compiled.

Alpine.js

For interactivity, include Alpine.js from CDN:

<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

Then use Alpine directives in your templates or markdown:

<div x-data="{ open: false }">
  <button @click="open = !open">Toggle</button>
  <div x-show="open">Content</div>
</div>

Package.json Integration

Add to your project's package.json:

{
  "scripts": {
    "build": "minuto build",
    "serve": "minuto serve",
    "dev": "minuto dev"
  },
  "devDependencies": {
    "minuto": "^0.0.1"
  }
}

Then run:

npm run dev

Dependencies

Only 4 runtime dependencies:

• markdown-it - Markdown parser
• handlebars - Template engine
• gray-matter - Frontmatter parser
• commander - CLI framework

Dev dependency (optional - only needed if using Tailwind):

• @tailwindcss/cli - Tailwind CSS v4 compiler

Philosophy

Convention over configuration. No config files, no complex build systems, just a simple compiler that turns markdown into beautiful static sites.

Perfect for:

• Blogs
• Documentation sites
• Landing pages
• Portfolio sites
• Any content-focused website

License

MIT