Moss - Markup of Spread Sheet

Documentation-first markup language for embedding spreadsheet tables and visualizations in technical documentation

Like Mermaid for diagrams, Moss enables version-controlled, text-based data tables and charts that render beautifully in markdown documents.

🎉 v1.0.0 Released!

Moss v1.0.0 is now stable and production-ready! This release includes:

• ✅ 20 spreadsheet functions
• ✅ Multiple output formats (HTML, SVG, Markdown, JSON)
• ✅ Comprehensive documentation & examples
• ✅ 185 passing tests with 71% coverage
• ✅ WCAG 2.1 AA accessibility
• ✅ Security audit completed (5/5 rating)
• ✅ Performance optimizations

See CHANGELOG.md for full details.

🚀 Try It Live

Try the Moss Playground →

Experiment with Moss markup, formulas, and visualizations in your browser. No installation required!

Features

• YAML-based syntax - Clean, readable markup for spreadsheet data
• Excel-style cell references - A1, B2, AA10, etc.
• 20+ spreadsheet functions - Math, logic, text, and counting functions
• Bar charts with SVG - Vertical and horizontal orientations
• Multiple display modes - Full, paginated, compact, and virtual scrolling
• Accessibility-first - WCAG 2.1 AA compliant
• Type-safe - Written in TypeScript with strict types
• Lightweight - < 100KB bundle size

Installation

npm install moss-js

Quick Start

Basic Table

---
metadata:
  title: "Q1 Sales Data"
  theme: light

cells:
  - A1: "Product"
  - B1: "Sales"
  - A2: "Widget A"
  - B2: 1250
  - A3: "Widget B"
  - B3: 1890
  - A4: "Widget C"
  - B4: 3420

formulas:
  - B5: =SUM(B2:B4)

With Visualization

---
metadata:
  title: "Q1 Sales Report"

cells:
  - A1: "Product"
  - B1: "Sales"
  - A2: "Widget A"
  - B2: 1250
  - A3: "Widget B"
  - B3: 1890
  - A4: "Widget C"
  - B4: 3420

visualizations:
  sales_chart:
    type: bar
    title: "Q1 Sales by Product"
    labels: A2:A4
    data: B2:B4
    orientation: vertical
    showValues: true

Usage

JavaScript/TypeScript

import Moss from 'moss-js';

const markup = `
---
cells:
  - A1: 100
  - A2: 200
  - A3: =A1 + A2
`;

const result = Moss.render(markup, {
  target: '#container',
  format: 'html'
});

if (result.success) {
  console.log('Rendered successfully!');
} else {
  console.error('Errors:', result.errors);
}

CLI

# Validate a Moss file
moss validate example.moss

# Render to HTML
moss render example.moss output.html

# Evaluate formulas
moss eval example.moss --format=json

Supported Functions

Math Functions

• SUM(range) - Sum of values
• AVERAGE(range) - Arithmetic mean
• MIN(range) - Minimum value
• MAX(range) - Maximum value
• ROUND(value, decimals) - Round to N decimals
• ABS(value) - Absolute value
• FLOOR(value) - Round down
• CEIL(value) - Round up
• MOD(dividend, divisor) - Modulo
• POWER(base, exp) - Exponentiation

Logic Functions

• IF(condition, true_val, false_val) - Conditional
• AND(val1, val2, ...) - Logical AND
• OR(val1, val2, ...) - Logical OR
• NOT(value) - Logical NOT

Count Functions

• COUNT(range) - Count numeric cells
• COUNTA(range) - Count non-empty cells
• COUNTIF(range, criteria) - Conditional count

Text Functions

• CONCAT(text1, text2, ...) - Concatenate strings
• LEN(text) - String length
• UPPER(text) - Convert to uppercase
• LOWER(text) - Convert to lowercase

Data Types

• Float - Default numeric type: 100, -45.5, 1e6
• String - Double-quoted text: "Hello"
• DateTime - Date/time values: DATETIME(2024-01-15)

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Lint code
pnpm lint

# Format code
pnpm format

Project Structure

moss/
├── packages/
│   ├── moss-parser/      # YAML parser and AST
│   ├── moss-evaluator/   # Formula evaluator
│   ├── moss-renderer/    # HTML/SVG renderer
│   ├── moss/             # Main package
│   └── moss-cli/         # CLI tool
├── docs/                 # Documentation
└── examples/             # Example files

Documentation

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• API Reference - Complete API documentation
• Format Specification - Moss markup language reference
• Function Reference - All 20 functions with examples

Guides

• Migration Guide - Version migration and compatibility
• Performance Guide - Optimization and benchmarks
• Security Audit - Security analysis and compliance

Project Documentation

• Changelog - Version history and release notes
• Requirements - Complete requirements specification
• Language Design - Design decisions

Roadmap

Phase 1: Foundation (v0.1.0) ✅ Complete

• ✅ Basic parser and evaluator
• ✅ Core functions (SUM, AVERAGE, MIN, MAX, COUNT)
• ✅ Simple HTML table renderer
• ✅ CLI tool

Phase 2: Core Features (v0.5.0) ✅ Complete

• ✅ Complete function library (20 functions)
• ✅ Bar chart visualization
• ✅ Display modes (full, paginated, compact, virtual)
• ✅ Error handling

Phase 3: Polish & Documentation (v1.0.0) ✅ Complete

• ✅ Complete documentation (8 guides)
• ✅ 71% test coverage (185 tests)
• ✅ Performance optimization (formula cache, topological sort)
• ✅ WCAG 2.1 AA compliance
• ✅ Security audit (OWASP Top 10)
• ✅ Markdown plugins (markdown-it, remark)
• ✅ CSV import with auto-detection
• ✅ Multiple output formats

Phase 4: Ecosystem (v1.x) 🚧 Planned

• 🔮 Additional chart types (line, pie, scatter)
• 🔮 Framework integrations (React, Vue, Svelte)
• 🔮 VS Code extension
• 🔮 Docusaurus/VitePress plugins
• 🔮 Data filtering and sorting
• 🔮 Conditional formatting
• 🔮 Export to Excel/Google Sheets

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details

Support

• GitHub Issues: Report bugs or request features
• Documentation: Full documentation

---

Status: ✨ v1.0.0 Stable - Production Ready

Built with ❤️ for the technical documentation community

Moss © 2026 | MIT License | Changelog | Contributing