docyard 0.1.0 → 0.3.0

data/lib/docyard/rack_application.rb

@@ -2,12 +2,15 @@
 
 require "json"
 require "rack"
+require_relative "sidebar_builder"
+require_relative "constants"
 
 module Docyard
   class RackApplication
-    def initialize(docs_path:, file_watcher:)
+    def initialize(docs_path:, file_watcher:, config: nil)
       @docs_path = docs_path
       @file_watcher = file_watcher
+      @config = config
       @router = Router.new(docs_path: docs_path)
       @renderer = Renderer.new
       @asset_handler = AssetHandler.new
@@ -19,13 +22,13 @@ module Docyard
 
     private
 
-    attr_reader :docs_path, :file_watcher, :router, :renderer, :asset_handler
+    attr_reader :docs_path, :file_watcher, :config, :router, :renderer, :asset_handler
 
     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 +36,115 @@ 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?
+        render_documentation_page(result.file_path, path)
+      else
+        render_not_found_page
+      end
+    end
+
+    def render_documentation_page(file_path, current_path)
+      html = renderer.render_file(
+        file_path,
+        sidebar_html: build_sidebar(current_path),
+        branding: branding_options
+      )
+
+      [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
+    end
+
+    def render_not_found_page
+      html = renderer.render_not_found
+      [Constants::STATUS_NOT_FOUND, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
+    end
+
+    def build_sidebar(current_path)
+      SidebarBuilder.new(
+        docs_path: docs_path,
+        current_path: current_path,
+        config: config
+      ).to_html
+    end
+
+    def branding_options
+      return default_branding unless config
+
+      default_branding.merge(config_branding_options)
+    end
+
+    def default_branding
+      {
+        site_title: Constants::DEFAULT_SITE_TITLE,
+        site_description: "",
+        logo: Constants::DEFAULT_LOGO_PATH,
+        logo_dark: Constants::DEFAULT_LOGO_DARK_PATH,
+        favicon: nil,
+        display_logo: true,
+        display_title: true
+      }
+    end
+
+    def config_branding_options
+      site = config.site
+      branding = config.branding
+
+      {
+        site_title: site.title || Constants::DEFAULT_SITE_TITLE,
+        site_description: site.description || "",
+        logo: resolve_logo(branding.logo, branding.logo_dark),
+        logo_dark: resolve_logo_dark(branding.logo, branding.logo_dark),
+        favicon: branding.favicon
+      }.merge(appearance_options(branding.appearance))
+    end
+
+    def appearance_options(appearance)
+      appearance ||= {}
+      {
+        display_logo: appearance["logo"] != false,
+        display_title: appearance["title"] != false
+      }
+    end
+
+    def resolve_logo(logo, logo_dark)
+      logo || logo_dark || Constants::DEFAULT_LOGO_PATH
+    end
+
+    def resolve_logo_dark(logo, logo_dark)
+      logo_dark || logo || Constants::DEFAULT_LOGO_DARK_PATH
     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

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require "erb"
+require_relative "constants"
 
 module Docyard
   class Renderer
     LAYOUTS_PATH = File.join(__dir__, "templates", "layouts")
     ERRORS_PATH = File.join(__dir__, "templates", "errors")
+    PARTIALS_PATH = File.join(__dir__, "templates", "partials")
 
     attr_reader :layout_path
 
@@ -13,7 +15,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: "", branding: {})
       markdown_content = File.read(file_path)
       markdown = Markdown.new(markdown_content)
 
@@ -21,15 +23,17 @@ module Docyard
 
       render(
         content: html_content,
-        page_title: markdown.title || "Documentation"
+        page_title: markdown.title || Constants::DEFAULT_SITE_TITLE,
+        sidebar_html: sidebar_html,
+        branding: branding
       )
     end
 
-    def render(content:, page_title: "Documentation")
+    def render(content:, page_title: Constants::DEFAULT_SITE_TITLE, sidebar_html: "", branding: {})
       template = File.read(layout_path)
 
-      @content = content
-      @page_title = page_title
+      assign_content_variables(content, page_title, sidebar_html)
+      assign_branding_variables(branding)
 
       ERB.new(template).result(binding)
     end
@@ -50,8 +54,39 @@ module Docyard
       ERB.new(template).result(binding)
     end
 
+    def render_partial(name, locals = {})
+      partial_path = File.join(PARTIALS_PATH, "#{name}.html.erb")
+      template = File.read(partial_path)
+
+      locals.each { |key, value| instance_variable_set("@#{key}", value) }
+
+      ERB.new(template).result(binding)
+    end
+
+    def asset_path(path)
+      return path if path.nil? || path.start_with?("http://", "https://")
+
+      "/#{path}"
+    end
+
     private
 
+    def assign_content_variables(content, page_title, sidebar_html)
+      @content = content
+      @page_title = page_title
+      @sidebar_html = sidebar_html
+    end
+
+    def assign_branding_variables(branding)
+      @site_title = branding[:site_title] || Constants::DEFAULT_SITE_TITLE
+      @site_description = branding[:site_description] || ""
+      @logo = branding[:logo] || Constants::DEFAULT_LOGO_PATH
+      @logo_dark = branding[:logo_dark]
+      @favicon = branding[:favicon] || Constants::DEFAULT_FAVICON_PATH
+      @display_logo = branding[:display_logo].nil? || branding[:display_logo]
+      @display_title = branding[:display_title].nil? || branding[:display_title]
+    end
+
     def strip_md_from_links(html)
       html.gsub(/href="([^"]+)\.md"/, 'href="\1"')
     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/server.rb

@@ -4,22 +4,25 @@ require "webrick"
 require "stringio"
 require_relative "file_watcher"
 require_relative "rack_application"
+require_relative "config"
 
 module Docyard
   class Server
     DEFAULT_PORT = 4200
     DEFAULT_HOST = "localhost"
 
-    attr_reader :port, :host, :docs_path
+    attr_reader :port, :host, :docs_path, :config
 
     def initialize(port: DEFAULT_PORT, host: DEFAULT_HOST, docs_path: "docs")
       @port = port
       @host = host
       @docs_path = docs_path
+      @config = Config.load
       @file_watcher = FileWatcher.new(File.expand_path(docs_path))
       @app = RackApplication.new(
         docs_path: File.expand_path(docs_path),
-        file_watcher: @file_watcher
+        file_watcher: @file_watcher,
+        config: @config
       )
     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

data/lib/docyard/sidebar/tree_builder.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class TreeBuilder
+      attr_reader :docs_path, :current_path, :title_extractor
+
+      def initialize(docs_path:, current_path:, title_extractor: TitleExtractor.new)
+        @docs_path = docs_path
+        @current_path = Utils::PathResolver.normalize(current_path)
+        @title_extractor = title_extractor
+      end
+
+      def build(file_items)
+        transform_items(file_items, "")
+      end
+
+      private
+
+      def transform_items(items, relative_base)
+        items.map do |item|
+          if item[:type] == :directory
+            transform_directory(item, relative_base)
+          else
+            transform_file(item, relative_base)
+          end
+        end
+      end
+
+      def transform_directory(item, relative_base)
+        dir_path = File.join(relative_base, item[:name])
+
+        {
+          title: Utils::TextFormatter.titleize(item[:name]),
+          path: nil,
+          active: false,
+          type: :directory,
+          collapsible: true,
+          collapsed: false,
+          children: transform_items(item[:children], dir_path)
+        }
+      end
+
+      def transform_file(item, relative_base)
+        file_path = File.join(relative_base, "#{item[:name]}#{Constants::MARKDOWN_EXTENSION}")
+        full_file_path = File.join(docs_path, file_path)
+        url_path = Utils::PathResolver.to_url(file_path.delete_suffix(Constants::MARKDOWN_EXTENSION))
+
+        {
+          title: title_extractor.extract(full_file_path),
+          path: url_path,
+          active: current_path == url_path,
+          type: :file,
+          children: []
+        }
+      end
+    end
+  end
+end

data/lib/docyard/sidebar_builder.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "sidebar/file_system_scanner"
+require_relative "sidebar/title_extractor"
+require_relative "sidebar/tree_builder"
+require_relative "sidebar/renderer"
+
+module Docyard
+  class SidebarBuilder
+    attr_reader :docs_path, :current_path, :config
+
+    def initialize(docs_path:, current_path: "/", config: nil)
+      @docs_path = docs_path
+      @current_path = current_path
+      @config = config
+    end
+
+    def tree
+      @tree ||= build_tree
+    end
+
+    def to_html
+      renderer.render(tree)
+    end
+
+    private
+
+    def build_tree
+      file_items = scanner.scan
+      tree_builder.build(file_items)
+    end
+
+    def scanner
+      @scanner ||= Sidebar::FileSystemScanner.new(docs_path)
+    end
+
+    def tree_builder
+      @tree_builder ||= Sidebar::TreeBuilder.new(
+        docs_path: docs_path,
+        current_path: current_path
+      )
+    end
+
+    def renderer
+      @renderer ||= Sidebar::Renderer.new(
+        site_title: extract_site_title
+      )
+    end
+
+    def extract_site_title
+      if config.is_a?(Hash)
+        config[:site_title] || "Documentation"
+      else
+        config&.site&.title || "Documentation"
+      end
+    end
+  end
+end