docyard 0.9.0 → 1.0.1

data/lib/docyard/config.rb

@@ -1,36 +1,35 @@
 # frozen_string_literal: true
 
 require "yaml"
+require_relative "config/section"
+require_relative "config/schema"
 require_relative "config/validator"
-require_relative "config/constants"
+require_relative "constants"
+require_relative "utils/hash_utils"
 
 module Docyard
   class Config
+    SIDEBAR_MODES = %w[config auto distributed].freeze
+
     DEFAULT_CONFIG = {
       "title" => Constants::DEFAULT_SITE_TITLE,
       "description" => "",
-      "branding" => {
-        "logo" => nil,
-        "favicon" => nil,
-        "credits" => true,
-        "copyright" => nil
-      },
+      "url" => nil,
+      "og_image" => nil,
+      "twitter" => nil,
+      "source" => "docs",
+      "branding" => { "logo" => nil, "favicon" => nil, "credits" => true, "copyright" => nil, "color" => nil },
       "socials" => {},
       "tabs" => [],
-      "build" => {
-        "output" => "dist",
-        "base" => "/"
-      },
-      "search" => {
-        "enabled" => true,
-        "placeholder" => "Search...",
-        "exclude" => []
-      },
-      "navigation" => {
-        "cta" => [],
-        "breadcrumbs" => true
-      },
-      "announcement" => nil
+      "sidebar" => "config",
+      "build" => { "output" => "dist", "base" => "/" },
+      "search" => { "enabled" => true, "placeholder" => "Search...", "exclude" => [] },
+      "navigation" => { "cta" => [], "breadcrumbs" => true },
+      "announcement" => nil,
+      "repo" => { "url" => nil, "branch" => "main", "edit_path" => nil, "edit_link" => true,
+                  "last_updated" => true },
+      "analytics" => { "google" => nil, "plausible" => nil, "fathom" => nil, "script" => nil },
+      "feedback" => { "enabled" => false, "question" => "Was this page helpful?" }
     }.freeze
 
     attr_reader :data, :file_path
@@ -50,87 +49,50 @@ module Docyard
       File.exist?(file_path)
     end
 
-    def title
-      data["title"]
-    end
-
-    def description
-      data["description"]
-    end
-
-    def branding
-      @branding ||= ConfigSection.new(data["branding"])
-    end
-
-    def socials
-      data["socials"]
-    end
-
-    def tabs
-      data["tabs"]
-    end
-
-    def build
-      @build ||= ConfigSection.new(data["build"])
-    end
-
-    def search
-      @search ||= ConfigSection.new(data["search"])
-    end
-
-    def navigation
-      @navigation ||= ConfigSection.new(data["navigation"])
-    end
+    def title = data["title"]
+    def description = data["description"]
+    def url = data["url"]
+    def og_image = data["og_image"]
+    def twitter = data["twitter"]
+    def source = data["source"]
+    def public_dir = File.join(source, "public")
+    def socials = data["socials"]
+    def tabs = data["tabs"]
+    def sidebar = data["sidebar"]
+
+    def sidebar_config? = sidebar == "config"
+    def sidebar_auto? = sidebar == "auto"
+    def sidebar_distributed? = sidebar == "distributed"
+
+    def branding = @branding ||= Section.new(data["branding"])
+    def build = @build ||= Section.new(data["build"])
+    def search = @search ||= Section.new(data["search"])
+    def navigation = @navigation ||= Section.new(data["navigation"])
+    def repo = @repo ||= Section.new(data["repo"])
+    def analytics = @analytics ||= Section.new(data["analytics"])
+    def feedback = @feedback ||= Section.new(data["feedback"])
 
     def announcement
-      @announcement ||= data["announcement"] ? ConfigSection.new(data["announcement"]) : nil
+      @announcement ||= data["announcement"] ? Section.new(data["announcement"]) : nil
     end
 
     private
 
     def load_config_data
-      if file_exists?
-        load_and_merge_config
-      else
-        deep_dup(DEFAULT_CONFIG)
-      end
+      file_exists? ? load_and_merge_config : Utils::HashUtils.deep_dup(DEFAULT_CONFIG)
     end
 
     def load_and_merge_config
       yaml_content = YAML.load_file(file_path)
-      deep_merge(deep_dup(DEFAULT_CONFIG), yaml_content || {})
+      Utils::HashUtils.deep_merge(Utils::HashUtils.deep_dup(DEFAULT_CONFIG), yaml_content || {})
     rescue Psych::SyntaxError => e
       raise ConfigError, build_yaml_error_message(e)
     rescue StandardError => e
       raise ConfigError, "Error loading docyard.yml: #{e.message}"
     end
 
-    def deep_merge(hash1, hash2)
-      hash1.merge(hash2) do |_key, v1, v2|
-        if v2.nil?
-          v1
-        elsif v1.is_a?(Hash) && v2.is_a?(Hash)
-          deep_merge(v1, v2)
-        else
-          v2
-        end
-      end
-    end
-
-    def deep_dup(hash)
-      hash.transform_values do |value|
-        case value
-        when Hash then deep_dup(value)
-        when Array then value.map { |v| v.is_a?(Hash) ? deep_dup(v) : v }
-        else value
-        end
-      end
-    end
-
     def build_yaml_error_message(error)
-      message = "Invalid YAML in docyard.yml:\n\n"
-      message += "  #{error.message}\n\n"
-      message += "Fix: Check YAML syntax"
+      message = "Invalid YAML in docyard.yml:\n\n  #{error.message}\n\nFix: Check YAML syntax"
       message += " at line #{error.line}" if error.respond_to?(:line)
       message
     end
@@ -139,22 +101,4 @@ module Docyard
       Validator.new(data).validate!
     end
   end
-
-  class ConfigSection
-    def initialize(data)
-      @data = data || {}
-    end
-
-    def method_missing(method, *args)
-      return @data[method.to_s] if args.empty?
-
-      super
-    end
-
-    def respond_to_missing?(method, include_private = false)
-      @data.key?(method.to_s) || super
-    end
-  end
-
-  class ConfigError < StandardError; end
 end

data/lib/docyard/constants.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Constants
+    CONTENT_TYPE_HTML = "text/html; charset=utf-8"
+
+    DOCYARD_ASSETS_PREFIX = "/_docyard/"
+    PAGEFIND_PREFIX = "/_docyard/pagefind/"
+
+    INDEX_FILE = "index"
+    MARKDOWN_EXTENSION = ".md"
+
+    STATUS_OK = 200
+    STATUS_REDIRECT = 302
+    STATUS_NOT_FOUND = 404
+    STATUS_INTERNAL_ERROR = 500
+
+    DEFAULT_SITE_TITLE = "Documentation"
+    DEFAULT_LOGO_PATH = "_docyard/logo.svg"
+    DEFAULT_LOGO_DARK_PATH = "_docyard/logo-dark.svg"
+    DEFAULT_FAVICON_PATH = "_docyard/favicon.svg"
+
+    SOCIAL_ICON_MAP = {
+      "github" => "github-logo",
+      "x" => "x-logo",
+      "twitter" => "x-logo",
+      "discord" => "discord-logo",
+      "slack" => "slack-logo",
+      "linkedin" => "linkedin-logo",
+      "youtube" => "youtube-logo",
+      "twitch" => "twitch-logo",
+      "instagram" => "instagram-logo",
+      "facebook" => "facebook-logo",
+      "tiktok" => "tiktok-logo",
+      "reddit" => "reddit-logo",
+      "mastodon" => "mastodon-logo",
+      "threads" => "threads-logo",
+      "pinterest" => "pinterest-logo",
+      "medium" => "medium-logo",
+      "gitlab" => "gitlab-logo",
+      "figma" => "figma-logo",
+      "dribbble" => "dribbble-logo",
+      "behance" => "behance-logo",
+      "codepen" => "codepen-logo",
+      "codesandbox" => "codesandbox-logo",
+      "notion" => "notion-logo",
+      "spotify" => "spotify-logo",
+      "soundcloud" => "soundcloud-logo",
+      "whatsapp" => "whatsapp-logo",
+      "telegram" => "telegram-logo",
+      "snapchat" => "snapchat-logo",
+      "patreon" => "patreon-logo",
+      "paypal" => "paypal-logo",
+      "stripe" => "stripe-logo",
+      "google-podcasts" => "google-podcasts-logo",
+      "apple-podcasts" => "apple-podcasts-logo"
+    }.freeze
+  end
+end

data/lib/docyard/{utils/errors.rb → errors.rb}

@@ -3,6 +3,10 @@
 module Docyard
   class Error < StandardError; end
 
+  class ConfigError < Error; end
+
+  class SidebarConfigError < Error; end
+
   class FileNotFoundError < Error
     attr_reader :path
 
@@ -51,4 +55,6 @@ module Docyard
       super("Asset not found: #{asset_path}")
     end
   end
+
+  class BuildError < Error; end
 end

data/lib/docyard/initializer.rb

@@ -5,19 +5,21 @@ require "fileutils"
 module Docyard
   class Initializer
     DOCS_DIR = "docs"
-    CONFIG_TEMPLATE_DIR = File.join(__dir__, "templates", "config")
+    TEMPLATES_DIR = File.join(__dir__, "templates", "init")
 
-    def initialize(path = ".")
-      @path = path
-      @docs_path = File.join(@path, DOCS_DIR)
+    attr_reader :project_name, :project_path, :docs_path, :force
+
+    def initialize(project_name = nil, force: false)
+      @project_name = project_name
+      @project_path = project_name ? File.join(".", project_name) : "."
+      @docs_path = File.join(@project_path, DOCS_DIR)
+      @force = force
     end
 
-    def run
-      if already_initialized?
-        print_already_exists_error
-        return
-      end
+    def run # rubocop:disable Naming/PredicateMethod
+      return false unless check_existing_files
 
+      create_project_directory if project_name
       create_structure
       print_success
       true
@@ -25,74 +27,123 @@ module Docyard
 
     private
 
-    def already_initialized?
-      File.exist?(@docs_path)
+    def check_existing_files # rubocop:disable Naming/PredicateMethod
+      return true if force
+      return true unless files_exist?
+
+      print_existing_files_warning
+      return true if user_confirms_overwrite?
+
+      print_abort_message
+      false
     end
 
-    def create_structure
-      FileUtils.mkdir_p(@docs_path)
-      create_index_file
-      create_example_config
+    def files_exist?
+      File.exist?(docs_path) || File.exist?(config_path)
     end
 
-    def create_index_file
-      index_path = File.join(@docs_path, "index.md")
-      content = <<~MARKDOWN
-        ---
-        title: Welcome
-        ---
+    def config_path
+      File.join(project_path, "docyard.yml")
+    end
 
-        # Welcome to Your Documentation
+    def user_confirms_overwrite?
+      print "\nOverwrite existing files? [y/N] "
+      response = $stdin.gets&.strip&.downcase
+      %w[y yes].include?(response)
+    end
 
-        Start writing your documentation here.
-      MARKDOWN
-      File.write(index_path, content)
+    def print_existing_files_warning
+      puts ""
+      puts "\e[33mWarning:\e[0m Existing files found:"
+      puts "  - #{docs_path}/" if File.exist?(docs_path)
+      puts "  - #{config_path}" if File.exist?(config_path)
     end
 
-    def create_example_config
-      config_path = File.join(@path, "docyard.yml")
-      return if File.exist?(config_path)
+    def print_abort_message
+      puts ""
+      puts "Aborted. Use \e[1m--force\e[0m to overwrite existing files."
+    end
 
-      template_path = File.join(CONFIG_TEMPLATE_DIR, "docyard.yml.erb")
-      config_content = File.read(template_path)
+    def create_project_directory
+      FileUtils.mkdir_p(project_path)
+    end
 
-      File.write(config_path, config_content)
+    def create_structure
+      FileUtils.mkdir_p(docs_path)
+      FileUtils.mkdir_p(File.join(docs_path, "public"))
+      create_config_file
+      create_sidebar_file
+      create_starter_pages
     end
 
-    def print_already_exists_error
-      puts "Error: #{DOCS_DIR}/ folder already exists"
-      puts "   Remove it first or run docyard in a different directory"
+    def create_config_file
+      template = File.read(File.join(TEMPLATES_DIR, "docyard.yml"))
+      content = template.gsub("{{PROJECT_NAME}}", display_name)
+      File.write(config_path, content)
     end
 
-    def print_success
-      print_banner
-      print_created_files
-      print_next_steps
+    def create_sidebar_file
+      template = File.read(File.join(TEMPLATES_DIR, "_sidebar.yml"))
+      File.write(File.join(docs_path, "_sidebar.yml"), template)
+    end
+
+    def create_starter_pages
+      pages_dir = File.join(TEMPLATES_DIR, "pages")
+      Dir.glob(File.join(pages_dir, "*.md")).each do |template_path|
+        filename = File.basename(template_path)
+        content = File.read(template_path).gsub("{{PROJECT_NAME}}", display_name)
+        File.write(File.join(docs_path, filename), content)
+      end
+    end
+
+    def display_name
+      return "My Documentation" unless project_name
+
+      project_name.split(/[-_]/).map(&:capitalize).join(" ")
     end
 
-    def print_banner
+    def print_success
       puts ""
-      puts "Docyard initialized successfully"
+      puts "\e[32m#{success_icon} Docyard project initialized successfully!\e[0m"
       puts ""
+      print_created_structure
+      print_next_steps
+    end
+
+    def success_icon
+      "\u2714"
     end
 
-    def print_created_files
-      puts "Created files:"
+    def print_created_structure
+      puts "Created:"
       puts ""
-      puts "  docs/"
-      puts "    index.md"
-      puts "  docyard.yml"
+      if project_name
+        puts "  \e[1m#{project_name}/\e[0m"
+        puts "  \u251C\u2500\u2500 docyard.yml"
+        puts "  \u2514\u2500\u2500 docs/"
+      else
+        puts "  \e[1mdocyard.yml\e[0m"
+        puts "  \e[1mdocs/\e[0m"
+      end
+      puts "      \u251C\u2500\u2500 _sidebar.yml"
+      puts "      \u251C\u2500\u2500 index.md"
+      puts "      \u251C\u2500\u2500 getting-started.md"
+      puts "      \u251C\u2500\u2500 components.md"
+      puts "      \u2514\u2500\u2500 public/"
       puts ""
     end
 
     def print_next_steps
       puts "Next steps:"
       puts ""
-      puts "  Start development server:"
-      puts "    docyard serve"
+      if project_name
+        puts "  \e[1mcd #{project_name}\e[0m"
+        puts ""
+      end
+      puts "  Start the development server:"
+      puts "  \e[1m$ docyard serve\e[0m"
       puts ""
-      puts "  Build for production:"
-      puts "    docyard build"
+      puts "  Then open \e[4mhttp://localhost:4200\e[0m in your browser"
       puts ""
     end
   end

data/lib/docyard/navigation/breadcrumb_builder.rb

@@ -76,9 +76,10 @@ module Docyard
     def search_in_ancestors(node, path, title, href)
       return unless node[:children]&.any?
 
-      effective_href = href == "/" ? derive_section_path(node) : href
-      return unless path_is_ancestor?(effective_href)
+      section_path = derive_section_path(node, href)
+      return unless path_is_ancestor?(section_path)
 
+      effective_href = resolve_section_href(node, href, section_path)
       result = find_breadcrumb_path(
         node[:children],
         path + [Item.new(title: title, href: effective_href, current: false)]
@@ -86,14 +87,52 @@ module Docyard
       result.any? ? result : nil
     end
 
-    def derive_section_path(node)
-      first_child = node[:children]&.first
+    def derive_section_path(node, href)
+      return href if section_has_index?(href)
+
+      derive_section_path_from_children(node[:children])
+    end
+
+    def derive_section_path_from_children(children)
+      first_child = children&.first
       return nil unless first_child
 
       child_path = first_child[:path]
-      return nil if child_path.nil? || child_path.empty?
+      return nil unless navigable_path?(child_path)
+
+      parent_dir = File.dirname(child_path)
+      root_parent?(parent_dir) ? child_path : parent_dir
+    end
+
+    def root_parent?(parent_dir)
+      parent_dir == "/" || parent_dir.empty?
+    end
+
+    def resolve_section_href(node, href, section_path)
+      return href if section_has_index?(href)
+
+      find_first_navigable_child(node[:children]) || section_path
+    end
+
+    def section_has_index?(path)
+      path && !path.empty? && path != "/"
+    end
+
+    def find_first_navigable_child(children)
+      return nil unless children&.any?
+
+      children.each do |child|
+        return child[:path] if navigable_path?(child[:path])
+
+        nested = find_first_navigable_child(child[:children])
+        return nested if nested
+      end
+
+      nil
+    end
 
-      File.dirname(child_path)
+    def navigable_path?(path)
+      path && !path.empty? && path != "/"
     end
 
     def search_in_children(node, path)

data/lib/docyard/navigation/page_navigation_builder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "sidebar_builder"
+require_relative "prev_next_builder"
+require_relative "breadcrumb_builder"
+
+module Docyard
+  module Navigation
+    class PageNavigationBuilder
+      def initialize(docs_path:, config:, sidebar_cache: nil)
+        @docs_path = docs_path
+        @config = config
+        @sidebar_cache = sidebar_cache
+      end
+
+      def build(current_path:, markdown:, header_ctas: [], show_sidebar: true)
+        return empty_navigation unless show_sidebar
+
+        sidebar_builder = build_sidebar(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
+
+      private
+
+      attr_reader :docs_path, :config, :sidebar_cache
+
+      def empty_navigation
+        { sidebar_html: "", prev_next_html: "", breadcrumbs: nil }
+      end
+
+      def build_sidebar(current_path, header_ctas)
+        SidebarBuilder.new(
+          docs_path: docs_path,
+          current_path: current_path,
+          config: config,
+          header_ctas: header_ctas,
+          sidebar_cache: sidebar_cache
+        )
+      end
+
+      def build_prev_next(sidebar_builder, current_path, markdown)
+        PrevNextBuilder.new(
+          sidebar_tree: sidebar_builder.tree,
+          current_path: current_path,
+          frontmatter: markdown.frontmatter,
+          config: {}
+        ).to_html
+      end
+
+      def build_breadcrumbs(sidebar_tree, current_path)
+        return nil unless breadcrumbs_enabled?
+
+        BreadcrumbBuilder.new(sidebar_tree: sidebar_tree, current_path: current_path)
+      end
+
+      def breadcrumbs_enabled?
+        config&.navigation&.breadcrumbs != false
+      end
+    end
+  end
+end