Strum

STRuctured Markdown - Convert between structured data and Markdown documents.

What is Strum?

Strum provides bidirectional conversion between structured data (JSON/Crystal) and Markdown documents with sections, metadata, and formatted content.

Perfect for:

• Document generation from structured data
• Parsing user-edited Markdown back to structure
• Template rendering with dynamic content
• Building documentation systems

Features

• ✅ Bidirectional: JSON ↔ Markdown
• ✅ Sections: Documents with headings, IDs, and metadata
• ✅ Formats: Checklists, tables, code blocks
• ✅ Metadata: YAML or JSON frontmatter per section
• ✅ Fluent API: Builder pattern for constructing documents

Installation

Add to your shard.yml:

dependencies:
  strum:
    path: ../strum  # or github: you/strum

Usage

Building Documents

require "strum"

# Build a structured document
doc = Strum::Builder.new
  .section("auth-todos", "Authentication TODOs", metadata: {"kind" => JSON::Any.new("todo")}) do |b|
    b.text("Implementation tasks:")
    b.checklist([
      {text: "Add JWT middleware", done: false},
      {text: "Write tests", done: true},
      {text: "Add documentation", done: false}
    ])
  end
  .to_markdown

puts doc

Output:

## [auth-todos] Authentication TODOs
---
kind: "todo"
---

Implementation tasks:

- [ ] Add JWT middleware
- [x] Write tests
- [ ] Add documentation

Parsing Documents (TODO)

markdown = File.read("todo.md")
doc = Strum::Parser.parse(markdown)

doc.sections.each do |section|
  puts "Section: #{section.title}"
  puts "ID: #{section.id}"
end

Formatting Utilities

# Format checklist
checklist = Strum::Formatter.checklist([
  {text: "Done", done: true},
  {text: "Pending", done: false}
])
# => "- [x] Done\n- [ ] Pending"

# Format code block
code = Strum::Formatter.code_block("puts 'hello'", "crystal")
# => "```crystal\nputs 'hello'\n```"

Roadmap

• [x] Basic document structure (Document, Section)
• [x] Builder API for constructing documents
• [x] Checklist formatting
• [x] YAML metadata rendering
• [ ] Markdown parser (Markdown → Structure)
• [ ] Table formatting
• [ ] Template system
• [ ] More content types (images, links, etc.)

Development

# Run tests
crystal spec

# Build
shards build

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-feature)
3. Commit your changes (git commit -am 'Add feature')
4. Push to the branch (git push origin my-feature)
5. Create a Pull Request

License

MIT License - see LICENSE file