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
| Command | What It Does |
|---|---|
listsome init | Scaffolds a new site with config, projects directory, and .gitignore |
listsome new | Creates a new project with index.md, frontmatter template, and assets directory |
listsome build | Parses projects, renders HTML from templates, copies assets, generates index page and Atom feed |
listsome serve | Dev server with live reload via WebSocket, auto-rebuilds on file changes |
listsome check | Validates project structure and frontmatter |
listsome list | Lists projects with filtering by category, difficulty, and draft status |
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