docyard 0.8.0 → 1.0.0

data/lib/docyard/config/validators/navigation.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Config
+    module Validators
+      module Navigation
+        private
+
+        def validate_navigation_section
+          cta = @config.dig("navigation", "cta")
+          return if cta.nil?
+          return add_array_error("navigation.cta") unless cta.is_a?(Array)
+
+          validate_cta_max_count(cta)
+          validate_cta_items(cta)
+        end
+
+        def validate_cta_items(cta)
+          cta.each_with_index do |item, idx|
+            validate_string(item["text"], "navigation.cta[#{idx}].text")
+            validate_string(item["href"], "navigation.cta[#{idx}].href")
+            validate_cta_variant(item["variant"], idx) if item.key?("variant")
+            validate_boolean(item["external"], "navigation.cta[#{idx}].external") if item.key?("external")
+          end
+        end
+
+        def validate_cta_max_count(cta)
+          return if cta.length <= 2
+
+          add_error(field: "navigation.cta", error: "maximum 2 CTAs allowed",
+                    got: "#{cta.length} items", fix: "Remove extra CTA items to have at most 2")
+        end
+
+        def validate_cta_variant(variant, idx)
+          return if variant.nil? || %w[primary secondary].include?(variant)
+
+          add_error(field: "navigation.cta[#{idx}].variant", error: "must be 'primary' or 'secondary'",
+                    got: variant, fix: "Change to 'primary' or 'secondary'")
+        end
+      end
+    end
+  end
+end

data/lib/docyard/config/validators/section.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Config
+    module Validators
+      module Section
+        private
+
+        def validate_top_level
+          validate_string(@config["title"], "title")
+          validate_string(@config["description"], "description")
+        end
+
+        def validate_branding_section
+          branding = @config["branding"]
+          return unless branding
+
+          validate_file_path_or_url(branding["logo"], "branding.logo")
+          validate_file_path_or_url(branding["favicon"], "branding.favicon")
+          validate_boolean(branding["credits"], "branding.credits") if branding.key?("credits")
+        end
+
+        def validate_socials_section
+          socials = @config["socials"]
+          return unless socials
+          return add_hash_error("socials") unless socials.is_a?(Hash)
+
+          socials.each { |platform, url| validate_url(url, "socials.#{platform}") unless platform == "custom" }
+          validate_custom_socials(socials["custom"]) if socials.key?("custom")
+        end
+
+        def validate_custom_socials(custom)
+          return if custom.nil?
+          return add_array_error("socials.custom") unless custom.is_a?(Array)
+
+          custom.each_with_index do |item, index|
+            validate_string(item["icon"], "socials.custom[#{index}].icon")
+            validate_url(item["href"], "socials.custom[#{index}].href")
+          end
+        end
+
+        def validate_tabs_section
+          tabs = @config["tabs"]
+          return unless tabs
+          return add_array_error("tabs") unless tabs.is_a?(Array)
+
+          tabs.each_with_index do |tab, index|
+            validate_string(tab["text"], "tabs[#{index}].text")
+            validate_string(tab["href"], "tabs[#{index}].href")
+            validate_boolean(tab["external"], "tabs[#{index}].external") if tab.key?("external")
+          end
+        end
+
+        def validate_sidebar_setting
+          sidebar = @config["sidebar"]
+          return if sidebar.nil? || Config::SIDEBAR_MODES.include?(sidebar)
+
+          add_error(
+            field: "sidebar",
+            error: "must be one of: #{Config::SIDEBAR_MODES.join(', ')}",
+            got: sidebar.inspect,
+            fix: "Change to 'config', 'auto', or 'distributed'"
+          )
+        end
+
+        def validate_build_section
+          build = @config["build"]
+          return unless build
+
+          validate_string(build["output"], "build.output")
+          validate_no_slashes(build["output"], "build.output")
+          validate_string(build["base"], "build.base")
+          validate_starts_with_slash(build["base"], "build.base")
+        end
+
+        def validate_search_section
+          search = @config["search"]
+          return unless search
+
+          validate_boolean(search["enabled"], "search.enabled") if search.key?("enabled")
+          validate_string(search["placeholder"], "search.placeholder") if search.key?("placeholder")
+          validate_array(search["exclude"], "search.exclude") if search.key?("exclude")
+        end
+
+        def validate_announcement_section
+          announcement = @config["announcement"]
+          return unless announcement.is_a?(Hash)
+
+          validate_string(announcement["text"], "announcement.text") if announcement.key?("text")
+        end
+
+        def validate_feedback_section
+          feedback = @config["feedback"]
+          return unless feedback.is_a?(Hash) && feedback["enabled"] == true
+          return if analytics_configured?
+
+          add_error(
+            field: "feedback.enabled",
+            error: "requires analytics to be configured",
+            got: "feedback enabled without analytics",
+            fix: "Configure analytics (google, plausible, fathom, or script) to collect feedback responses"
+          )
+        end
+
+        def analytics_configured?
+          analytics = @config["analytics"]
+          return false unless analytics.is_a?(Hash)
+
+          analytics["google"] || analytics["plausible"] || analytics["fathom"] || analytics["script"]
+        end
+      end
+    end
+  end
+end

data/lib/docyard/config.rb

@@ -1,35 +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
-      }
+      "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
@@ -49,83 +49,50 @@ module Docyard
       File.exist?(file_path)
     end
 
-    def title
-      data["title"]
-    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 description
-      data["description"]
-    end
+    def sidebar_config? = sidebar == "config"
+    def sidebar_auto? = sidebar == "auto"
+    def sidebar_distributed? = sidebar == "distributed"
 
-    def branding
-      @branding ||= ConfigSection.new(data["branding"])
-    end
+    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 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"])
+    def announcement
+      @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
@@ -134,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/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