docyard 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a189b17059ce7d65d2bf10e3f920f193a1441cc2505a67b2acb9b9e4e99f5d94
-  data.tar.gz: f08c2fc0fb50a8e8c4f52bda72f14b122e196ad82b474977111292115e56c80b
+  metadata.gz: 9b69315ac7baa43631fa2019a0ab8fb16d2b738efc622ad58c9dac3a4922b94d
+  data.tar.gz: f180d6145f4ae3ab99f41a91ea85c62d6824952782e33b7a91dfde612f68d9a3
 SHA512:
-  metadata.gz: c0dc6551e43449d96f38fff9c0bf444bd8b233013be3af84690e2bf0c7db7795b75e9af9c02425e003a2ca2704aa7177452b90faebcc4bf599392afca17a34cc
-  data.tar.gz: 12ea961b5b7acb9da1ba15eaac76b7e62f5bbb96bf8039f83cfe4ec0a002cf641f25333eda7824c7e76a90cbda3fd5c87eafe3ed7b3477b93f8b29e6fc92f546
+  metadata.gz: 7e8a176789932b8b09d7f07dbb1eb2789230e7a48b5b6bee09e2ff2cf29f780456d58231adf54933c902172feb858020ca1d1ef148bba4aaf5ec1a8a3d5d3795
+  data.tar.gz: 435ac4d482457cf029c1e98ca772d56291c7cbd810d6463a770d79b0e073925c0e790fe23bc21ad1f2386f715ba946d4520d5c25ffb6d8fc724731b3df61ba24

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug Report
+about: Report a bug
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Description
+
+<!-- Clear description of the bug -->
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+<!-- What should happen -->
+
+## Actual Behavior
+
+<!-- What actually happens -->
+
+## Environment
+
+- Ruby version: <!-- `ruby -v` -->
+- Docyard version: <!-- `gem list docyard` -->
+- OS: <!-- macOS, Linux, etc. -->

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature Request
+about: Suggest a feature
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+## Description
+
+<!-- What feature would you like? -->
+
+## Use Case
+
+<!-- Why is this useful? When would you use it? -->
+
+## Implementation Ideas
+
+<!-- Optional: How might this work? -->

data/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Description
+
+<!-- What does this PR do? -->
+
+## Changes
+
+-
+-
+
+## Checklist
+
+- [ ] Tests added/updated
+- [ ] CHANGELOG.md updated
+- [ ] README.md updated (if needed)

data/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }} - Test
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.2', '3.3', '3.4', 'head']
+    continue-on-error: ${{ matrix.ruby == 'head' }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec
+        env:
+            RUBYOPT: '-W0'
+
+  lint:
+    name: Rubocop
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Run rubocop
+        run: bundle exec rubocop

data/.rubocop.yml

@@ -0,0 +1,35 @@
+plugins:
+  - rubocop-rspec
+  - rubocop-rake
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  Exclude:
+    - 'vendor/**/*'
+    - 'spec/fixtures/**/*'
+    - 'tmp/**/*'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+RSpec/ExampleLength:
+  Max: 10
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 15
+
+Style/Documentation:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 120
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-11-04
+
+### Added
+- Hot reload
+- GitHub Flavored Markdown support (tables, task lists, strikethrough)
+- Syntax highlighting for 100+ languages via Rouge
+- YAML frontmatter for page metadata
+- Customizable 404/500 error templates
+- CLI commands: `docyard init`, `docyard serve`
+- File watcher for live reload
+- Directory traversal protection in asset handler
+
+## [0.0.1] - 2025-11-03
+
+### Added
+- Initial gem structure
+- Project scaffolding
+
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sanifhimani/docyard/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/sanifhimani/docyard/releases/tag/v0.0.1

data/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+Thanks for wanting to contribute to Docyard!
+
+## Development Setup
+
+```bash
+git clone https://github.com/YOUR_USERNAME/docyard.git
+cd docyard
+bundle install
+
+# Run tests
+bundle exec rspec
+bundle exec rubocop
+
+# Test locally
+./bin/docyard init
+./bin/docyard serve
+```
+
+## Pull Requests
+
+1. Fork the repo and create a branch from `main`
+2. Write tests for new features
+3. Run `bundle exec rspec && bundle exec rubocop`
+4. Update README/CHANGELOG if needed
+5. Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`
+
+## Architecture
+
+```
+lib/docyard/
+  cli.rb              # CLI
+  server.rb           # Server lifecycle
+  rack_application.rb # HTTP handling
+  router.rb           # URL → file mapping
+  renderer.rb         # Markdown → HTML
+  markdown.rb         # Parsing
+  file_watcher.rb     # Live reload
+  asset_handler.rb    # Static assets
+```
+
+## Code Style
+
+- Maintain >85% test coverage
+- Keep methods focused and readable
+- Add tests for new features
+
+## Questions?
+
+Open an issue.
+
+---
+
+Thanks for contributing! 🚀

data/README.md

@@ -1,14 +1,177 @@
 # Docyard
 
+[![CI](https://github.com/sanifhimani/docyard/actions/workflows/ci.yml/badge.svg)](https://github.com/sanifhimani/docyard/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/docyard.svg)](https://badge.fury.io/rb/docyard)
+
 > Documentation generator for Ruby
 
-## What is this?
+**Early development** - Core features work, but missing sidebar, search, and build command. See [roadmap](#roadmap).
+
+## Features
+
+- **Hot reload** - Changes appear instantly while you write
+- **GitHub Flavored Markdown** - Tables, task lists, strikethrough
+- **Syntax highlighting** - 100+ languages via Rouge
+- **YAML frontmatter** - Add metadata to your pages
+- **Customizable error pages** - Make 404/500 pages your own
+
+## Quick Start
+
+```bash
+# Install the gem
+gem install docyard
+
+# Create a new docs project
+mkdir my-docs && cd my-docs
+docyard init
 
-Building a modern documentation generator for Ruby. Zero config, convention over configuration.
+# Start the dev server
+docyard serve
+
+# Visit http://localhost:4200
+```
 
 ## Installation
 
-Not published yet. Building in public - follow along!
+Add to your Gemfile:
+
+```ruby
+gem 'docyard'
+```
+
+Or install directly:
+
+```bash
+gem install docyard
+```
+
+## Usage
+
+### Initialize a New Project
+
+```bash
+docyard init
+```
+
+This creates:
+```
+docs/
+  index.md           # Home page
+  getting-started.md # Sample page
+```
+
+### Start Development Server
+
+```bash
+docyard serve
+
+# Custom port and host
+docyard serve --port 3000 --host 0.0.0.0
+```
+
+### Writing Docs
+
+Create markdown files in the `docs/` directory:
+
+```markdown
+---
+title: Getting Started
+---
+
+# Getting Started
+
+\`\`\`ruby
+class User
+  def initialize(name)
+    @name = name
+  end
+end
+\`\`\`
+```
+
+### Frontmatter
+
+Add YAML frontmatter to customize page metadata:
+
+```yaml
+---
+title: My Page Title
+description: Page description
+---
+```
+
+Currently supported:
+- `title` - Page title (shown in `<title>` tag)
+
+### Linking Between Pages
+
+Write links with `.md` extension, they'll be automatically cleaned:
+
+```markdown
+[Getting Started](./getting-started.md)  → /getting-started
+[Guide](./guide/index.md)                → /guide
+```
+
+### Directory Structure
+
+```
+docs/
+  index.md              # / (root)
+  getting-started.md    # /getting-started
+  guide/
+    index.md            # /guide
+    setup.md            # /guide/setup
+    advanced.md         # /guide/advanced
+```
+
+## Architecture
+
+Clean separation of concerns:
+
+```
+lib/docyard/
+  cli.rb              # Command-line interface (Thor)
+  initializer.rb      # Project scaffolding (init command)
+  server.rb           # Server lifecycle (WEBrick, signals)
+  rack_application.rb # HTTP request handling (routing, rendering)
+  router.rb           # URL → file path mapping
+  renderer.rb         # Markdown → HTML conversion
+  markdown.rb         # Markdown parsing & frontmatter extraction
+  file_watcher.rb     # Live reload file monitoring
+  asset_handler.rb    # Static asset serving
+```
+
+Each class has a single, clear responsibility. Easy to test, easy to extend.
+
+## Development
+
+```bash
+git clone https://github.com/sanifhimani/docyard.git
+cd docyard
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Use local version
+./bin/docyard init
+./bin/docyard serve
+```
+
+## Roadmap
+
+- Sidebar navigation
+- Search
+- Dark mode
+- Build command
+- Config file
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## License
 

data/lib/docyard/asset_handler.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Docyard
+  class AssetHandler
+    ASSETS_PATH = File.join(__dir__, "templates", "assets")
+
+    CONTENT_TYPES = {
+      ".css" => "text/css; charset=utf-8",
+      ".js" => "application/javascript; charset=utf-8",
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".svg" => "image/svg+xml",
+      ".woff" => "font/woff2",
+      ".woff2" => "font/woff2",
+      ".ico" => "image/x-icon"
+    }.freeze
+
+    def serve(request_path)
+      asset_path = extract_asset_path(request_path)
+
+      return forbidden_response if directory_traversal?(asset_path)
+
+      file_path = build_file_path(asset_path)
+      return not_found_response unless File.file?(file_path)
+
+      serve_file(file_path)
+    end
+
+    private
+
+    def extract_asset_path(request_path)
+      request_path.delete_prefix("/assets/")
+    end
+
+    def directory_traversal?(path)
+      path.include?("..")
+    end
+
+    def build_file_path(asset_path)
+      File.join(ASSETS_PATH, asset_path)
+    end
+
+    def serve_file(file_path)
+      content = File.read(file_path)
+      content_type = detect_content_type(file_path)
+
+      [200, { "Content-Type" => content_type }, [content]]
+    end
+
+    def detect_content_type(file_path)
+      extension = File.extname(file_path)
+      CONTENT_TYPES.fetch(extension, "application/octet-stream")
+    end
+
+    def forbidden_response
+      [403, { "Content-Type" => "text/plain" }, ["403 Forbidden"]]
+    end
+
+    def not_found_response
+      [404, { "Content-Type" => "text/plain" }, ["404 Not Found"]]
+    end
+  end
+end

data/lib/docyard/cli.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Docyard
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "version", "Show docyard version"
+    def version
+      puts "docyard #{Docyard::VERSION}"
+    end
+
+    desc "init", "Initialize a new docyard project"
+    def init
+      initializer = Docyard::Initializer.new
+      exit(1) unless initializer.run
+    end
+
+    desc "serve", "Start the development server"
+    method_option :port, type: :numeric, default: 4200, aliases: "-p", desc: "Port to run the server on"
+    method_option :host, type: :string, default: "localhost", aliases: "-h", desc: "Host to bind the server to"
+    def serve
+      require_relative "server"
+      server = Docyard::Server.new(
+        port: options[:port],
+        host: options[:host]
+      )
+      server.start
+    end
+  end
+end

data/lib/docyard/file_watcher.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "listen"
+
+module Docyard
+  class FileWatcher
+    attr_reader :last_modified_time
+
+    def initialize(docs_path)
+      @docs_path = docs_path
+      @last_modified_time = Time.now
+      @listener = nil
+    end
+
+    def start
+      @listener = Listen.to(@docs_path, only: /\.md$/) do |modified, added, removed|
+        handle_changes(modified, added, removed)
+      end
+
+      @listener.start
+    end
+
+    def stop
+      @listener&.stop
+    rescue StandardError => e
+      puts "[Docyard] Error stopping file watcher: #{e.class} - #{e.message}"
+    end
+
+    def changed_since?(timestamp)
+      @last_modified_time > timestamp
+    end
+
+    private
+
+    def handle_changes(modified, added, removed)
+      return if modified.empty? && added.empty? && removed.empty?
+
+      @last_modified_time = Time.now
+      puts "[Docyard] Files changed, triggering reload..."
+    end
+  end
+end

data/lib/docyard/initializer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Docyard
+  class Initializer
+    DOCS_DIR = "docs"
+    TEMPLATE_DIR = File.join(__dir__, "templates", "markdown")
+
+    TEMPLATES = {
+      "index.md" => "index.md.erb",
+      "getting-started.md" => "getting-started.md.erb"
+    }.freeze
+
+    def initialize(path = ".")
+      @path = path
+      @docs_path = File.join(@path, DOCS_DIR)
+    end
+
+    def run
+      if already_initialized?
+        print_already_exists_error
+        return
+      end
+
+      create_structure
+      print_success
+      true
+    end
+
+    private
+
+    def already_initialized?
+      File.exist?(@docs_path)
+    end
+
+    def create_structure
+      FileUtils.mkdir_p(@docs_path)
+
+      TEMPLATES.each do |output_name, template_name|
+        copy_template(template_name, output_name)
+      end
+    end
+
+    def copy_template(template_name, output_name)
+      template_path = File.join(TEMPLATE_DIR, template_name)
+      output_path = File.join(@docs_path, output_name)
+
+      content = File.read(template_path)
+      File.write(output_path, content)
+    end
+
+    def print_already_exists_error
+      puts "Error: #{DOCS_DIR}/ folder already exists"
+      puts "   Remove it first or run docyard in a different directory"
+    end
+
+    def print_success
+      puts "Docyard initialized successfully!"
+      puts ""
+      puts "Created:"
+      TEMPLATES.each_key { |file| puts "  #{DOCS_DIR}/#{file}" }
+      puts ""
+      puts "Next steps:"
+      puts "  1. Edit your markdown files in #{DOCS_DIR}/"
+      puts "  2. Run 'docyard serve' to preview (not implemented yet)"
+    end
+  end
+end

data/lib/docyard/markdown.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+require "yaml"
+
+module Docyard
+  class Markdown
+    FRONTMATTER_REGEX = /\A---\s*\n(.*?\n)---\s*\n/m
+
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw.freeze
+    end
+
+    def frontmatter
+      @frontmatter ||= parse_frontmatter
+    end
+
+    def content
+      @content ||= extract_content
+    end
+
+    def html
+      @html ||= render_html
+    end
+
+    def title
+      frontmatter["title"]
+    end
+
+    def description
+      frontmatter["description"]
+    end
+
+    private
+
+    def parse_frontmatter
+      match = raw.match(FRONTMATTER_REGEX)
+      return {} unless match
+
+      YAML.safe_load(match[1])
+    rescue Psych::SyntaxError
+      {}
+    end
+
+    def extract_content
+      raw.sub(FRONTMATTER_REGEX, "").strip
+    end
+
+    def render_html
+      Kramdown::Document.new(
+        content,
+        input: "GFM",
+        hard_wrap: false,
+        syntax_highlighter: "rouge"
+      ).to_html
+    end
+  end
+end