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.