docyard 0.7.0 → 0.8.0

data/lib/docyard/routing/fallback_resolver.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Routing
+    class FallbackResolver
+      attr_reader :docs_path, :sidebar_builder
+
+      def initialize(docs_path:, sidebar_builder:)
+        @docs_path = docs_path
+        @sidebar_builder = sidebar_builder
+      end
+
+      def resolve_fallback(request_path)
+        return nil if file_exists?(request_path)
+
+        find_first_item_in_section(request_path)
+      end
+
+      private
+
+      def file_exists?(request_path)
+        clean_path = sanitize_path(request_path)
+
+        file_path = File.join(docs_path, "#{clean_path}.md")
+        return true if File.file?(file_path)
+
+        index_path = File.join(docs_path, clean_path, "index.md")
+        File.file?(index_path)
+      end
+
+      def sanitize_path(request_path)
+        clean = request_path.to_s.delete_prefix("/").delete_suffix("/")
+        clean = "index" if clean.empty?
+        clean.delete_suffix(".md")
+      end
+
+      def find_first_item_in_section(request_path)
+        tree = sidebar_builder.tree
+
+        if root_path?(request_path)
+          find_first_navigable_item(tree)
+        else
+          section = find_section_in_tree(tree, request_path)
+          section ? find_first_navigable_item(section[:children] || []) : nil
+        end
+      end
+
+      def root_path?(request_path)
+        request_path.nil? || request_path == "/" || request_path.empty?
+      end
+
+      def find_section_in_tree(tree, path)
+        normalized_path = normalize_path(path)
+
+        tree.each do |item|
+          return item if path_matches_section?(item, normalized_path)
+
+          if item[:children]&.any?
+            found = find_section_in_tree(item[:children], path)
+            return found if found
+          end
+        end
+
+        nil
+      end
+
+      def normalize_path(path)
+        path.to_s.delete_prefix("/").delete_suffix("/").downcase
+      end
+
+      def path_matches_section?(item, normalized_path)
+        return false unless item[:type] == :directory
+
+        item_path = item[:title].to_s.downcase.gsub(/\s+/, "-")
+        item_path == normalized_path
+      end
+
+      def find_first_navigable_item(items)
+        items.each do |item|
+          return item[:path] if item[:path] && item[:type] == :file
+
+          if item[:children]&.any?
+            found = find_first_navigable_item(item[:children])
+            return found if found
+          end
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/docyard/search/build_indexer.rb

@@ -13,7 +13,7 @@ module Docyard
 
       def initialize(config, verbose: false)
         @config = config
-        @output_dir = config.build.output_dir
+        @output_dir = config.build.output
         @verbose = verbose
       end
 

data/lib/docyard/search/dev_indexer.rb

@@ -25,10 +25,10 @@ module Docyard
 
         @temp_dir = Dir.mktmpdir("docyard-search-")
         generate_html_files
-        run_pagefind
+        page_count = run_pagefind
         @pagefind_path = File.join(temp_dir, "pagefind")
 
-        log_success
+        log_success(page_count)
         pagefind_path
       rescue StandardError => e
         warn "[!] Search index generation failed: #{e.message}"
@@ -52,6 +52,8 @@ module Docyard
 
       def generate_html_files
         markdown_files = Dir.glob(File.join(docs_path, "**", "*.md"))
+        markdown_files = filter_excluded_files(markdown_files)
+        markdown_files = filter_non_indexable_files(markdown_files)
         renderer = Renderer.new(base_url: "/", config: config)
 
         progress = TTY::ProgressBar.new(
@@ -66,6 +68,45 @@ module Docyard
         end
       end
 
+      def filter_excluded_files(files)
+        exclude_patterns = config.search.exclude || []
+        return files if exclude_patterns.empty?
+
+        files.reject do |file_path|
+          url_path = file_to_url_path(file_path)
+          exclude_patterns.any? { |pattern| File.fnmatch(pattern, url_path, File::FNM_PATHNAME) }
+        end
+      end
+
+      def filter_non_indexable_files(files)
+        files.reject do |file_path|
+          content = File.read(file_path)
+          markdown = Markdown.new(content)
+          frontmatter = markdown.frontmatter
+
+          uses_splash_template?(frontmatter)
+        end
+      end
+
+      def uses_splash_template?(frontmatter)
+        return true if frontmatter["template"] == "splash"
+        return true if frontmatter.key?("landing")
+
+        frontmatter.key?("hero") || frontmatter.key?("features")
+      end
+
+      def file_to_url_path(file_path)
+        relative_path = file_path.delete_prefix("#{docs_path}/")
+        base_name = File.basename(relative_path, ".md")
+        dir_name = File.dirname(relative_path)
+
+        if base_name == "index"
+          dir_name == "." ? "/" : "/#{dir_name}"
+        else
+          dir_name == "." ? "/#{base_name}" : "/#{dir_name}/#{base_name}"
+        end
+      end
+
       def generate_html_file(markdown_file, renderer)
         relative_path = markdown_file.delete_prefix("#{docs_path}/")
         output_path = determine_output_path(relative_path)
@@ -97,12 +138,16 @@ module Docyard
 
         raise "Pagefind failed: #{stderr}" unless status.success?
 
-        stdout
+        extract_page_count(stdout)
+      end
+
+      def extract_page_count(output)
+        match = output.match(/Indexed (\d+) page/i)
+        match ? match[1].to_i : 0
       end
 
-      def log_success
-        page_count = Dir.glob(File.join(temp_dir, "**", "*.html")).size
-        puts "=> Search index generated (#{page_count} pages)"
+      def log_success(page_count)
+        puts "=> Search index generated (#{page_count} pages indexed)"
         puts "=> Temp directory: #{temp_dir}" if ENV["DOCYARD_DEBUG"]
       end
     end

data/lib/docyard/search/pagefind_support.rb

@@ -21,6 +21,8 @@ module Docyard
 
         exclusions = config.search.exclude || []
         exclusions.each do |pattern|
+          next if pattern.start_with?("/")
+
           args += ["--exclude-selectors", pattern]
         end
 

data/lib/docyard/server/asset_handler.rb

@@ -2,8 +2,7 @@
 
 module Docyard
   class AssetHandler
-    ASSETS_PATH = File.join(__dir__, "../templates", "assets")
-    USER_ASSETS_PATH = "docs/assets"
+    TEMPLATES_ASSETS_PATH = File.join(__dir__, "../templates", "assets")
 
     CONTENT_TYPES = {
       ".css" => "text/css; charset=utf-8",
@@ -11,41 +10,47 @@ module Docyard
       ".png" => "image/png",
       ".jpg" => "image/jpeg",
       ".jpeg" => "image/jpeg",
+      ".gif" => "image/gif",
+      ".webp" => "image/webp",
       ".svg" => "image/svg+xml",
-      ".woff" => "font/woff2",
+      ".woff" => "font/woff",
       ".woff2" => "font/woff2",
-      ".ico" => "image/x-icon"
+      ".ttf" => "font/ttf",
+      ".ico" => "image/x-icon",
+      ".pdf" => "application/pdf",
+      ".mp4" => "video/mp4",
+      ".webm" => "video/webm"
     }.freeze
 
-    def serve(request_path)
-      asset_path = extract_asset_path(request_path)
+    def serve_docyard_assets(request_path)
+      asset_path = request_path.delete_prefix("/_docyard/")
 
       return forbidden_response if directory_traversal?(asset_path)
 
       return serve_components_css if asset_path == "css/components.css"
       return serve_components_js if asset_path == "js/components.js"
 
-      file_path = build_file_path(asset_path)
+      file_path = File.join(TEMPLATES_ASSETS_PATH, asset_path)
       return not_found_response unless File.file?(file_path)
 
       serve_file(file_path)
     end
 
-    private
+    def serve_public_file(request_path)
+      asset_path = request_path.delete_prefix("/")
 
-    def extract_asset_path(request_path)
-      request_path.delete_prefix("/assets/")
-    end
+      return nil if directory_traversal?(asset_path)
 
-    def directory_traversal?(path)
-      path.include?("..")
+      file_path = File.join(Constants::PUBLIC_DIR, asset_path)
+      return nil unless File.file?(file_path)
+
+      serve_file(file_path)
     end
 
-    def build_file_path(asset_path)
-      user_path = File.join(USER_ASSETS_PATH, asset_path)
-      return user_path if File.file?(user_path)
+    private
 
-      File.join(ASSETS_PATH, asset_path)
+    def directory_traversal?(path)
+      path.include?("..")
     end
 
     def serve_file(file_path)
@@ -61,7 +66,7 @@ module Docyard
     end
 
     def concatenate_component_css
-      components_dir = File.join(ASSETS_PATH, "css", "components")
+      components_dir = File.join(TEMPLATES_ASSETS_PATH, "css", "components")
       return "" unless Dir.exist?(components_dir)
 
       css_files = Dir.glob(File.join(components_dir, "*.css"))
@@ -74,7 +79,7 @@ module Docyard
     end
 
     def concatenate_component_js
-      components_dir = File.join(ASSETS_PATH, "js", "components")
+      components_dir = File.join(TEMPLATES_ASSETS_PATH, "js", "components")
       return "" unless Dir.exist?(components_dir)
 
       js_files = Dir.glob(File.join(components_dir, "*.js"))

data/lib/docyard/server/pagefind_handler.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Docyard
+  class PagefindHandler
+    CONTENT_TYPES = {
+      ".js" => "application/javascript; charset=utf-8",
+      ".css" => "text/css; charset=utf-8",
+      ".json" => "application/json; charset=utf-8"
+    }.freeze
+
+    def initialize(pagefind_path:, config:)
+      @pagefind_path = pagefind_path
+      @config = config
+    end
+
+    def serve(path)
+      relative_path = path.delete_prefix(Constants::PAGEFIND_PREFIX)
+      return not_found if relative_path.include?("..")
+
+      file_path = resolve_file(relative_path)
+      return not_found unless file_path && File.file?(file_path)
+
+      serve_file(file_path)
+    end
+
+    private
+
+    attr_reader :pagefind_path, :config
+
+    def resolve_file(relative_path)
+      return File.join(pagefind_path, relative_path) if pagefind_path && Dir.exist?(pagefind_path)
+
+      output_dir = config&.build&.output_dir || "dist"
+      File.join(output_dir, "pagefind", relative_path)
+    end
+
+    def serve_file(file_path)
+      content = File.binread(file_path)
+      content_type = content_type_for(file_path)
+
+      [Constants::STATUS_OK, build_headers(content_type), [content]]
+    end
+
+    def build_headers(content_type)
+      {
+        "Content-Type" => content_type,
+        "Cache-Control" => "no-cache, no-store, must-revalidate",
+        "Pragma" => "no-cache",
+        "Expires" => "0"
+      }
+    end
+
+    def content_type_for(file_path)
+      extension = File.extname(file_path)
+      CONTENT_TYPES.fetch(extension, "application/octet-stream")
+    end
+
+    def not_found
+      message = "Pagefind not found. Run 'docyard build' first."
+      [Constants::STATUS_NOT_FOUND, { "Content-Type" => "text/plain" }, [message]]
+    end
+  end
+end

data/lib/docyard/server/preview_server.rb

@@ -12,7 +12,7 @@ module Docyard
     def initialize(port: DEFAULT_PORT)
       @port = port
       @config = Config.load
-      @output_dir = File.expand_path(@config.build.output_dir)
+      @output_dir = File.expand_path(@config.build.output)
     end
 
     def start

data/lib/docyard/server/rack_application.rb

@@ -4,25 +4,23 @@ require "json"
 require "rack"
 require_relative "../navigation/sidebar_builder"
 require_relative "../navigation/prev_next_builder"
+require_relative "../navigation/breadcrumb_builder"
 require_relative "../config/branding_resolver"
 require_relative "../config/constants"
+require_relative "../rendering/template_resolver"
+require_relative "../routing/fallback_resolver"
+require_relative "pagefind_handler"
 
 module Docyard
   class RackApplication
-    PAGEFIND_CONTENT_TYPES = {
-      ".js" => "application/javascript; charset=utf-8",
-      ".css" => "text/css; charset=utf-8",
-      ".json" => "application/json; charset=utf-8"
-    }.freeze
-
     def initialize(docs_path:, file_watcher:, config: nil, pagefind_path: nil)
       @docs_path = docs_path
       @file_watcher = file_watcher
       @config = config
-      @pagefind_path = pagefind_path
       @router = Router.new(docs_path: docs_path)
-      @renderer = Renderer.new(base_url: config&.build&.base_url || "/", config: config)
+      @renderer = Renderer.new(base_url: config&.build&.base || "/", config: config)
       @asset_handler = AssetHandler.new
+      @pagefind_handler = PagefindHandler.new(pagefind_path: pagefind_path, config: config)
     end
 
     def call(env)
@@ -31,14 +29,17 @@ module Docyard
 
     private
 
-    attr_reader :docs_path, :file_watcher, :config, :pagefind_path, :router, :renderer, :asset_handler
+    attr_reader :docs_path, :file_watcher, :config, :router, :renderer, :asset_handler, :pagefind_handler
 
     def handle_request(env)
       path = env["PATH_INFO"]
 
       return handle_reload_check(env) if path == Constants::RELOAD_ENDPOINT
-      return asset_handler.serve(path) if path.start_with?(Constants::ASSETS_PREFIX)
-      return serve_pagefind(path) if path.start_with?(Constants::PAGEFIND_PREFIX)
+      return asset_handler.serve_docyard_assets(path) if path.start_with?(Constants::DOCYARD_ASSETS_PREFIX)
+      return pagefind_handler.serve(path) if path.start_with?(Constants::PAGEFIND_PREFIX)
+
+      public_response = asset_handler.serve_public_file(path)
+      return public_response if public_response
 
       handle_documentation_request(path)
     rescue StandardError => e
@@ -46,45 +47,90 @@ module Docyard
     end
 
     def handle_documentation_request(path)
+      if root_path?(path)
+        html_response = serve_custom_landing_page
+        return html_response if html_response
+      end
+
       result = router.resolve(path)
 
       if result.found?
         render_documentation_page(result.file_path, path)
+      else
+        try_fallback_redirect(path)
+      end
+    end
+
+    def root_path?(path)
+      path == "/" || path.empty?
+    end
+
+    def serve_custom_landing_page
+      html_path = File.join(docs_path, "index.html")
+      return nil unless File.file?(html_path)
+
+      html = File.read(html_path)
+      [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
+    end
+
+    def try_fallback_redirect(path)
+      sidebar_builder = build_sidebar_instance(path)
+      fallback_resolver = Routing::FallbackResolver.new(
+        docs_path: docs_path,
+        sidebar_builder: sidebar_builder
+      )
+
+      fallback_path = fallback_resolver.resolve_fallback(path)
+      if fallback_path
+        redirect_to(fallback_path)
       else
         render_not_found_page
       end
     end
 
+    def redirect_to(path)
+      [Constants::STATUS_REDIRECT, { "Location" => path }, []]
+    end
+
     def render_documentation_page(file_path, current_path)
-      sidebar_builder = build_sidebar_instance(current_path)
+      markdown = Markdown.new(File.read(file_path))
+      template_resolver = TemplateResolver.new(markdown.frontmatter, @config&.data)
+      branding = branding_options
 
-      html = renderer.render_file(
-        file_path,
-        sidebar_html: sidebar_builder.to_html,
-        prev_next_html: build_prev_next(sidebar_builder, current_path, file_path),
-        branding: branding_options
-      )
+      navigation = build_navigation_html(template_resolver, current_path, markdown, branding[:header_ctas])
+      html = renderer.render_file(file_path, **navigation, branding: branding,
+                                                           template_options: template_resolver.to_options,
+                                                           current_path: current_path)
 
       [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
     end
 
+    def build_navigation_html(template_resolver, current_path, markdown, header_ctas)
+      return { sidebar_html: "", prev_next_html: "", breadcrumbs: nil } unless template_resolver.show_sidebar?
+
+      sidebar_builder = build_sidebar_instance(current_path, header_ctas)
+      {
+        sidebar_html: sidebar_builder.to_html,
+        prev_next_html: build_prev_next(sidebar_builder, current_path, markdown),
+        breadcrumbs: build_breadcrumbs(sidebar_builder.tree, current_path)
+      }
+    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_instance(current_path)
+    def build_sidebar_instance(current_path, header_ctas = [])
       SidebarBuilder.new(
         docs_path: docs_path,
         current_path: current_path,
-        config: config
+        config: config,
+        header_ctas: header_ctas
       )
     end
 
-    def build_prev_next(sidebar_builder, current_path, file_path)
-      markdown_content = File.read(file_path)
-      markdown = Markdown.new(markdown_content)
-
+    def build_prev_next(sidebar_builder, current_path, markdown)
       PrevNextBuilder.new(
         sidebar_tree: sidebar_builder.tree,
         current_path: current_path,
@@ -93,10 +139,18 @@ module Docyard
       ).to_html
     end
 
-    def navigation_config
-      return {} unless config
+    def build_breadcrumbs(sidebar_tree, current_path)
+      return nil unless breadcrumbs_enabled?
+
+      BreadcrumbBuilder.new(sidebar_tree: sidebar_tree, current_path: current_path)
+    end
 
-      config.navigation&.footer || {}
+    def breadcrumbs_enabled?
+      config&.navigation&.breadcrumbs != false
+    end
+
+    def navigation_config
+      {}
     end
 
     def branding_options
@@ -134,42 +188,5 @@ module Docyard
       [Constants::STATUS_INTERNAL_ERROR, { "Content-Type" => Constants::CONTENT_TYPE_HTML },
        [renderer.render_server_error(error)]]
     end
-
-    def serve_pagefind(path)
-      relative_path = path.delete_prefix(Constants::PAGEFIND_PREFIX)
-      return pagefind_not_found if relative_path.include?("..")
-
-      file_path = resolve_pagefind_file(relative_path)
-      return pagefind_not_found unless file_path && File.file?(file_path)
-
-      content = File.binread(file_path)
-      content_type = pagefind_content_type(file_path)
-
-      headers = {
-        "Content-Type" => content_type,
-        "Cache-Control" => "no-cache, no-store, must-revalidate",
-        "Pragma" => "no-cache",
-        "Expires" => "0"
-      }
-
-      [Constants::STATUS_OK, headers, [content]]
-    end
-
-    def resolve_pagefind_file(relative_path)
-      return File.join(pagefind_path, relative_path) if pagefind_path && Dir.exist?(pagefind_path)
-
-      output_dir = config&.build&.output_dir || "dist"
-      File.join(output_dir, "pagefind", relative_path)
-    end
-
-    def pagefind_content_type(file_path)
-      extension = File.extname(file_path)
-      PAGEFIND_CONTENT_TYPES.fetch(extension, "application/octet-stream")
-    end
-
-    def pagefind_not_found
-      message = "Pagefind not found. Run 'docyard build' first."
-      [Constants::STATUS_NOT_FOUND, { "Content-Type" => "text/plain" }, [message]]
-    end
   end
 end