jackdaw 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5b17899530465a6c70afaf54e32479a44f82c97eb3a590ad765273824765997
+  data.tar.gz: '08c704ec34e10236e64b73f789fed9c3ffb1c084f7216a918b6914296a9e60df'
+SHA512:
+  metadata.gz: ba74079fefe98d864b769f62fe32ee8d3ea5bb9765c2c0823ffc9ec00d1af0e132ad2e0032f0be5de3c7c509b7307d89e8f752597cf8508e5d96cfe8a3b27a0d
+  data.tar.gz: e3f055613bbf027a8758e5dcb7d0e0fd992c35962275111c94b9844b577161c8c7708b8c27050643c6c4b88de076ae47195fb7c949406bb8fee1fdcfeb79bcac

data/.rubocop.yml

@@ -0,0 +1,32 @@
+AllCops:
+  TargetRubyVersion: 4.0
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+# CLI classes naturally have many public methods
+Metrics/ClassLength:
+  Max: 200
+
+# CLI methods often have longer implementations for user output
+Metrics/MethodLength:
+  Max: 50
+
+# CLI build methods have inherent complexity
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+# CLI classes don't need top-level documentation
+Style/Documentation:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to Jackdaw will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-06
+
+### Added
+- **Core Features**
+  - Lightning-fast static site generation with parallel processing
+  - Incremental builds (6-18x faster than clean builds)
+  - Convention-over-configuration approach (zero config files needed)
+  - Beautiful CLI with colorful output and emojis
+  - Live reload development server with auto-refresh
+  - GitHub Flavored Markdown with syntax highlighting (Rouge)
+  - ERB template system with layouts and partials
+
+- **CLI Commands**
+  - `jackdaw new <name>` - Create new site project with starter templates
+  - `jackdaw build` - Build static site with incremental and clean options
+  - `jackdaw serve` - Development server with live reload
+  - `jackdaw create <type> <name>` - Create new content from templates
+  - `jackdaw template list` - List available content templates
+  - `jackdaw version` - Show version information
+
+- **Project Structure**
+  - Convention-based directory layout (site/src, site/templates, site/assets, public/)
+  - Double-extension content files (name.type.md)
+  - Automatic date extraction from filenames (YYYY-MM-DD-name.type.md)
+  - Template discovery and validation
+
+- **Content Processing**
+  - Automatic metadata extraction (title, date, excerpt, reading time)
+  - Smart content type detection
+  - Nested directory structure preservation
+  - Asset copying with directory structure maintenance
+
+- **Template System**
+  - ERB template rendering with full context
+  - Layout wrapping (layout.html.erb)
+  - Partial includes with render helper
+  - Template caching for performance
+  - Access to all_posts and all_pages collections
+  - Site name inference from directory
+
+- **Performance**
+  - Multi-threaded parallel processing (uses all CPU cores)
+  - Smart incremental builds with mtime-based change detection
+  - Template compilation caching
+  - Benchmark results:
+    - Small sites (30 files): 5,821 files/sec incremental
+    - Medium sites (150 files): 12,343 files/sec incremental
+    - Large sites (600 files): 16,280 files/sec incremental
+
+- **Development Experience**
+  - Live reload with file watching (Listen gem)
+  - Beautiful CLI output with ANSI colors
+  - Detailed build statistics
+  - Verbose mode for debugging
+  - Comprehensive error messages
+
+- **Testing**
+  - 99 comprehensive tests covering all components
+  - Unit tests for core classes
+  - Integration tests for build pipeline
+  - End-to-end workflow tests
+  - Test fixtures and helpers
+
+### Technical Details
+- Ruby 4.0+ compatible
+- Dependencies: Thor, Kramdown, Rouge, Parallel, Listen, Puma, Rack
+- RuboCop compliant
+- Comprehensive documentation
+
+### Performance Benchmarks
+- Clean build: 164-693 files/sec
+- Incremental build: 5,821-16,280 files/sec
+- Build 600 files in under 1 second
+
+[1.0.0]: https://github.com/yourusername/jackdaw/releases/tag/v1.0.0

data/README.md

@@ -0,0 +1,467 @@
+# Jackdaw ⚡️
+
+**Lightning-fast Ruby static site generator with convention over configuration**
+
+Jackdaw is a minimal, fast static site generator that emphasizes:
+- **Speed**: Parallel processing and incremental builds
+- **Simplicity**: Convention over configuration - zero config files needed
+- **Developer Experience**: Live reload, beautiful CLI output, intuitive structure
+
+## Features
+
+- ⚡️ **Blazing Fast**: Build 600 files in under 1 second
+- 🔄 **Incremental Builds**: Only rebuilds changed files (6-18x faster)
+- 🎨 **Beautiful CLI**: Colorful, informative command output
+- 🔥 **Live Reload**: Auto-refresh browser on file changes
+- 📝 **Markdown + ERB**: GitHub Flavored Markdown with ERB templates
+- 🎯 **Convention-Based**: No configuration files required
+- 🌈 **Syntax Highlighting**: Built-in code highlighting with Rouge
+- 🚀 **Development Server**: Built-in server with live reload
+
+## Performance
+
+| Site Size | Files | Clean Build | Incremental | Files/sec |
+|-----------|-------|-------------|-------------|-----------|
+| Small     | 30    | 0.18s       | 0.005s      | 5,821     |
+| Medium    | 150   | 0.35s       | 0.012s      | 12,343    |
+| Large     | 600   | 0.87s       | 0.037s      | 16,280    |
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jackdaw'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install jackdaw
+```
+
+## Quick Start
+
+### Create a new site
+
+```bash
+$ jackdaw new my-blog
+$ cd my-blog.site
+```
+
+This creates a project structure:
+
+```
+my-blog.site/
+├── site/
+│   ├── src/              # Your content (Markdown files)
+│   ├── templates/        # ERB templates
+│   └── assets/           # Static assets (CSS, images, etc.)
+└── public/               # Generated output (git-ignored)
+```
+
+### Build your site
+
+```bash
+$ jackdaw build              # Build the site
+$ jackdaw build --clean      # Clean build (remove old files)
+$ jackdaw build --verbose    # Show detailed output
+```
+
+### Development server
+
+```bash
+$ jackdaw serve              # Start server with live reload on port 4000
+$ jackdaw serve --port 3000  # Use custom port
+$ jackdaw serve --no-livereload  # Disable live reload
+```
+
+Visit `http://localhost:4000` to see your site with auto-reload enabled!
+
+### Create content
+
+```bash
+$ jackdaw create blog "My First Post"      # Creates: 2026-01-06-my-first-post.blog.md
+$ jackdaw create page "About"              # Creates: about.page.md
+$ jackdaw create page "company/history"    # Creates: company/history.page.md
+```
+
+### List available templates
+
+```bash
+$ jackdaw template list
+```
+
+## Project Structure
+
+Jackdaw follows a simple, convention-based structure:
+
+```
+my-site.site/
+├── site/
+│   ├── src/                    # Content directory
+│   │   ├── index.page.md       # Homepage
+│   │   ├── about.page.md       # About page
+│   │   └── blog/               # Blog posts
+│   │       └── 2026-01-06-hello.blog.md
+│   │
+│   ├── templates/              # ERB templates
+│   │   ├── layout.html.erb     # Main layout
+│   │   ├── page.html.erb       # Page template
+│   │   ├── blog.html.erb       # Blog post template
+│   │   └── _nav.html.erb       # Partial (starts with _)
+│   │
+│   └── assets/                 # Static files
+│       ├── styles.css
+│       └── images/
+│
+└── public/                     # Generated output
+    ├── index.html
+    ├── about.html
+    ├── blog/
+    │   └── 2026-01-06-hello.html
+    └── assets/
+```
+
+## Content Files
+
+Content files use a naming convention: `<name>.<type>.md`
+
+### Pages
+
+```markdown
+# About Us
+
+Regular pages using the page template.
+```
+
+**File**: `about.page.md` → **Output**: `about.html`
+
+### Blog Posts (with date prefixes)
+
+```markdown
+# My First Post
+
+Blog posts automatically get date metadata from filename.
+```
+
+**File**: `2026-01-06-first-post.blog.md` → **Output**: `blog/2026-01-06-first-post.html`
+
+### Metadata Extraction
+
+Jackdaw automatically extracts metadata:
+
+- **Title**: From first H1 heading (`# Title`)
+- **Date**: From filename (`YYYY-MM-DD-`) or file modification time
+- **Excerpt**: First 150 words
+- **Reading Time**: Calculated from word count
+
+## Templates
+
+### Layout Template (`layout.html.erb`)
+
+```erb
+<!DOCTYPE html>
+<html>
+<head>
+  <title><%= title %> - <%= site_name %></title>
+</head>
+<body>
+  <%= render 'nav' %>
+  <%= content %>
+</body>
+</html>
+```
+
+### Page Template (`page.html.erb`)
+
+```erb
+<main>
+  <%= content %>
+</main>
+```
+
+### Blog Template (`blog.html.erb`)
+
+```erb
+<article>
+  <h1><%= title %></h1>
+  <time><%= date.strftime('%B %d, %Y') %></time>
+  <%= content %>
+</article>
+```
+
+### Partials
+
+Partials start with `_` and can be included with `<%= render 'name' %>`
+
+**File**: `_nav.html.erb`
+
+```erb
+<nav>
+  <a href="/">Home</a>
+  <a href="/blog">Blog</a>
+</nav>
+```
+
+**Usage**: `<%= render 'nav' %>`
+
+## Template Variables
+
+Available in all templates:
+
+| Variable | Description |
+|----------|-------------|
+| `<%= content %>` | Rendered markdown content |
+| `<%= title %>` | Page title (from H1) |
+| `<%= date %>` | Post date (Date object) |
+| `<%= excerpt %>` | First 150 words |
+| `<%= reading_time %>` | Estimated minutes to read |
+| `<%= site_name %>` | Site name (from directory) |
+| `<%= all_posts %>` | Array of all blog posts |
+| `<%= all_pages %>` | Array of all pages |
+
+## Syntax Highlighting
+
+Code blocks are automatically highlighted:
+
+````markdown
+```ruby
+def hello
+  puts "Hello, World!"
+end
+```
+````
+
+## Creating Custom Templates
+
+1. Create a new template file: `templates/project.html.erb`
+2. Add your template code
+3. Create content with: `jackdaw create project "My Project"`
+
+Dated templates (auto-prefix with date):
+- `blog`, `post`, `article`, `news`
+
+Override with flags:
+```bash
+$ jackdaw create page "Timeline" --dated      # Add date to page
+$ jackdaw create blog "Timeless" --no-date    # Remove date from blog
+```
+
+## CLI Commands
+
+### `jackdaw new <name>`
+
+Create a new site project with starter templates and example content.
+
+```bash
+$ jackdaw new my-blog
+$ cd my-blog.site
+```
+
+### `jackdaw build [options]`
+
+Build the static site.
+
+**Options:**
+- `--clean, -c` Clean output directory before building
+- `--verbose, -v` Show detailed output
+
+```bash
+$ jackdaw build           # Incremental build
+$ jackdaw build --clean   # Full rebuild
+```
+
+### `jackdaw serve [options]`
+
+Start development server with live reload.
+
+**Options:**
+- `--port, -p PORT` Server port (default: 4000)
+- `--host, -h HOST` Server host (default: localhost)
+- `--no-livereload` Disable live reload
+
+```bash
+$ jackdaw serve                    # Start on port 4000
+$ jackdaw serve --port 3000        # Use port 3000
+$ jackdaw serve --no-livereload    # No auto-refresh
+```
+
+### `jackdaw create <template> <name> [options]`
+
+Create a new content file from template.
+
+**Options:**
+- `--dated` Add date prefix to filename
+- `--no-date` Skip date prefix
+
+```bash
+$ jackdaw create blog "First Post"           # → 2026-01-06-first-post.blog.md
+$ jackdaw create page "About"                # → about.page.md
+$ jackdaw create page "company/team"         # → company/team.page.md
+$ jackdaw create page "Timeline" --dated     # → 2026-01-06-timeline.page.md
+```
+
+### `jackdaw template list`
+
+List all available templates.
+
+```bash
+$ jackdaw template list
+```
+
+### `jackdaw version`
+
+Show Jackdaw version.
+
+```bash
+$ jackdaw version
+```
+
+## How It Works
+
+### Build Process
+
+1. **Scan**: Discover all content, template, and asset files
+2. **Check**: Determine which files need rebuilding (mtime-based)
+3. **Process**: Render content in parallel using all CPU cores
+4. **Write**: Output HTML files to public/ directory
+5. **Copy**: Copy assets to public/assets/
+
+### Incremental Builds
+
+Jackdaw uses modification time (mtime) checking to only rebuild files when:
+- Content file changed
+- Template file changed
+- Layout file changed
+
+This makes rebuilds **6-18x faster** than clean builds.
+
+### Live Reload
+
+The development server watches for file changes and:
+1. Detects changes using the Listen gem
+2. Triggers incremental rebuild
+3. Injects JavaScript that polls for changes
+4. Refreshes browser automatically
+
+## Best Practices
+
+### Content Organization
+
+```
+src/
+├── index.page.md           # Homepage
+├── about.page.md           # Top-level pages
+├── blog/                   # Blog posts by category
+│   └── 2026-01-06-post.blog.md
+└── projects/               # Nested content
+    └── project-name.page.md
+```
+
+### Template Naming
+
+- Main layout: `layout.html.erb` (required)
+- Content templates: `<type>.html.erb` (e.g., `blog.html.erb`)
+- Partials: `_<name>.html.erb` (e.g., `_header.html.erb`)
+
+### Dated Content
+
+Use dated types for time-based content:
+- `blog` - Blog posts
+- `post` - General posts
+- `article` - Articles
+- `news` - News items
+
+Use non-dated types for static content:
+- `page` - Pages
+- `project` - Projects
+- Any custom type
+
+## Deployment
+
+Jackdaw generates static HTML files in the `public/` directory. Deploy to any static host:
+
+### Netlify / Vercel
+
+```bash
+$ jackdaw build
+# Deploy public/ directory
+```
+
+### GitHub Pages
+
+```bash
+$ jackdaw build
+$ cd public
+$ git init
+$ git add .
+$ git commit -m "Deploy"
+$ git push origin gh-pages
+```
+
+### Nginx / Apache
+
+Copy `public/` contents to your web server's document root.
+
+## Troubleshooting
+
+### Server won't start
+
+Make sure you're in a `.site` directory:
+
+```bash
+$ jackdaw serve
+✗ No site directory found. Run this command from a .site directory.
+```
+
+### Template not found
+
+List available templates:
+
+```bash
+$ jackdaw template list
+```
+
+### Build errors
+
+Run with verbose flag to see details:
+
+```bash
+$ jackdaw build --verbose
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Built with:
+- [Thor](https://github.com/rails/thor) - CLI framework
+- [Kramdown](https://kramdown.gettalong.org/) - Markdown parser
+- [Rouge](https://github.com/rouge-ruby/rouge) - Syntax highlighting
+- [Parallel](https://github.com/grosser/parallel) - Multi-threading
+- [Listen](https://github.com/guard/listen) - File watching
+- [Puma](https://puma.io/) - Web server
+- [Rack](https://github.com/rack/rack) - Web server interface
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/jackdaw.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec