Listsome Documentation

A static site generator for sharing DIY project guides. Write standard Markdown with YAML frontmatter, get a deployable static site.

What It Does Today

Every project lives in projects/<slug>/index.md. Step headers (## Step N: Title, ## Part N: Title) are automatically extracted. Tables with Item/Qty/Cost/Source columns are parsed as bill-of-materials.

Philosophy

• Standard Markdown: No proprietary syntax. Your files render everywhere.
• Single Binary: One Rust binary, no runtime, no database.
• Opinionated: Sensible defaults for DIY project sites.
• Portable Output: Deploy anywhere that serves static files.

Project Structure

my-site/
├── listsome.toml          # Site configuration
├── projects/              # Your project directories
│   └── my-project/
│       ├── index.md       # Project content with frontmatter
│       └── assets/        # Images, downloads, etc.
├── output/                # Generated site (gitignored)
└── README.md              # Your site's README (generated by init)

Quick Links

• Quickstart: Install, create a site, build, deploy
• Project Format: How to write project files
• Roadmap: Current state and planned features
• Contributors: Architecture, building, testing

Quickstart

Prerequisites

• Rust 1.75 or later

Install

cargo install listsome

Create a Site

listsome init my-projects
cd my-projects

This creates listsome.toml, a projects/ directory, and a .gitignore. Edit listsome.toml to set your site name, author, URL, and webmention endpoint. See the configuration reference for details.

Add a Project

listsome new smart-thermostat --title "Smart Thermostat" --difficulty intermediate

Edit projects/smart-thermostat/index.md with your content.

Build

listsome build

Generates output/index.html, output/<slug>/index.html for each project, and output/rss.xml.

Preview

listsome serve --open

Opens a browser at http://127.0.0.1:8080 with live reload. Edit your project files and the browser refreshes automatically.

Deploy

Copy the output/ directory to any static host (Netlify, Codeberg Pages, S3, nginx, etc.).

Command-Line Tool Reference

Global flags: -v (verbose), -q (quiet), -C <FILE> (config path), --color <WHEN>.

Project Format Reference

Philosophy

Write standard Markdown with YAML frontmatter. Listsome recognizes patterns through convention, not custom syntax. Your files render anywhere Markdown does.

Folder Structure

projects/
└── smart-thermostat/
    ├── index.md          # Project content (required)
    └── assets/           # Images, downloads (optional)
        ├── hero.jpg
        ├── wiring-diagram.png
        └── firmware.ino

• index.md is required, everything else is optional
• Metadata goes in frontmatter, not separate config files
• Assets referenced by relative path: ./assets/hero.jpg

Example Project

---
title: DIY Smart Thermostat
description: A $20 ESP32-based smart thermostat for Home Assistant
difficulty: intermediate
time: 4 hours
cost: 23.50
categories: [home-automation, electronics]
author: Your Name
date: 2026-03-08
---

# DIY Smart Thermostat

![Finished project](./assets/hero.jpg)

Replace your old thermostat with a smart, WiFi-enabled version
that integrates with Home Assistant.

## What You'll Need

| Item | Qty | Cost | Source |
|------|-----|------|--------|
| ESP32 DevKit | 1 | $6.00 | [Example](https://example.com) |
| DHT22 Sensor | 1 | $4.50 | [Adafruit](https://adafruit.com) |
| 5V Relay Module | 1 | $3.00 | [Example](https://example.com) |

## Step 1: Test Your Components

Connect the DHT22 to the ESP32 (VCC → 3.3V, GND → GND, Data → GPIO4)
and upload the test sketch.

## Step 2: Wire the Relay

Connect 24VAC control: R to relay COM, W to relay NO.

**Warning:** Turn off power at the breaker before proceeding.

## Step 3: Install the Software

Flash the firmware with PlatformIO, then configure WiFi and MQTT.

Frontmatter Schema

Required fields:

title: "Project Name"            # Display title (3-100 chars)
description: "Short summary"     # For listings, SEO (10-200 chars)

Optional:

difficulty: beginner             # beginner | intermediate | advanced
time: 4 hours                    # Estimated duration
cost: 23.50                      # Estimated total cost
currency: USD                    # ISO 4217 code
categories: [electronics]        # Primary categories
tags: [arduino, sensor]          # Searchable tags
author: Your Name                # Display name
date: 2026-03-08                 # ISO 8601

Advanced:

featured: true                   # Highlight on index page
hidden: false                    # Exclude from listings
draft: true                      # Work in progress
related: [other-project-slug]    # Related projects
dangerous: true                  # Shows warning banner
hero: ./assets/hero.jpg          # Image for index listings

Section Conventions

Listsome recognizes these H2 headers and extracts structured data:

BOM Tables

Tables under a materials header are parsed as structured BOM data. Recognized column names (case-insensitive):

• Item: Item, Part, Component, Name, Material
• Qty: Qty, Quantity, Count, Amount
• Cost: Cost, Price, Unit Cost, Each
• Source: Source, Link, Buy, Vendor, Supplier
• Notes: Notes, Description, Comment, Note

| Item | Qty | Cost | Source | Notes |
|------|-----|------|--------|-------|
| ESP32 | 1 | $6.00 | [Buy](link) | Any ESP32 works |

Step Headers

Headers matching ## Step N: Title, ## Part N: Title, or ## Phase N: Title are extracted as numbered steps. A table of contents is generated from the step titles.

Emoji Callouts

Bold text starting with a recognized prefix renders as a styled callout box:

Warning: High voltage present Tip: Buy in bulk to save 40% Note: App requires iOS 14+

Recognized prefixes include: warning, hot, tip, note, pro tip, caution.

Asset Conventions

Naming

assets/
├── hero.jpg              # Main image for listings
├── thumbnail.jpg         # Optional listing thumbnail override
├── step-01-breadboard.jpg   # Step images
├── step-02-wiring.jpg
├── diagram.svg           # Vector graphics
├── firmware.ino          # Code downloads
└── schematic.pdf         # PDF documents

Referencing Assets

# Standard image
![Alt text](./assets/photo.jpg)

# Video
<video src="./assets/demo.mp4" poster="./assets/demo-thumb.jpg"></video>

# Download link (renders as button)
[Download STL](./assets/model.stl)

Minimal Example

---
title: Paperclip Antenna
description: Free TV antenna from a paperclip
difficulty: beginner
time: 5 minutes
cost: 0
---

# Paperclip Antenna

Need free over-the-air TV? Unbend a paperclip.

## What You Need

| Item | Qty | Cost |
|------|-----|------|
| Paperclip | 1 | $0 |
| Coax adapter | 1 | $5 (optional) |

## Steps

1. Unbend paperclip into "L" shape
2. Insert into TV's coax input center pin
3. Auto-scan for channels

Done. No amplifier needed if you're close to broadcast towers.

Under 50 lines including frontmatter. Listsome makes it look professional.

Site Configuration

Listsome is configured via listsome.toml in your site root. Run listsome init to generate a default config, then edit it to match your setup.

Full Example

[site]
name = "My DIY Projects"
url = "https://projects.example.com"
description = "Step-by-step guides for things I built"
language = "en"
author = "Your Name"
about = "https://yourdomain.com/about"
email = "you@example.com"
source_repo = "https://codeberg.org/username/my-projects"

[site.fediverse]
mastodon = "@username@mastodon.social"

[build]
output_dir = "./output"
theme = "default"
drafts = false
parallel_jobs = 8
incremental = true

[webmention]
enabled = true
endpoint = "https://webmention.io/yourdomain.com/webmention"
require_approval = true
notify = false

[dev]
base_url = "http://localhost:8080"
port = 8080

[deploy]
host = "your-server.local"
user = "deploy"
path = "/var/www/site"

[fediverse]
enabled = false
mastodon_instance = "https://mastodon.social"
mastodon_token = ""
auto_syndicate = false
default_hashtags = ["#DIY", "#makers"]

[site]: Site Metadata

Fediverse Handles (under [site.fediverse])

These live under [site.fediverse] and are optional: they enable sharing features on project pages.

[build]: Build Settings

[webmention]: Webmention Settings

Webmentions let other sites notify you when they link to your projects. Requires endpoint to be configured.

[dev]: Development Settings

Configure the local development server.

[deploy]: Deployment Settings

Configure remote deployment via listsome deploy.

[fediverse]: Fediverse Syndication

Configure automatic posting to Mastodon when you publish or update a project.

To get a Mastodon API token: settings → Development → New Application, then copy the access token.

Author Fallback

When creating a project, the author is determined in this order:

1. --author flag on listsome new
2. author field in the project’s frontmatter
3. site.author from listsome.toml
4. USER or USERNAME environment variable
5. "Anonymous" as final fallback

Command-line Tool Flags

These fields can also be set via command-line tool flags on listsome init:

Roadmap

Current State (v0.1.0)

Listsome is functional for creating and publishing DIY project sites. See overview for what works today.

Planned

The following features are documented in design specs but not yet implemented:

Short Term

• Webmention support: Fetch, display, and send webmentions
• Image optimization: Automatic resizing and WebP/AVIF conversion
• Syntax highlighting: Code blocks with syntect-based highlighting
• Search index: Full-text search without external services
• Category and tag pages: Auto-generated listing pages per category/tag

Longer Term

• POSSE syndication: Publish to Mastodon, Pixelfed, PeerTube from the command-line tool
• Print stylesheets: Built-in print-friendly CSS for generated sites
• Import tools: Import from Instructables, Hackaday, and other platforms
• Video support: Transcoding and thumbnail generation
• Multi-language sites: i18n support for international makers
• Plugin system: Extend Listsome with custom generators and themes
• 3D model viewer: Inline STEP/STL viewing in project pages

Design Status

• IndieWeb integration: Documented; microformats2 markup is generated by default templates, webmention command-line tool is stubbed
• Fediverse syndication: Configuration model exists in listsome.toml, no implementation
• Interactivity: Research done on webmentions, email replies, and Giscus integrations for adding comments/reactions to project pages

Contributors Guide

Architecture

Listsome follows a pipeline architecture: source content → parse → render → output.

projects/*/index.md  ──►  Parser  ──►  Renderer (MiniJinja)  ──►  output/
(frontmatter + MD)        (pulldown-cmark)  +                   (static HTML)
                                              templates/

Modules

Data Flow

1. listsome build loads listsome.toml via config::find_and_load_config()
2. generator::SiteGenerator::discover_projects() walks projects/ looking for index.md
3. Each file is parsed by parser::parse_project() which extracts frontmatter and renders Markdown to HTML
4. Headers matching ## Step N: Title become Step structs; BOM tables become MaterialItems
5. render::TemplateRenderer renders each project into HTML using MiniJinja templates
6. Assets from projects/<slug>/assets/ are copied to output/<slug>/assets/
7. output/index.html (project listing) and output/feed.atom are generated

Design Patterns

• Pure functions with no shared mutable state
• Result<T, ListsomeError> throughout for error handling
• Immutable Project and ProjectMetadata structs
• SiteConfig with sensible defaults via Default trait
• Template renderer is created once and reused across all projects

Building

cargo build
cargo build --release   # Optimized binary

Testing

cargo test              # Run all tests
cargo test -- --nocapture  # Show test output

Tests are in #[cfg(test)] modules within each source file (parser, render, generator, config, server).

Code Style

• cargo clippy: Pedantic and nursery lints enabled (warnings during dev, not errors)
• cargo fmt: 100-character line width, Unix line endings
• Conventional commit messages for pull requests

How to Contribute

1. Open an issue to discuss your proposed change
2. Fork the repository
3. Make your changes with tests
4. Run cargo test and cargo clippy
5. Submit a pull request