docyard 0.3.0 → 0.5.0

data/lib/docyard/builder.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tty-progressbar"
+
+module Docyard
+  class Builder
+    attr_reader :config, :clean, :verbose, :start_time
+
+    def initialize(clean: true, verbose: false)
+      @config = Config.new
+      @clean = clean
+      @verbose = verbose
+      @start_time = Time.now
+    end
+
+    def build
+      prepare_output_directory
+      log "Building static site..."
+
+      pages_built = generate_static_pages
+      bundles_created = bundle_assets
+      assets_copied = copy_static_files
+      generate_seo_files
+
+      display_summary(pages_built, bundles_created, assets_copied)
+      true
+    rescue StandardError => e
+      error "Build failed: #{e.message}"
+      error e.backtrace.first if verbose
+      false
+    end
+
+    private
+
+    def prepare_output_directory
+      output_dir = config.build.output_dir
+
+      if clean && Dir.exist?(output_dir)
+        log "[✓] Cleaning #{output_dir}/ directory"
+        FileUtils.rm_rf(output_dir)
+      end
+
+      FileUtils.mkdir_p(output_dir)
+    end
+
+    def generate_static_pages
+      require_relative "build/static_generator"
+      generator = Build::StaticGenerator.new(config, verbose: verbose)
+      generator.generate
+    end
+
+    def bundle_assets
+      require_relative "build/asset_bundler"
+      bundler = Build::AssetBundler.new(config, verbose: verbose)
+      bundler.bundle
+    end
+
+    def copy_static_files
+      require_relative "build/file_copier"
+      copier = Build::FileCopier.new(config, verbose: verbose)
+      copier.copy
+    end
+
+    def generate_seo_files
+      require_relative "build/sitemap_generator"
+      sitemap_gen = Build::SitemapGenerator.new(config)
+      sitemap_gen.generate
+
+      File.write(File.join(config.build.output_dir, "robots.txt"), robots_txt_content)
+      log "[✓] Generated robots.txt"
+    end
+
+    def robots_txt_content
+      base_url = config.build.base_url
+      base_url = "#{base_url}/" unless base_url.end_with?("/")
+
+      <<~ROBOTS
+        User-agent: *
+        Allow: /
+
+        Sitemap: #{base_url}sitemap.xml
+      ROBOTS
+    end
+
+    def display_summary(pages, bundles, assets)
+      elapsed = Time.now - start_time
+
+      puts "\n#{'=' * 50}"
+      puts "Build complete in #{format('%.2f', elapsed)}s"
+      puts "Output: #{config.build.output_dir}/"
+      puts "#{pages} pages, #{bundles} bundles, #{assets} static files"
+      puts "=" * 50
+    end
+
+    def log(message)
+      puts message
+    end
+
+    def error(message)
+      warn "[ERROR] #{message}"
+    end
+  end
+end

data/lib/docyard/cli.rb

@@ -19,6 +19,25 @@ module Docyard
       exit(1) unless initializer.run
     end
 
+    desc "build", "Build static site for production"
+    method_option :clean, type: :boolean, default: true, desc: "Clean output directory before building"
+    method_option :verbose, type: :boolean, default: false, aliases: "-v", desc: "Show verbose output"
+    def build
+      require_relative "builder"
+      builder = Docyard::Builder.new(
+        clean: options[:clean],
+        verbose: options[:verbose]
+      )
+      exit(1) unless builder.build
+    end
+
+    desc "preview", "Preview the built site locally"
+    method_option :port, type: :numeric, default: 4000, aliases: "-p", desc: "Port to run preview server on"
+    def preview
+      require_relative "preview_server"
+      Docyard::PreviewServer.new(port: options[:port]).start
+    end
+
     desc "serve", "Start the development server"
     method_option :port, type: :numeric, default: 4200, aliases: "-p", desc: "Port to run the server on"
     method_option :host, type: :string, default: "localhost", aliases: "-h", desc: "Host to bind the server to"

data/lib/docyard/components/heading_anchor_processor.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    class HeadingAnchorProcessor < BaseProcessor
+      self.priority = 30
+
+      def postprocess(html)
+        add_anchor_links(html)
+      end
+
+      private
+
+      def add_anchor_links(html)
+        html.gsub(%r{<(h[2-6])\s+id="([^"]+)">(.*?)</\1>}m) do |_match|
+          tag = Regexp.last_match(1)
+          id = Regexp.last_match(2)
+          content = Regexp.last_match(3)
+
+          anchor_html = render_anchor_link(id)
+
+          "<#{tag} id=\"#{id}\">#{content}#{anchor_html}</#{tag}>"
+        end
+      end
+
+      def render_anchor_link(id)
+        renderer = Renderer.new
+        renderer.render_partial("_heading_anchor", {
+                                  id: id
+                                })
+      end
+    end
+  end
+end

data/lib/docyard/components/table_of_contents_processor.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    class TableOfContentsProcessor < BaseProcessor
+      self.priority = 35
+
+      def postprocess(html)
+        headings = extract_headings(html)
+        Thread.current[:docyard_toc] = headings
+        html
+      end
+
+      private
+
+      def extract_headings(html)
+        headings = []
+
+        html.scan(%r{<(h[2-4])\s+id="([^"]+)">(.*?)</\1>}m) do
+          level = Regexp.last_match(1)[1].to_i
+          id = Regexp.last_match(2)
+          text = strip_html(Regexp.last_match(3))
+
+          headings << {
+            level: level,
+            id: id,
+            text: text
+          }
+        end
+
+        build_hierarchy(headings)
+      end
+
+      def build_hierarchy(headings)
+        return [] if headings.empty?
+
+        root = []
+        stack = []
+
+        headings.each do |heading|
+          heading[:children] = []
+
+          stack.pop while stack.any? && stack.last[:level] >= heading[:level]
+
+          if stack.empty?
+            root << heading
+          else
+            stack.last[:children] << heading
+          end
+
+          stack << heading
+        end
+
+        root
+      end
+
+      def strip_html(text)
+        text.gsub(%r{<a[^>]*class="heading-anchor"[^>]*>.*?</a>}, "")
+          .gsub(/<[^>]+>/, "")
+          .strip
+      end
+    end
+  end
+end

data/lib/docyard/components/table_wrapper_processor.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    class TableWrapperProcessor < BaseProcessor
+      self.priority = 100
+
+      def postprocess(html)
+        wrapped = html.gsub(/<table([^>]*)>/) do
+          attributes = Regexp.last_match(1)
+          "<div class=\"table-wrapper\"><table#{attributes}>"
+        end
+
+        wrapped.gsub("</table>", "</table></div>")
+      end
+    end
+  end
+end

data/lib/docyard/config.rb

@@ -25,7 +25,16 @@ module Docyard
         "base_url" => "/",
         "clean" => true
       },
-      "sidebar" => nil
+      "sidebar" => {
+        "items" => []
+      },
+      "navigation" => {
+        "footer" => {
+          "enabled" => true,
+          "prev_text" => "Previous",
+          "next_text" => "Next"
+        }
+      }
     }.freeze
 
     attr_reader :data, :file_path
@@ -58,7 +67,11 @@ module Docyard
     end
 
     def sidebar
-      data["sidebar"]
+      @sidebar ||= ConfigSection.new(data["sidebar"])
+    end
+
+    def navigation
+      @navigation ||= ConfigSection.new(data["navigation"])
     end
 
     private

data/lib/docyard/icons/phosphor.rb

@@ -27,6 +27,7 @@ module Docyard
         "sun" => '<path d="M120,40V16a8,8,0,0,1,16,0V40a8,8,0,0,1-16,0Zm72,88a64,64,0,1,1-64-64A64.07,64.07,0,0,1,192,128Zm-16,0a48,48,0,1,0-48,48A48.05,48.05,0,0,0,176,128ZM58.34,69.66A8,8,0,0,0,69.66,58.34l-16-16A8,8,0,0,0,42.34,53.66Zm0,116.68-16,16a8,8,0,0,0,11.32,11.32l16-16a8,8,0,0,0-11.32-11.32ZM192,72a8,8,0,0,0,5.66-2.34l16-16a8,8,0,0,0-11.32-11.32l-16,16A8,8,0,0,0,192,72Zm5.66,114.34a8,8,0,0,0-11.32,11.32l16,16a8,8,0,0,0,11.32-11.32ZM48,128a8,8,0,0,0-8-8H16a8,8,0,0,0,0,16H40A8,8,0,0,0,48,128Zm80,80a8,8,0,0,0-8,8v24a8,8,0,0,0,16,0V216A8,8,0,0,0,128,208Zm112-88H216a8,8,0,0,0,0,16h24a8,8,0,0,0,0-16Z"/>',
         "link-external" => '<path d="M224,104a8,8,0,0,1-16,0V59.32l-66.33,66.34a8,8,0,0,1-11.32-11.32L196.68,48H152a8,8,0,0,1,0-16h64a8,8,0,0,1,8,8Zm-40,24a8,8,0,0,0-8,8v72H48V80h72a8,8,0,0,0,0-16H48A16,16,0,0,0,32,80V208a16,16,0,0,0,16,16H176a16,16,0,0,0,16-16V136A8,8,0,0,0,184,128Z"/>',
         "copy" => '<path d="M216,32H88a8,8,0,0,0-8,8V80H40a8,8,0,0,0-8,8V216a8,8,0,0,0,8,8H168a8,8,0,0,0,8-8V176h40a8,8,0,0,0,8-8V40A8,8,0,0,0,216,32ZM160,208H48V96H160Zm48-48H176V88a8,8,0,0,0-8-8H96V48H208Z"/>',
+        "caret-right" => '<path d="M181.66,133.66l-80,80a8,8,0,0,1-11.32-11.32L164.69,128,90.34,53.66a8,8,0,0,1,11.32-11.32l80,80A8,8,0,0,1,181.66,133.66Z"/>',
         "github" => '<path d="M208.31,75.68A59.78,59.78,0,0,0,202.93,28,8,8,0,0,0,196,24a59.75,59.75,0,0,0-48,24H124A59.75,59.75,0,0,0,76,24a8,8,0,0,0-6.93,4,59.78,59.78,0,0,0-5.38,47.68A58.14,58.14,0,0,0,56,104v8a56.06,56.06,0,0,0,48.44,55.47A39.8,39.8,0,0,0,96,192v8H72a24,24,0,0,1-24-24A40,40,0,0,0,8,136a8,8,0,0,0,0,16,24,24,0,0,1,24,24,40,40,0,0,0,40,40H96v16a8,8,0,0,0,16,0V192a24,24,0,0,1,48,0v40a8,8,0,0,0,16,0V192a39.8,39.8,0,0,0-8.44-24.53A56.06,56.06,0,0,0,216,112v-8A58.14,58.14,0,0,0,208.31,75.68ZM200,112a40,40,0,0,1-40,40H112a40,40,0,0,1-40-40v-8a41.74,41.74,0,0,1,6.9-22.48,8,8,0,0,0,1.1-7.69,43.81,43.81,0,0,1,.79-33.58,43.88,43.88,0,0,1,32.32,20.06,8,8,0,0,0,6.71,3.69h32.35a8,8,0,0,0,6.74-3.69,43.87,43.87,0,0,1,32.32-20.06,43.81,43.81,0,0,1,.77,33.58,8.09,8.09,0,0,0,1,7.65,41.76,41.76,0,0,1,7,22.52Z"/>',
         "question" => '<path d="M140,180a12,12,0,1,1-12-12A12,12,0,0,1,140,180ZM128,72c-22.06,0-40,16.15-40,36v4a8,8,0,0,0,16,0v-4c0-11,10.77-20,24-20s24,9,24,20-10.77,20-24,20a8,8,0,0,0-8,8v8a8,8,0,0,0,16,0v-.72c18.24-3.35,32-17.9,32-35.28C168,88.15,150.06,72,128,72Zm104,56A104,104,0,1,1,128,24,104.11,104.11,0,0,1,232,128Zm-16,0a88,88,0,1,0-88,88A88.1,88.1,0,0,0,216,128Z"/>',
         "lightbulb" => '<path d="M176,232a8,8,0,0,1-8,8H88a8,8,0,0,1,0-16h80A8,8,0,0,1,176,232Zm40-128a87.55,87.55,0,0,1-33.64,69.21A16.24,16.24,0,0,0,176,186v6a16,16,0,0,1-16,16H96a16,16,0,0,1-16-16v-6a16,16,0,0,0-6.23-12.66A87.59,87.59,0,0,1,40,104.49C39.74,56.83,78.26,17.14,125.88,16A88,88,0,0,1,216,104Zm-16,0a72,72,0,0,0-73.74-72c-39,.92-70.47,33.39-70.26,72.39a71.65,71.65,0,0,0,27.64,56.3A32,32,0,0,1,96,186v6h64v-6a32.15,32.15,0,0,1,12.47-25.35A71.65,71.65,0,0,0,200,104Zm-16.11-9.34a57.6,57.6,0,0,0-46.56-46.55,8,8,0,0,0-2.66,15.78c16.57,2.79,30.63,16.85,33.44,33.45A8,8,0,0,0,176,104a9,9,0,0,0,1.35-.11A8,8,0,0,0,183.89,94.66Z"/>',
@@ -34,7 +35,8 @@ module Docyard
         "warning-octagon" => '<path d="M120,136V80a8,8,0,0,1,16,0v56a8,8,0,0,1-16,0ZM232,91.55v72.9a15.86,15.86,0,0,1-4.69,11.31l-51.55,51.55A15.86,15.86,0,0,1,164.45,232H91.55a15.86,15.86,0,0,1-11.31-4.69L28.69,175.76A15.86,15.86,0,0,1,24,164.45V91.55a15.86,15.86,0,0,1,4.69-11.31L80.24,28.69A15.86,15.86,0,0,1,91.55,24h72.9a15.86,15.86,0,0,1,11.31,4.69l51.55,51.55A15.86,15.86,0,0,1,232,91.55Zm-16,0L164.45,40H91.55L40,91.55v72.9L91.55,216h72.9L216,164.45ZM128,160a12,12,0,1,0,12,12A12,12,0,0,0,128,160Z"/>',
         "siren" => '<path d="M120,16V8a8,8,0,0,1,16,0v8a8,8,0,0,1-16,0Zm80,32a8,8,0,0,0,5.66-2.34l8-8a8,8,0,0,0-11.32-11.32l-8,8A8,8,0,0,0,200,48ZM50.34,45.66A8,8,0,0,0,61.66,34.34l-8-8A8,8,0,0,0,42.34,37.66Zm87,26.45a8,8,0,1,0-2.64,15.78C153.67,91.08,168,108.32,168,128a8,8,0,0,0,16,0C184,100.6,163.93,76.57,137.32,72.11ZM232,176v24a16,16,0,0,1-16,16H40a16,16,0,0,1-16-16V176a16,16,0,0,1,16-16V128a88,88,0,0,1,88.67-88c48.15.36,87.33,40.29,87.33,89v31A16,16,0,0,1,232,176ZM56,160H200V129c0-40-32.05-72.71-71.45-73H128a72,72,0,0,0-72,72Zm160,40V176H40v24H216Z"/>',
         "file" => '<path d="M213.66,82.34l-56-56A8,8,0,0,0,152,24H56A16,16,0,0,0,40,40V216a16,16,0,0,0,16,16H200a16,16,0,0,0,16-16V88A8,8,0,0,0,213.66,82.34ZM160,51.31,188.69,80H160ZM200,216H56V40h88V88a8,8,0,0,0,8,8h48V216Z"/>',
-        "terminal-window" => '<path d="M128,128a8,8,0,0,1-3,6.25l-40,32a8,8,0,1,1-10-12.5L107.19,128,75,102.25a8,8,0,1,1,10-12.5l40,32A8,8,0,0,1,128,128Zm48,24H136a8,8,0,0,0,0,16h40a8,8,0,0,0,0-16Zm56-96V200a16,16,0,0,1-16,16H40a16,16,0,0,1-16-16V56A16,16,0,0,1,40,40H216A16,16,0,0,1,232,56ZM216,200V56H40V200H216Z"/>'
+        "terminal-window" => '<path d="M128,128a8,8,0,0,1-3,6.25l-40,32a8,8,0,1,1-10-12.5L107.19,128,75,102.25a8,8,0,1,1,10-12.5l40,32A8,8,0,0,1,128,128Zm48,24H136a8,8,0,0,0,0,16h40a8,8,0,0,0,0-16Zm56-96V200a16,16,0,0,1-16,16H40a16,16,0,0,1-16-16V56A16,16,0,0,1,40,40H216A16,16,0,0,1,232,56ZM216,200V56H40V200H216Z"/>',
+        "list-dashes" => '<path d="M88,64a8,8,0,0,1,8-8H216a8,8,0,0,1,0,16H96A8,8,0,0,1,88,64Zm128,56H96a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16Zm0,64H96a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16ZM56,56H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Zm0,64H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Zm0,64H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Z"/>'
       },
       "bold" => {
         "heart" => '<path d="M178,36c-20.09,0-37.92,7.93-50,21.56C115.92,43.93,98.09,36,78,36a66.08,66.08,0,0,0-66,66c0,72.34,105.81,130.14,110.31,132.57a12,12,0,0,0,11.38,0C138.19,232.14,244,174.34,244,102A66.08,66.08,0,0,0,178,36Zm-5.49,142.36A328.69,328.69,0,0,1,128,210.16a328.69,328.69,0,0,1-44.51-31.8C61.82,159.77,36,131.42,36,102A42,42,0,0,1,78,60c17.8,0,32.7,9.4,38.89,24.54a12,12,0,0,0,22.22,0C145.3,69.4,160.2,60,178,60a42,42,0,0,1,42,42C220,131.42,194.18,159.77,172.51,178.36Z"/>'

data/lib/docyard/initializer.rb

@@ -10,14 +10,9 @@ module Docyard
 
     TEMPLATES = {
       "index.md" => "index.md.erb",
-      "getting-started/introduction.md" => "getting-started/introduction.md.erb",
       "getting-started/installation.md" => "getting-started/installation.md.erb",
-      "getting-started/quick-start.md" => "getting-started/quick-start.md.erb",
-      "core-concepts/file-structure.md" => "core-concepts/file-structure.md.erb",
-      "core-concepts/markdown.md" => "core-concepts/markdown.md.erb",
-      "components/callouts.md" => "components/callouts.md.erb",
-      "components/icons.md" => "components/icons.md.erb",
-      "components/tabs.md" => "components/tabs.md.erb"
+      "guides/markdown-features.md" => "guides/markdown-features.md.erb",
+      "guides/configuration.md" => "guides/configuration.md.erb"
     }.freeze
 
     def initialize(path = ".")
@@ -79,16 +74,87 @@ module Docyard
     end
 
     def print_success
-      puts "Docyard initialized successfully!"
+      print_banner
+      print_created_files
+      print_next_steps
+    end
+
+    def print_banner
+      puts ""
+      puts "┌─────────────────────────────────────────────────────────────┐"
+      puts "│  ✓ Docyard initialized successfully                        │"
+      puts "└─────────────────────────────────────────────────────────────┘"
+      puts ""
+    end
+
+    def print_created_files
+      puts "Created files:"
       puts ""
-      puts "Created:"
-      TEMPLATES.each_key { |file| puts "  #{DOCS_DIR}/#{file}" }
-      puts "  docyard.yml (configuration - optional)"
+      print_file_tree
       puts ""
+    end
+
+    def print_next_steps
       puts "Next steps:"
-      puts "  1. Edit your markdown files in #{DOCS_DIR}/"
-      puts "  2. Customize docyard.yml (optional)"
-      puts "  3. Run 'docyard serve' to preview your documentation locally"
+      puts ""
+      puts "  Start development server:"
+      puts "    docyard serve"
+      puts "    → http://localhost:4200"
+      puts ""
+      puts "  Build for production:"
+      puts "    docyard build"
+      puts ""
+      puts "  Preview production build:"
+      puts "    docyard preview"
+      puts ""
+    end
+
+    def print_file_tree
+      puts "  ├── docs/"
+
+      grouped_files = TEMPLATES.keys.group_by { |file| File.dirname(file) }
+      sorted_dirs = grouped_files.keys.sort
+
+      sorted_dirs.each_with_index do |dir, dir_idx|
+        print_directory_group(dir, grouped_files[dir], dir_idx == sorted_dirs.length - 1)
+      end
+
+      puts "  └── docyard.yml"
+    end
+
+    def print_directory_group(dir, files, is_last_dir)
+      sorted_files = files.sort
+
+      if dir == "."
+        print_root_files(sorted_files, is_last_dir)
+      else
+        print_subdirectory(dir, sorted_files, is_last_dir)
+      end
+    end
+
+    def print_root_files(files, is_last_dir)
+      files.each_with_index do |file, idx|
+        is_last = idx == files.length - 1 && is_last_dir
+        prefix = is_last ? "  │   └──" : "  │   ├──"
+        puts "#{prefix} #{file}"
+      end
+    end
+
+    def print_subdirectory(dir, files, is_last_dir)
+      dir_prefix = is_last_dir ? "  │   └──" : "  │   ├──"
+      puts "#{dir_prefix} #{dir}/"
+
+      files.each_with_index do |file, idx|
+        print_subdirectory_file(file, idx, files.length, is_last_dir)
+      end
+    end
+
+    def print_subdirectory_file(file, idx, total, is_last_dir)
+      is_last_file = idx == total - 1
+      file_prefix = is_last_dir ? "  │       " : "  │   │   "
+      file_prefix += is_last_file ? "└──" : "├──"
+      basename = File.basename(file)
+      puts "#{file_prefix} #{basename}"
     end
   end
 end

data/lib/docyard/markdown.rb

@@ -9,6 +9,9 @@ require_relative "components/callout_processor"
 require_relative "components/tabs_processor"
 require_relative "components/icon_processor"
 require_relative "components/code_block_processor"
+require_relative "components/table_wrapper_processor"
+require_relative "components/heading_anchor_processor"
+require_relative "components/table_of_contents_processor"
 
 module Docyard
   class Markdown
@@ -40,6 +43,22 @@ module Docyard
       frontmatter["description"]
     end
 
+    def sidebar_icon
+      frontmatter.dig("sidebar", "icon")
+    end
+
+    def sidebar_text
+      frontmatter.dig("sidebar", "text")
+    end
+
+    def sidebar_collapsed
+      frontmatter.dig("sidebar", "collapsed")
+    end
+
+    def toc
+      @toc ||= Thread.current[:docyard_toc] || []
+    end
+
     private
 
     def parse_frontmatter

data/lib/docyard/prev_next_builder.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative "renderer"
+require_relative "utils/path_resolver"
+
+module Docyard
+  class PrevNextBuilder
+    attr_reader :sidebar_tree, :current_path, :frontmatter, :config
+
+    def initialize(sidebar_tree:, current_path:, frontmatter: {}, config: {})
+      @sidebar_tree = sidebar_tree
+      @current_path = Utils::PathResolver.normalize(current_path)
+      @frontmatter = frontmatter
+      @config = config
+    end
+
+    def prev_next_links
+      return nil unless enabled?
+
+      {
+        prev: build_prev_link,
+        next: build_next_link
+      }
+    end
+
+    def to_html
+      links = prev_next_links
+      return "" if links.nil? || (links[:prev].nil? && links[:next].nil?)
+
+      Renderer.new.render_partial(
+        "_prev_next", {
+          prev: links[:prev],
+          next: links[:next],
+          prev_text: config_prev_text,
+          next_text: config_next_text
+        }
+      )
+    end
+
+    private
+
+    def enabled?
+      return false if config_disabled?
+      return false if frontmatter_disabled?
+
+      true
+    end
+
+    def config_disabled?
+      return false if config.nil? || config.empty?
+
+      config == false || config["enabled"] == false || config[:enabled] == false
+    end
+
+    def frontmatter_disabled?
+      frontmatter["prev"] == false && frontmatter["next"] == false
+    end
+
+    def build_prev_link
+      return nil if frontmatter["prev"] == false
+
+      return build_frontmatter_link(frontmatter["prev"]) if frontmatter["prev"]
+
+      auto_prev_link
+    end
+
+    def build_next_link
+      return nil if frontmatter["next"] == false
+
+      return build_frontmatter_link(frontmatter["next"]) if frontmatter["next"]
+
+      auto_next_link
+    end
+
+    def build_frontmatter_link(value)
+      case value
+      when String
+        find_link_by_text(value)
+      when Hash
+        {
+          title: value["text"] || value[:text],
+          path: value["link"] || value[:link]
+        }
+      end
+    end
+
+    def find_link_by_text(text)
+      flat_links.find { |link| link[:title].downcase == text.downcase }
+    end
+
+    def auto_prev_link
+      index = current_page_index
+      return nil unless index&.positive?
+
+      flat_links[index - 1]
+    end
+
+    def auto_next_link
+      index = current_page_index
+      return nil unless index && index < flat_links.length - 1
+
+      flat_links[index + 1]
+    end
+
+    def current_page_index
+      @current_page_index ||= flat_links.find_index do |link|
+        normalized_path(link[:path]) == normalized_path(current_path)
+      end
+    end
+
+    def flat_links
+      @flat_links ||= begin
+        links = []
+        flatten_tree(sidebar_tree, links)
+        links.uniq { |link| normalized_path(link[:path]) }
+      end
+    end
+
+    def flatten_tree(items, links)
+      items.each do |item|
+        links << build_link(item) if valid_navigation_item?(item)
+        flatten_tree(item[:children], links) if item[:children]&.any?
+      end
+    end
+
+    def valid_navigation_item?(item)
+      item[:type] == :file && item[:path] && !external_link?(item[:path])
+    end
+
+    def build_link(item)
+      {
+        title: item[:footer_text] || item[:title],
+        path: item[:path]
+      }
+    end
+
+    def external_link?(path)
+      path.start_with?("http://", "https://")
+    end
+
+    def normalized_path(path)
+      return "" if path.nil?
+
+      path.gsub(/[?#].*$/, "")
+    end
+
+    def config_prev_text
+      return "Previous" if config.nil? || config.empty?
+
+      config["prev_text"] || config[:prev_text] || "Previous"
+    end
+
+    def config_next_text
+      return "Next" if config.nil? || config.empty?
+
+      config["next_text"] || config[:next_text] || "Next"
+    end
+  end
+end

data/lib/docyard/preview_server.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "webrick"
+require_relative "config"
+
+module Docyard
+  class PreviewServer
+    DEFAULT_PORT = 4000
+
+    attr_reader :port, :output_dir
+
+    def initialize(port: DEFAULT_PORT)
+      @port = port
+      @config = Config.load
+      @output_dir = File.expand_path(@config.build.output_dir)
+    end
+
+    def start
+      validate_output_directory!
+      print_server_info
+
+      server = create_server
+      trap("INT") { shutdown_server(server) }
+
+      server.start
+    end
+
+    private
+
+    def validate_output_directory!
+      return if File.directory?(output_dir)
+
+      abort "Error: #{output_dir}/ directory not found.\n" \
+            "Run `docyard build` first to build the site."
+    end
+
+    def print_server_info
+      puts "Preview server starting..."
+      puts "=> Serving from: #{output_dir}/"
+      puts "=> Running at: http://localhost:#{port}"
+      puts "=> Press Ctrl+C to stop\n"
+    end
+
+    def create_server
+      WEBrick::HTTPServer.new(
+        Port: port,
+        DocumentRoot: output_dir,
+        AccessLog: [],
+        Logger: WEBrick::Log.new(File::NULL),
+        MimeTypes: mime_types
+      )
+    end
+
+    def mime_types
+      WEBrick::HTTPUtils::DefaultMimeTypes.merge(
+        {
+          "css" => "text/css",
+          "js" => "application/javascript",
+          "json" => "application/json",
+          "svg" => "image/svg+xml",
+          "woff" => "font/woff",
+          "woff2" => "font/woff2"
+        }
+      )
+    end
+
+    def shutdown_server(server)
+      puts "\nShutting down preview server..."
+      server.shutdown
+    end
+  end
+end