markdowndocs 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a49d71e98d368188a3ed6a4437651f03880e691a8f520ee1067cd62c5fa4882
-  data.tar.gz: 7b3646a743326288758bbfef6322b27a3e9ed75dd54c2c8edcec6f4671428f8c
+  metadata.gz: b10065bc9db477eab3c5c118832bf1bf3d0b8c68d879c6b3b5bd324b0deb4ec3
+  data.tar.gz: 4696b2b0c2e906ae7875ba69b32279d222f717db45abbed0987bb335f2d1e55d
 SHA512:
-  metadata.gz: 2b7b057ab57104c261bdd5b6d3d5d06527450a2b68469d42af79f58652e9f3a752b4dbd69b4c386d3e323cfb6bb7f55a4279e9fe324e6b8d5bee211bdfc12f0b
-  data.tar.gz: 0aa8ea43096b87a21396084f59648d8f23762af311e1459703c2074196d6d02cc69dfe950b84b2849e4aff513aacf80d6a40c2f38b98f03417248fa35be7d76b
+  metadata.gz: 81f260911757400e215ebdc586c40229032e381ee5fc445e6606509de5a8fa15e7d60ce5a22f2b33e110c4984f63f093ca9e78393935b1d3e5306002c9dfe9de
+  data.tar.gz: f41f6d08e1736a2d772a89e0d89a5f6d57d6da25342b1a426c0f9bd339f028280d9e1bb0814209ac43edea4823057392a2e2e18db7d52164d1363d0b8c22462e

data/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-03-20
+
+### Added
+
+- Keywords frontmatter support (`keywords: [login, signin, ...]`) indexed by full-text search with highest boost (4x), improving search relevance for docs with explicit keyword tags.
+
+## [0.2.3] - 2026-03-20
+
+### Fixed
+
+- Host app route helpers (e.g., `about_path`) no longer resolve against the engine namespace. Replaced `method_missing` delegation with explicit `define_method` overrides built lazily on first request via `before_action`.
+
 ## [0.2.2] - 2026-03-18
 
 ### Changed
@@ -84,6 +96,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - i18n support for all UI strings
 - Install generator (`rails generate markdowndocs:install`)
 
+[0.3.0]: https://github.com/dschmura/markdowndocs/releases/tag/v0.3.0
+[0.2.3]: https://github.com/dschmura/markdowndocs/releases/tag/v0.2.3
 [0.2.2]: https://github.com/dschmura/markdowndocs/releases/tag/v0.2.2
 [0.2.1]: https://github.com/dschmura/markdowndocs/releases/tag/v0.2.1
 [0.2.0]: https://github.com/dschmura/markdowndocs/releases/tag/v0.2.0

data/app/assets/javascripts/markdowndocs/controllers/docs_search_controller.js

@@ -23,10 +23,10 @@ export default class extends Controller {
       const MiniSearch = (await this.loadMiniSearch()).default || (await this.loadMiniSearch())
 
       this.miniSearch = new MiniSearch({
-        fields: ["title", "description", "content", "keywords"],
+        fields: ["title", "description", "content", "keywords", "code"],
         storeFields: ["title", "description"],
         searchOptions: {
-          boost: { title: 3, description: 2, keywords: 4 },
+          boost: { title: 3, description: 2, keywords: 4, code: 0.5 },
           fuzzy: 0.2,
           prefix: true
         }
@@ -58,7 +58,7 @@ export default class extends Controller {
 
   search() {
     if (this.debounceTimer) clearTimeout(this.debounceTimer)
-    this.debounceTimer = setTimeout(() => this.performSearch(), 150)
+    this.debounceTimer = setTimeout(() => this.performSearch(), 50)
   }
 
   performSearch() {
@@ -71,16 +71,21 @@ export default class extends Controller {
 
     const results = this.miniSearch.search(query)
     const matchingSlugs = new Set(results.map(r => r.id))
+    const scoreBySlug = new Map(results.map(r => [r.id, r.score]))
 
-    this.cardTargets.forEach(card => {
-      const slug = card.dataset.slug
-      card.classList.toggle("hidden", !matchingSlugs.has(slug))
-    })
-
+    // Reorder cards within each category by relevance score
     this.categoryTargets.forEach(section => {
-      const cards = section.querySelectorAll("[data-docs-search-target='card']")
-      const hasVisible = Array.from(cards).some(c => !c.classList.contains("hidden"))
-      section.classList.toggle("hidden", !hasVisible)
+      const cards = Array.from(section.querySelectorAll("[data-docs-search-target='card']"))
+      cards.forEach(card => {
+        const slug = card.dataset.slug
+        card.classList.toggle("hidden", !matchingSlugs.has(slug))
+      })
+
+      const visibleCards = cards.filter(c => !c.classList.contains("hidden"))
+      visibleCards.sort((a, b) => (scoreBySlug.get(b.dataset.slug) || 0) - (scoreBySlug.get(a.dataset.slug) || 0))
+      visibleCards.forEach(card => card.parentElement.appendChild(card))
+
+      section.classList.toggle("hidden", visibleCards.length === 0)
     })
 
     const hasResults = matchingSlugs.size > 0
@@ -91,7 +96,13 @@ export default class extends Controller {
 
   showAll() {
     this.cardTargets.forEach(card => card.classList.remove("hidden"))
-    this.categoryTargets.forEach(section => section.classList.remove("hidden"))
+    this.categoryTargets.forEach(section => {
+      section.classList.remove("hidden")
+      // Restore original order by slug
+      const cards = Array.from(section.querySelectorAll("[data-docs-search-target='card']"))
+      cards.sort((a, b) => a.dataset.slug.localeCompare(b.dataset.slug))
+      cards.forEach(card => card.parentElement.appendChild(card))
+    })
     if (this.hasNoResultsTarget) {
       this.noResultsTarget.classList.add("hidden")
     }

data/app/controllers/markdowndocs/application_controller.rb

@@ -4,19 +4,20 @@ module Markdowndocs
   class ApplicationController < ::ApplicationController
     protect_from_forgery with: :exception
 
-    # Fix route helper isolation caused by isolate_namespace.
+    # Use the engine's own layout to avoid route helper conflicts.
+    # Host apps that shared their application layout with the engine
+    # would see route helpers (about_path, signout_path, etc.) resolve
+    # against the engine's namespace instead of the main app.
     #
-    # The problem: host app route helpers (about_path, contact_path, etc.)
-    # exist in the view context but resolve against the engine's namespace,
-    # so about_path returns "/docs/about" instead of "/about".
+    # Host apps can customize by overriding this layout at:
+    #   app/views/layouts/markdowndocs/application.html.erb
     #
-    # method_missing doesn't help because the methods already exist —
-    # they just resolve wrong. We need to override them explicitly.
-    #
-    # This before_action builds a helper module on first request (when
-    # routes are fully loaded) that defines every host app route helper
-    # as a delegation to main_app.
-    before_action :ensure_host_route_helpers
+    # The layout provides content_for blocks:
+    #   :docs_header — rendered above main content (for nav/header)
+    #   :docs_footer — rendered below main content (for footer)
+    #   :head        — injected into <head> (for extra stylesheets/scripts)
+    #   :title       — page title (defaults to "Documentation")
+    layout -> { Markdowndocs.config.layout }
 
     # Support Rails 8 built-in authentication (allow_unauthenticated_access)
     # without requiring it — works with any auth system or none at all
@@ -26,21 +27,5 @@ module Markdowndocs
 
     # Resume session if the host app supports it (Rails 8 auth)
     before_action :resume_session, if: -> { respond_to?(:resume_session, true) }
-
-    private
-
-    def ensure_host_route_helpers
-      return if self.class.instance_variable_get(:@host_routes_delegated)
-
-      helper_module = Module.new do
-        Rails.application.routes.named_routes.names.each do |name|
-          define_method(:"#{name}_path") { |*args, **kwargs| main_app.send(:"#{name}_path", *args, **kwargs) }
-          define_method(:"#{name}_url") { |*args, **kwargs| main_app.send(:"#{name}_url", *args, **kwargs) }
-        end
-      end
-
-      self.class.helper(helper_module)
-      self.class.instance_variable_set(:@host_routes_delegated, true)
-    end
   end
 end

data/app/controllers/markdowndocs/docs_controller.rb

@@ -27,7 +27,8 @@ module Markdowndocs
             title: doc.title,
             description: doc.description,
             content: doc.plain_text_content,
-            keywords: doc.keywords.join(" ")
+            keywords: doc.keywords.join(" "),
+            code: doc.code_content
           }
         end.to_json
       end

data/app/models/markdowndocs/documentation.rb

@@ -98,6 +98,13 @@ module Markdowndocs
       text.strip
     end
 
+    # Returns text extracted from fenced code blocks for search indexing.
+    def code_content
+      parsed = parse_frontmatter
+      blocks = parsed[:markdown].scan(/```\w*\n([\s\S]*?)```/)
+      blocks.flatten.join(" ").gsub(/\s+/, " ").strip
+    end
+
     private
 
     def derive_slug

data/app/views/layouts/markdowndocs/application.html.erb

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title><%= content_for(:title) || "Documentation" %></title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= yield :head %>
+    <%= stylesheet_link_tag "application", "data-turbo-track": "reload" rescue nil %>
+    <%= javascript_importmap_tags rescue nil %>
+  </head>
+
+  <body class="min-h-screen flex flex-col bg-gray-50">
+    <%= yield :docs_header %>
+
+    <main id="main-content" role="main" class="flex-1">
+      <%= yield %>
+    </main>
+
+    <%= yield :docs_footer %>
+  </body>
+</html>

data/lib/markdowndocs/configuration.rb

@@ -4,7 +4,8 @@ module Markdowndocs
   class Configuration
     attr_accessor :docs_path, :categories, :modes, :default_mode,
       :markdown_options, :rouge_theme, :cache_expiry,
-      :user_mode_resolver, :user_mode_saver, :search_enabled
+      :user_mode_resolver, :user_mode_saver, :search_enabled,
+      :layout
 
     def initialize
       @docs_path = nil # Resolved lazily so Rails.root is available
@@ -17,6 +18,7 @@ module Markdowndocs
       @user_mode_resolver = nil
       @user_mode_saver = nil
       @search_enabled = false
+      @layout = "markdowndocs/application"
     end
 
     # Lazily resolve docs_path so Rails.root is available

data/lib/markdowndocs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Markdowndocs
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markdowndocs
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Dave Chmura
@@ -87,6 +87,7 @@ files:
 - app/helpers/markdowndocs/docs_helper.rb
 - app/models/markdowndocs/documentation.rb
 - app/services/markdowndocs/markdown_renderer.rb
+- app/views/layouts/markdowndocs/application.html.erb
 - app/views/markdowndocs/docs/_breadcrumb.html.erb
 - app/views/markdowndocs/docs/_card.html.erb
 - app/views/markdowndocs/docs/_mode_switcher.html.erb