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

Module	Responsibility
`src/cli.rs`	Command-line argument parsing with `clap`
`src/commands.rs`	Command implementations that wire up the pipeline
`src/config.rs`	`listsome.toml` loading, default config creation
`src/parser/mod.rs`	Frontmatter extraction, Markdown→HTML, step/BOM parsing
`src/render/mod.rs`	MiniJinja template rendering, context builders
`src/generator/mod.rs`	Site generation orchestration (discover, parse, render, copy assets, generate index + feed)
`src/server/mod.rs`	Axum-based dev server with WebSocket live reload and file watching
`src/model/project.rs`	`Project`, `Step`, `ProjectMetadata`, `Difficulty`, `ProjectStatus`
`src/model/site.rs`	`SiteConfig`, `BuildConfig`, `WebmentionConfig`, `FediverseConfig`
`src/error.rs`	`ListsomeError` enum with typed error variants
`src/templates/`	Built-in MiniJinja templates (`base.html`, `index.html`, `project.html`, `feed.atom`)

Data Flow

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

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

Keyboard shortcuts

Listsome Documentation