docyard 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a189b17059ce7d65d2bf10e3f920f193a1441cc2505a67b2acb9b9e4e99f5d94
-  data.tar.gz: f08c2fc0fb50a8e8c4f52bda72f14b122e196ad82b474977111292115e56c80b
+  metadata.gz: 0614d285d89d4f529607c5e4bdb50c823cce769a5628b90100234c9513f98690
+  data.tar.gz: 2f7c134bca20f17766e54fb4bc3b02b602e735cf4d8c7e11f83f9158773bec22
 SHA512:
-  metadata.gz: c0dc6551e43449d96f38fff9c0bf444bd8b233013be3af84690e2bf0c7db7795b75e9af9c02425e003a2ca2704aa7177452b90faebcc4bf599392afca17a34cc
-  data.tar.gz: 12ea961b5b7acb9da1ba15eaac76b7e62f5bbb96bf8039f83cfe4ec0a002cf641f25333eda7824c7e76a90cbda3fd5c87eafe3ed7b3477b93f8b29e6fc92f546
+  metadata.gz: 1259470e5245ff3ffc8796144a1e48fae46d851b44ca2c6cbeda0e8f83c782ebb815cfdfe0bdb3fa36fc25744a050859df44e5451376c8dadb4601ad9c3e2e98
+  data.tar.gz: 90281b4af9dd20425d26d6ea14214de5a79237ddeec9038546b9142819e363051850c64942a1b56459e5e8e1c509d08a36b323c2e01e3bacd4353fc39755915a

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,38 @@
+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
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# 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.2.0] - 2025-11-08
+
+### Added
+- Automatic sidebar navigation with nested folders
+- Collapsible sidebar sections with active page highlighting
+- Sidebar scroll position persistence
+- Modern responsive theme with mobile hamburger menu
+- Structured logging system with configurable levels
+- Custom error classes for better error handling
+- Constants module for shared application values
+- Utility modules for path resolution and text formatting
+- Improved initial templates with nested docs structure
+
+### Changed
+- Refactored sidebar rendering to use partial templates
+- Modular CSS architecture (split into variables, reset, typography, components, layout)
+- Enhanced router with routing resolution result pattern
+
+### Removed
+- Legacy syntax.css in favor of modular code.css
+
+## [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.2.0...HEAD
+[0.2.0]: https://github.com/sanifhimani/docyard/compare/v0.1.0...v0.2.0
+[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,185 @@
 # 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 search and build command. See [roadmap](#roadmap).
+
+## Features
+
+- **Sidebar navigation** - Automatic sidebar with nested folders and collapsible sections
+- **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/
+    introduction.md                 # Getting started guide
+    installation.md                 # Installation instructions
+    quick-start.md                  # Quick start guide
+  core-concepts/
+    file-structure.md              # File structure guide
+    markdown.md                     # Markdown guide
+```
+
+### 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
+
+**Next up:**
+- Dark mode with theme toggle
+- Markdown components (callouts, code groups, collapsible sections)
+- Icon system
+- Client-side search
+- Static site generation (`docyard build`)
+
+## 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/constants.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Constants
+    CONTENT_TYPE_HTML = "text/html; charset=utf-8"
+    CONTENT_TYPE_JSON = "application/json; charset=utf-8"
+    CONTENT_TYPE_CSS = "text/css; charset=utf-8"
+    CONTENT_TYPE_JS = "application/javascript; charset=utf-8"
+
+    RELOAD_ENDPOINT = "/_docyard/reload"
+    ASSETS_PREFIX = "/assets/"
+
+    INDEX_FILE = "index"
+    INDEX_TITLE = "Home"
+
+    MARKDOWN_EXTENSION = ".md"
+    HTML_EXTENSION = ".html"
+
+    STATUS_OK = 200
+    STATUS_NOT_FOUND = 404
+    STATUS_INTERNAL_ERROR = 500
+  end
+end

data/lib/docyard/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Error < StandardError; end
+
+  class FileNotFoundError < Error
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+      super("File not found: #{path}")
+    end
+  end
+
+  class InvalidPathError < Error; end
+
+  class MarkdownParseError < Error
+    attr_reader :file_path, :original_error
+
+    def initialize(file_path, original_error)
+      @file_path = file_path
+      @original_error = original_error
+      super("Failed to parse markdown file #{file_path}: #{original_error.message}")
+    end
+  end
+
+  class TemplateRenderError < Error
+    attr_reader :template_path, :original_error
+
+    def initialize(template_path, original_error)
+      @template_path = template_path
+      @original_error = original_error
+      super("Failed to render template #{template_path}: #{original_error.message}")
+    end
+  end
+
+  class ReloadCheckError < Error
+    attr_reader :original_error
+
+    def initialize(original_error)
+      @original_error = original_error
+      super("Reload check failed: #{original_error.message}")
+    end
+  end
+
+  class AssetNotFoundError < Error
+    attr_reader :asset_path
+
+    def initialize(asset_path)
+      @asset_path = asset_path
+      super("Asset not found: #{asset_path}")
+    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
+      Docyard.logger.error "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
+      Docyard.logger.info "Files changed, triggering reload..."
+    end
+  end
+end