docyard 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b69315ac7baa43631fa2019a0ab8fb16d2b738efc622ad58c9dac3a4922b94d
-  data.tar.gz: f180d6145f4ae3ab99f41a91ea85c62d6824952782e33b7a91dfde612f68d9a3
+  metadata.gz: 0614d285d89d4f529607c5e4bdb50c823cce769a5628b90100234c9513f98690
+  data.tar.gz: 2f7c134bca20f17766e54fb4bc3b02b602e735cf4d8c7e11f83f9158773bec22
 SHA512:
-  metadata.gz: 7e8a176789932b8b09d7f07dbb1eb2789230e7a48b5b6bee09e2ff2cf29f780456d58231adf54933c902172feb858020ca1d1ef148bba4aaf5ec1a8a3d5d3795
-  data.tar.gz: 435ac4d482457cf029c1e98ca772d56291c7cbd810d6463a770d79b0e073925c0e790fe23bc21ad1f2386f715ba946d4520d5c25ffb6d8fc724731b3df61ba24
+  metadata.gz: 1259470e5245ff3ffc8796144a1e48fae46d851b44ca2c6cbeda0e8f83c782ebb815cfdfe0bdb3fa36fc25744a050859df44e5451376c8dadb4601ad9c3e2e98
+  data.tar.gz: 90281b4af9dd20425d26d6ea14214de5a79237ddeec9038546b9142819e363051850c64942a1b56459e5e8e1c509d08a36b323c2e01e3bacd4353fc39755915a

data/.rubocop.yml

@@ -33,3 +33,6 @@ Layout/LineLength:
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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
@@ -25,6 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial gem structure
 - Project scaffolding
 
-[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.1.0...HEAD
+[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/README.md

@@ -5,10 +5,11 @@
 
 > Documentation generator for Ruby
 
-**Early development** - Core features work, but missing sidebar, search, and build command. See [roadmap](#roadmap).
+**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
@@ -56,8 +57,14 @@ docyard init
 This creates:
 ```
 docs/
-  index.md           # Home page
-  getting-started.md # Sample page
+  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
@@ -163,11 +170,12 @@ bundle exec rubocop
 
 ## Roadmap
 
-- Sidebar navigation
-- Search
-- Dark mode
-- Build command
-- Config file
+**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
 

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

@@ -23,7 +23,7 @@ module Docyard
     def stop
       @listener&.stop
     rescue StandardError => e
-      puts "[Docyard] Error stopping file watcher: #{e.class} - #{e.message}"
+      Docyard.logger.error "Error stopping file watcher: #{e.class} - #{e.message}"
     end
 
     def changed_since?(timestamp)
@@ -36,7 +36,7 @@ module Docyard
       return if modified.empty? && added.empty? && removed.empty?
 
       @last_modified_time = Time.now
-      puts "[Docyard] Files changed, triggering reload..."
+      Docyard.logger.info "Files changed, triggering reload..."
     end
   end
 end

data/lib/docyard/initializer.rb

@@ -9,7 +9,11 @@ module Docyard
 
     TEMPLATES = {
       "index.md" => "index.md.erb",
-      "getting-started.md" => "getting-started.md.erb"
+      "getting-started/introduction.md" => "getting-started/introduction.md.erb",
+      "getting-started/installation.md" => "getting-started/installation.md.erb",
+      "getting-started/quick-start.md" => "getting-started/quick-start.md.erb",
+      "core-concepts/file-structure.md" => "core-concepts/file-structure.md.erb",
+      "core-concepts/markdown.md" => "core-concepts/markdown.md.erb"
     }.freeze
 
     def initialize(path = ".")
@@ -46,6 +50,9 @@ module Docyard
       template_path = File.join(TEMPLATE_DIR, template_name)
       output_path = File.join(@docs_path, output_name)
 
+      output_dir = File.dirname(output_path)
+      FileUtils.mkdir_p(output_dir) unless File.directory?(output_dir)
+
       content = File.read(template_path)
       File.write(output_path, content)
     end
@@ -63,7 +70,7 @@ module Docyard
       puts ""
       puts "Next steps:"
       puts "  1. Edit your markdown files in #{DOCS_DIR}/"
-      puts "  2. Run 'docyard serve' to preview (not implemented yet)"
+      puts "  2. Run 'docyard serve' to preview your documentation locally"
     end
   end
 end

data/lib/docyard/logging.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Docyard
+  module Logging
+    class << self
+      attr_writer :logger
+
+      def logger
+        @logger ||= default_logger
+      end
+
+      def level=(level)
+        logger.level = Logger.const_get(level.to_s.upcase)
+      end
+
+      private
+
+      def default_logger
+        logger = Logger.new($stdout)
+        logger.level = Logger::INFO
+        logger.formatter = log_formatter
+        logger
+      end
+
+      def log_formatter
+        proc do |severity, datetime, _progname, msg|
+          timestamp = datetime.strftime("%Y-%m-%d %H:%M:%S")
+          "[#{timestamp}] [Docyard] [#{severity}] #{msg}\n"
+        end
+      end
+    end
+  end
+
+  def self.logger
+    Logging.logger
+  end
+
+  def self.log_level=(level)
+    Logging.level = level
+  end
+end

data/lib/docyard/rack_application.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "rack"
+require_relative "sidebar_builder"
 
 module Docyard
   class RackApplication
@@ -24,8 +25,8 @@ module Docyard
     def handle_request(env)
       path = env["PATH_INFO"]
 
-      return handle_reload_check(env) if path == "/_docyard/reload"
-      return asset_handler.serve(path) if path.start_with?("/assets/")
+      return handle_reload_check(env) if path == Constants::RELOAD_ENDPOINT
+      return asset_handler.serve(path) if path.start_with?(Constants::ASSETS_PREFIX)
 
       handle_documentation_request(path)
     rescue StandardError => e
@@ -33,31 +34,48 @@ module Docyard
     end
 
     def handle_documentation_request(path)
-      file_path = router.resolve(path)
-      status = file_path ? 200 : 404
-      html = file_path ? renderer.render_file(file_path) : renderer.render_not_found
+      result = router.resolve(path)
 
-      [status, { "Content-Type" => "text/html; charset=utf-8" }, [html]]
+      if result.found?
+        sidebar = SidebarBuilder.new(docs_path: docs_path, current_path: path)
+        html = renderer.render_file(result.file_path, sidebar_html: sidebar.to_html)
+        [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
+      else
+        html = renderer.render_not_found
+        [Constants::STATUS_NOT_FOUND, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
+      end
     end
 
     def handle_reload_check(env)
-      query = Rack::Utils.parse_query(env["QUERY_STRING"])
-      since = query["since"] ? Time.at(query["since"].to_f) : Time.now
+      since = parse_since_timestamp(env)
       reload_needed = file_watcher.changed_since?(since)
 
       build_reload_response(reload_needed)
     rescue StandardError => e
-      puts "[Docyard] Reload check error: #{e.message}"
+      log_reload_error(e)
       build_reload_response(false)
     end
 
+    def parse_since_timestamp(env)
+      query = Rack::Utils.parse_query(env["QUERY_STRING"])
+      query["since"] ? Time.at(query["since"].to_f) : Time.now
+    end
+
+    def log_reload_error(error)
+      Docyard.logger.error "Reload check error: #{error.message}"
+      Docyard.logger.debug error.backtrace.join("\n")
+    end
+
     def build_reload_response(reload_needed)
       response_body = { reload: reload_needed, timestamp: Time.now.to_f }.to_json
-      [200, { "Content-Type" => "application/json" }, [response_body]]
+      [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_JSON }, [response_body]]
     end
 
     def handle_error(error)
-      [500, { "Content-Type" => "text/html; charset=utf-8" }, [renderer.render_server_error(error)]]
+      Docyard.logger.error "Request error: #{error.message}"
+      Docyard.logger.debug error.backtrace.join("\n")
+      [Constants::STATUS_INTERNAL_ERROR, { "Content-Type" => Constants::CONTENT_TYPE_HTML },
+       [renderer.render_server_error(error)]]
     end
   end
 end

data/lib/docyard/renderer.rb

@@ -13,7 +13,7 @@ module Docyard
       @layout_path = File.join(LAYOUTS_PATH, "#{layout}.html.erb")
     end
 
-    def render_file(file_path)
+    def render_file(file_path, sidebar_html: "")
       markdown_content = File.read(file_path)
       markdown = Markdown.new(markdown_content)
 
@@ -21,15 +21,17 @@ module Docyard
 
       render(
         content: html_content,
-        page_title: markdown.title || "Documentation"
+        page_title: markdown.title || "Documentation",
+        sidebar_html: sidebar_html
       )
     end
 
-    def render(content:, page_title: "Documentation")
+    def render(content:, page_title: "Documentation", sidebar_html: "")
       template = File.read(layout_path)
 
       @content = content
       @page_title = page_title
+      @sidebar_html = sidebar_html
 
       ERB.new(template).result(binding)
     end

data/lib/docyard/router.rb

@@ -9,18 +9,23 @@ module Docyard
     end
 
     def resolve(request_path)
-      clean_path = request_path.delete_prefix("/")
-      clean_path = "index" if clean_path.empty?
+      clean_path = sanitize_path(request_path)
 
-      clean_path = clean_path.delete_suffix(".md")
+      file_path = File.join(docs_path, "#{clean_path}#{Constants::MARKDOWN_EXTENSION}")
+      return Routing::ResolutionResult.found(file_path) if File.file?(file_path)
 
-      file_path = File.join(docs_path, "#{clean_path}.md")
-      return file_path if File.file?(file_path)
+      index_path = File.join(docs_path, clean_path, "#{Constants::INDEX_FILE}#{Constants::MARKDOWN_EXTENSION}")
+      return Routing::ResolutionResult.found(index_path) if File.file?(index_path)
 
-      index_path = File.join(docs_path, clean_path, "index.md")
-      return index_path if File.file?(index_path)
+      Routing::ResolutionResult.not_found
+    end
+
+    private
 
-      nil
+    def sanitize_path(request_path)
+      clean = request_path.delete_prefix("/")
+      clean = Constants::INDEX_FILE if clean.empty?
+      clean.delete_suffix(Constants::MARKDOWN_EXTENSION)
     end
   end
 end

data/lib/docyard/routing/resolution_result.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Routing
+    class ResolutionResult
+      attr_reader :file_path, :status
+
+      def self.found(file_path)
+        new(file_path: file_path, status: :found)
+      end
+
+      def self.not_found
+        new(file_path: nil, status: :not_found)
+      end
+
+      def initialize(file_path:, status:)
+        @file_path = file_path
+        @status = status
+        freeze
+      end
+
+      def found?
+        status == :found
+      end
+
+      def not_found?
+        status == :not_found
+      end
+    end
+  end
+end

data/lib/docyard/sidebar/file_system_scanner.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class FileSystemScanner
+      attr_reader :docs_path
+
+      def initialize(docs_path)
+        @docs_path = docs_path
+      end
+
+      def scan
+        return [] unless File.directory?(docs_path)
+
+        scan_directory(docs_path, "")
+      end
+
+      private
+
+      def scan_directory(base_path, relative_path)
+        full_path = File.join(base_path, relative_path)
+        return [] unless File.directory?(full_path)
+
+        entries = sorted_entries(full_path, relative_path)
+        entries.map { |entry| build_item(entry, base_path, relative_path, full_path) }.compact
+      end
+
+      def sorted_entries(full_path, relative_path)
+        Dir.children(full_path)
+          .reject { |entry| hidden_or_ignored?(entry, relative_path) }
+          .sort_by { |entry| sort_key(entry) }
+      end
+
+      def build_item(entry, base_path, relative_path, full_path)
+        entry_full_path = File.join(full_path, entry)
+        entry_relative_path = build_relative_path(relative_path, entry)
+
+        if File.directory?(entry_full_path)
+          build_directory_item(entry, entry_relative_path, base_path)
+        elsif entry.end_with?(".md")
+          build_file_item(entry, entry_relative_path)
+        end
+      end
+
+      def build_relative_path(relative_path, entry)
+        relative_path.empty? ? entry : File.join(relative_path, entry)
+      end
+
+      def build_directory_item(entry, entry_relative_path, base_path)
+        {
+          type: :directory,
+          name: entry,
+          path: entry_relative_path,
+          children: scan_directory(base_path, entry_relative_path)
+        }
+      end
+
+      def build_file_item(entry, entry_relative_path)
+        {
+          type: :file,
+          name: entry.delete_suffix(".md"),
+          path: entry_relative_path
+        }
+      end
+
+      def hidden_or_ignored?(entry, relative_path)
+        entry.start_with?(".") ||
+          entry.start_with?("_") ||
+          (entry == "index.md" && relative_path.empty?)
+      end
+
+      def sort_key(entry)
+        entry.downcase
+      end
+    end
+  end
+end

data/lib/docyard/sidebar/renderer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Docyard
+  module Sidebar
+    class Renderer
+      PARTIALS_PATH = File.join(__dir__, "../templates/partials")
+
+      attr_reader :site_title
+
+      def initialize(site_title: "Documentation")
+        @site_title = site_title
+      end
+
+      def render(tree)
+        return "" if tree.empty?
+
+        nav_content = render_tree_with_sections(tree)
+        footer_html = render_partial(:sidebar_footer)
+
+        render_partial(:sidebar, nav_content: nav_content, footer_html: footer_html)
+      end
+
+      private
+
+      def render_partial(name, locals = {})
+        template_path = File.join(PARTIALS_PATH, "_#{name}.html.erb")
+        template = File.read(template_path)
+
+        locals.each { |key, value| instance_variable_set("@#{key}", value) }
+
+        erb_binding = binding
+        ERB.new(template).result(erb_binding)
+      end
+
+      def icon(name)
+        render_partial(:icons, icon_name: name)
+      end
+
+      def render_tree_with_sections(items)
+        filtered_items = items.reject { |item| item[:title]&.downcase == site_title.downcase }
+        grouped_items = group_by_section(filtered_items)
+
+        grouped_items.map do |section_name, section_items|
+          render_section(section_name, section_items)
+        end.join
+      end
+
+      def render_section(section_name, section_items)
+        section_content = render_tree(section_items)
+        render_partial(:nav_section, section_name: section_name, section_content: section_content)
+      end
+
+      def group_by_section(items)
+        sections = {}
+        root_items = []
+
+        items.each do |item|
+          process_section_item(item, sections, root_items)
+        end
+
+        build_section_result(sections, root_items)
+      end
+
+      def process_section_item(item, sections, root_items)
+        return if item[:title]&.downcase == site_title.downcase
+
+        if item[:type] == :directory && !item[:children].empty?
+          section_name = item[:title].upcase
+          sections[section_name] = item[:children]
+        else
+          root_items << item
+        end
+      end
+
+      def build_section_result(sections, root_items)
+        result = {}
+        result[nil] = root_items unless root_items.empty?
+        result.merge!(sections)
+      end
+
+      def render_tree(items)
+        return "" if items.empty?
+
+        list_items = items.map { |item| render_item(item) }.join
+        render_partial(:nav_list, list_items: list_items)
+      end
+
+      def render_item(item)
+        item_content = if item[:children].empty?
+                         render_leaf_item(item)
+                       else
+                         render_group_item(item)
+                       end
+
+        render_partial(:nav_item, item_content: item_content)
+      end
+
+      def render_leaf_item(item)
+        render_partial(:nav_leaf, path: item[:path], title: item[:title], active: item[:active])
+      end
+
+      def render_group_item(item)
+        children_html = render_tree(item[:children])
+        render_partial(:nav_group, title: item[:title], children_html: children_html)
+      end
+    end
+  end
+end

data/lib/docyard/sidebar/title_extractor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class TitleExtractor
+      def extract(file_path)
+        return titleize_filename(file_path) unless File.file?(file_path)
+
+        content = File.read(file_path)
+        markdown = Markdown.new(content)
+        markdown.title || titleize_filename(file_path)
+      rescue StandardError => e
+        Docyard.logger.warn "Failed to extract title from #{file_path}: #{e.message}"
+        titleize_filename(file_path)
+      end
+
+      private
+
+      def titleize_filename(file_path)
+        filename = File.basename(file_path, Constants::MARKDOWN_EXTENSION)
+        Utils::TextFormatter.titleize(filename)
+      end
+    end
+  end
+end