docyard 0.9.0 → 1.0.0

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

data/lib/docyard/navigation/sidebar/auto_builder.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "item"
+
+module Docyard
+  module Sidebar
+    class AutoBuilder
+      attr_reader :docs_path, :current_path
+
+      def initialize(docs_path, current_path: "/")
+        @docs_path = docs_path
+        @current_path = Utils::PathResolver.normalize(current_path)
+      end
+
+      def build
+        return [] unless File.directory?(docs_path)
+
+        scan_directory("").map(&:to_h)
+      end
+
+      private
+
+      def scan_directory(relative_path, depth: 1)
+        full_path = File.join(docs_path, relative_path)
+        return [] unless File.directory?(full_path)
+
+        entries = sorted_entries(full_path, relative_path)
+        entries.map { |entry| build_item(entry, relative_path, depth) }.compact
+      end
+
+      def sorted_entries(full_path, relative_path)
+        Dir.children(full_path)
+          .reject { |entry| ignored_entry?(entry, relative_path) }
+          .sort_by(&:downcase)
+      end
+
+      def build_item(entry, relative_path, depth)
+        entry_relative_path = build_relative_path(relative_path, entry)
+        entry_full_path = File.join(docs_path, entry_relative_path)
+
+        if File.directory?(entry_full_path)
+          build_directory_item(entry, entry_relative_path, depth)
+        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(name, relative_path, depth)
+        children = scan_directory(relative_path, depth: depth + 1)
+        return nil if children.empty?
+
+        url_path = "/#{relative_path}"
+        has_index = File.file?(File.join(docs_path, relative_path, "index.md"))
+
+        Item.new(
+          slug: name,
+          text: Utils::TextFormatter.titleize(name),
+          path: has_index ? url_path : nil,
+          type: :directory,
+          section: depth == 1,
+          collapsed: depth > 1 && !child_active?(children),
+          has_index: has_index,
+          active: has_index && current_path == url_path,
+          items: children
+        )
+      end
+
+      def build_file_item(filename, relative_path)
+        slug = filename.delete_suffix(".md")
+        url_path = "/#{relative_path.delete_suffix('.md')}"
+
+        Item.new(
+          slug: slug,
+          text: Utils::TextFormatter.titleize(slug),
+          path: url_path,
+          type: :file,
+          section: false,
+          active: current_path == url_path,
+          items: []
+        )
+      end
+
+      def ignored_entry?(entry, relative_path)
+        entry.start_with?(".") ||
+          entry.start_with?("_") ||
+          root_index?(entry, relative_path) ||
+          public_folder?(entry, relative_path)
+      end
+
+      def root_index?(entry, relative_path)
+        entry == "index.md" && relative_path.empty?
+      end
+
+      def public_folder?(entry, relative_path)
+        entry == "public" && relative_path.empty?
+      end
+
+      def child_active?(children)
+        children.any? { |child| child.active || child_active?(child.items) }
+      end
+    end
+  end
+end

data/lib/docyard/navigation/sidebar/cache.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "config_builder"
+require_relative "auto_builder"
+require_relative "distributed_builder"
+require_relative "local_config_loader"
+
+module Docyard
+  module Sidebar
+    class Cache
+      attr_reader :docs_path, :config, :tree, :built_at
+
+      def initialize(docs_path:, config:)
+        @docs_path = docs_path
+        @config = config
+        @tree = nil
+        @built_at = nil
+      end
+
+      def build
+        @tree = build_tree
+        @built_at = Time.now
+        @tree
+      end
+
+      def get(current_path: "/")
+        return nil unless @tree
+
+        mark_active_items(@tree, current_path)
+      end
+
+      def invalidate
+        @tree = nil
+        @built_at = nil
+      end
+
+      def valid?
+        !@tree.nil?
+      end
+
+      private
+
+      def build_tree
+        case config.sidebar
+        when "auto"
+          AutoBuilder.new(docs_path, current_path: "/").build
+        when "distributed"
+          DistributedBuilder.new(docs_path, current_path: "/").build
+        else
+          build_config_tree
+        end
+      end
+
+      def build_config_tree
+        config_items = LocalConfigLoader.new(docs_path).load
+        return [] unless config_items
+
+        ConfigBuilder.new(config_items, current_path: "/").build
+      end
+
+      def mark_active_items(items, current_path)
+        deep_copy_with_active(items, current_path)
+      end
+
+      def deep_copy_with_active(items, current_path)
+        items.map do |item|
+          copied = item.dup
+          copied[:active] = path_matches?(copied[:path], current_path)
+          copied[:children] = deep_copy_with_active(item[:children] || [], current_path)
+          copied[:collapsed] = determine_collapsed_for_copy(copied)
+          copied
+        end
+      end
+
+      def path_matches?(item_path, current_path)
+        return false if item_path.nil?
+
+        normalized_item = Utils::PathResolver.normalize(item_path)
+        normalized_current = Utils::PathResolver.normalize(current_path)
+        normalized_item == normalized_current
+      end
+
+      def determine_collapsed_for_copy(item)
+        return false if item[:section]
+        return false if item[:active]
+        return false if child_active?(item[:children] || [])
+
+        item[:collapsed]
+      end
+
+      def child_active?(children)
+        children.any? { |child| child[:active] || child_active?(child[:children] || []) }
+      end
+    end
+  end
+end