docyard 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db5ddabfe4a3b7bf25c24876b915188bd4768ca543772ad0a8cfc971ee791fee
-  data.tar.gz: d906b1c2ab33102c9ade6e2cb23f6d067fdbf240d6a4a8e2aa27a52a9ba62b42
+  metadata.gz: 52a27eaf396879abae3d0b091e5a488629022bb777838fafc17c0bb07e15d65b
+  data.tar.gz: ec6a567e2e411800f67f96351a80f7e60823ac399df8cac7e82b7c3a9a1370b5
 SHA512:
-  metadata.gz: 2abc1d991cade7059cfaa0b54c2b6f88b33625937e8073cee9d8f61948149567a209a378efd225e9fe85b45b7579ef4e1d81599be5a8cbee970e9cb6e5218a3c
-  data.tar.gz: dcd2baa65fcdd4c00825c6f895c035ffd53603ec22503233b600925084b6512b651c9a009687682f1f5cab3a0c8d8e3d0a5c7586634d6da174e4e4c5a95f9a53
+  metadata.gz: 6e0d9995254e35e291250db40c9572d3bde1a76d86433d0fbcfb6e2a8602d6e68ad6be910d7a03036814dcdc0fba64289d68c760d9d6f1336376e2f709ec35b8
+  data.tar.gz: 127131f44ea7140f227a8e95468b96e09256b5fced9ef557e37e5a1caefc888adb902a8b2d164474cb1f31ae0ddd4b76b1c4684b39e5125ddce17c84bbd754e7

data/CHANGELOG.md

@@ -7,7 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.4.0] - 2025-01-16
+## [0.5.0] - 2025-11-18
+
+### Added
+- **Table of Contents** - Auto-generated TOC from h2-h4 headings with clickable anchor links and smooth scrolling (#30)
+- **Previous/Next Navigation** - Auto-detection from sidebar order with frontmatter override support and configurable labels (#31)
+
+## [0.4.0] - 2025-11-16
 
 ### Added
 - **Static site generation** - Build system with `docyard build` command (#27)
@@ -29,7 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Component CSS accessibility and performance improvements (#24)
 - Table responsive styling with proper wrapper element (#23)
 
-## [0.3.0] - 2025-01-09
+## [0.3.0] - 2025-11-09
 
 ### Added
 - Configuration system with optional `docyard.yml` file (#20)
@@ -85,7 +91,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial gem structure
 - Project scaffolding
 
-[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/sanifhimani/docyard/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/sanifhimani/docyard/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/sanifhimani/docyard/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/sanifhimani/docyard/compare/v0.1.0...v0.2.0

data/README.md

@@ -20,6 +20,8 @@ Build beautiful documentation sites with hot reload, dark mode, and powerful mar
 ### Navigation
 - **Sidebar navigation** - Automatic sidebar with nested folders and collapsible sections
 - **Sidebar customization** - Custom ordering, icons, and external links via config
+- **Table of Contents** - Auto-generated TOC with heading anchors and smooth scrolling
+- **Previous/Next navigation** - Auto-detection from sidebar with frontmatter override support
 - **Active page highlighting** - Always know where you are
 
 ### Markdown
@@ -139,6 +141,32 @@ description: Page description
 
 Currently supported:
 - `title` - Page title (shown in `<title>` tag)
+- `prev` - Customize or disable previous link
+- `next` - Customize or disable next link
+
+### Customizing Navigation
+
+Control previous/next links per page via frontmatter:
+
+```yaml
+---
+title: My Page
+prev: false                  # Disable previous link
+next:
+  text: Custom Next Page
+  link: /custom-path
+---
+```
+
+Configure labels globally in `docyard.yml`:
+
+```yaml
+navigation:
+  footer:
+    enabled: true
+    prev_text: "← Back"
+    next_text: "Forward →"
+```
 
 ### Linking Between Pages
 
@@ -227,18 +255,15 @@ bundle exec rubocop
 
 ## Roadmap
 
-**v0.4.0 - Just shipped:**
-- Static site generation with `docyard build`
-- Asset bundling with minification and cache busting
-- SEO files (sitemap.xml, robots.txt)
-- Preview server for testing builds
-- Sidebar customization via config
-- Improved init templates
-
-**Next up:**
-- Search functionality
-- Table of contents
-- More markdown components
+**v0.5.0 - Just shipped:**
+- Table of Contents with heading anchors
+- Previous/Next page navigation with auto-detection
+
+**Next up (v0.6.0+):**
+- Code block enhancements (line numbers, highlighting, diffs)
+- Search functionality (client-side with Cmd/K)
+- Details/collapsible blocks
+- More markdown extensions
 
 ## Contributing
 

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/config.rb

@@ -27,6 +27,13 @@ module Docyard
       },
       "sidebar" => {
         "items" => []
+      },
+      "navigation" => {
+        "footer" => {
+          "enabled" => true,
+          "prev_text" => "Previous",
+          "next_text" => "Next"
+        }
       }
     }.freeze
 
@@ -63,6 +70,10 @@ module Docyard
       @sidebar ||= ConfigSection.new(data["sidebar"])
     end
 
+    def navigation
+      @navigation ||= ConfigSection.new(data["navigation"])
+    end
+
     private
 
     def load_config_data

data/lib/docyard/icons/phosphor.rb

@@ -35,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/markdown.rb

@@ -10,6 +10,8 @@ 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
@@ -53,6 +55,10 @@ module Docyard
       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/rack_application.rb

@@ -3,6 +3,7 @@
 require "json"
 require "rack"
 require_relative "sidebar_builder"
+require_relative "prev_next_builder"
 require_relative "constants"
 
 module Docyard
@@ -46,9 +47,12 @@ module Docyard
     end
 
     def render_documentation_page(file_path, current_path)
+      sidebar_builder = build_sidebar_instance(current_path)
+
       html = renderer.render_file(
         file_path,
-        sidebar_html: build_sidebar(current_path),
+        sidebar_html: sidebar_builder.to_html,
+        prev_next_html: build_prev_next(sidebar_builder, current_path, file_path),
         branding: branding_options
       )
 
@@ -60,14 +64,32 @@ module Docyard
       [Constants::STATUS_NOT_FOUND, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
     end
 
-    def build_sidebar(current_path)
+    def build_sidebar_instance(current_path)
       SidebarBuilder.new(
         docs_path: docs_path,
         current_path: current_path,
         config: config
+      )
+    end
+
+    def build_prev_next(sidebar_builder, current_path, file_path)
+      markdown_content = File.read(file_path)
+      markdown = Markdown.new(markdown_content)
+
+      PrevNextBuilder.new(
+        sidebar_tree: sidebar_builder.tree,
+        current_path: current_path,
+        frontmatter: markdown.frontmatter,
+        config: navigation_config
       ).to_html
     end
 
+    def navigation_config
+      return {} unless config
+
+      config.navigation&.footer || {}
+    end
+
     def branding_options
       return default_branding unless config
 

data/lib/docyard/renderer.rb

@@ -16,24 +16,33 @@ module Docyard
       @base_url = normalize_base_url(base_url)
     end
 
-    def render_file(file_path, sidebar_html: "", branding: {})
+    def render_file(file_path, sidebar_html: "", prev_next_html: "", branding: {})
       markdown_content = File.read(file_path)
       markdown = Markdown.new(markdown_content)
 
       html_content = strip_md_from_links(markdown.html)
+      toc = markdown.toc
 
       render(
         content: html_content,
         page_title: markdown.title || Constants::DEFAULT_SITE_TITLE,
-        sidebar_html: sidebar_html,
+        navigation: {
+          sidebar_html: sidebar_html,
+          prev_next_html: prev_next_html,
+          toc: toc
+        },
         branding: branding
       )
     end
 
-    def render(content:, page_title: Constants::DEFAULT_SITE_TITLE, sidebar_html: "", branding: {})
+    def render(content:, page_title: Constants::DEFAULT_SITE_TITLE, navigation: {}, branding: {})
       template = File.read(layout_path)
 
-      assign_content_variables(content, page_title, sidebar_html)
+      sidebar_html = navigation[:sidebar_html] || ""
+      prev_next_html = navigation[:prev_next_html] || ""
+      toc = navigation[:toc] || []
+
+      assign_content_variables(content, page_title, sidebar_html, prev_next_html, toc)
       assign_branding_variables(branding)
 
       ERB.new(template).result(binding)
@@ -85,10 +94,12 @@ module Docyard
       url.end_with?("/") ? url : "#{url}/"
     end
 
-    def assign_content_variables(content, page_title, sidebar_html)
+    def assign_content_variables(content, page_title, sidebar_html, prev_next_html, toc)
       @content = content
       @page_title = page_title
       @sidebar_html = sidebar_html
+      @prev_next_html = prev_next_html
+      @toc = toc
     end
 
     def assign_branding_variables(branding)

data/lib/docyard/templates/assets/css/components/heading-anchor.css

@@ -0,0 +1,77 @@
+.content h2[id],
+.content h3[id],
+.content h4[id],
+.content h5[id],
+.content h6[id] {
+  position: relative;
+  scroll-margin-top: 100px;
+}
+
+/* Tablet: Account for both primary + secondary header */
+@media (max-width: 1280px) and (min-width: 1025px) {
+  .content h2[id],
+  .content h3[id],
+  .content h4[id],
+  .content h5[id],
+  .content h6[id] {
+    scroll-margin-top: calc(var(--header-height) + 3rem + var(--space-4));
+  }
+}
+
+.heading-anchor {
+  float: left;
+  margin-left: -0.75em;
+  padding-right: 0.25em;
+  font-weight: var(--font-weight-normal);
+  color: var(--color-primary);
+  text-decoration: none !important;
+  opacity: 0;
+  transition: opacity var(--transition-fast);
+  cursor: pointer;
+  user-select: none;
+}
+
+.heading-anchor:hover,
+.heading-anchor:focus {
+  opacity: 1;
+  text-decoration: none !important;
+}
+
+.heading-anchor:active,
+.heading-anchor:visited {
+  text-decoration: none !important;
+}
+
+.heading-anchor:focus {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+  border-radius: 4px;
+}
+
+.content h2[id]:hover .heading-anchor,
+.content h3[id]:hover .heading-anchor,
+.content h4[id]:hover .heading-anchor,
+.content h5[id]:hover .heading-anchor,
+.content h6[id]:hover .heading-anchor {
+  opacity: 1;
+}
+
+@media (max-width: 1024px) {
+  .heading-anchor {
+    position: static;
+    margin-left: var(--space-2);
+    float: none;
+    opacity: 0.6;
+  }
+
+  .heading-anchor:hover,
+  .heading-anchor:focus {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .heading-anchor {
+    transition: none;
+  }
+}