hotdocs 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eda140e352c4f1836ac78536db4c3e594626a8405e0f0963bd636b3263a94280
-  data.tar.gz: e38d4fcb9d6c56474bd16af2cb64c74aff10737affcb0cb25d7dc192f25e8746
+  metadata.gz: e9062e9c27d95f790d4a77b9508b3ac57b518d41573896f358e508d03eb5b676
+  data.tar.gz: 29d4da1687c46d5bf2821aae114a96d30191c94204ab6936fd82892f0ed117ce
 SHA512:
-  metadata.gz: ae97c6c8c80ec06bcd88e3d64087c0dcf7337a8f054afaa83a97c56c5c1db1924252c8d63ee3c9042586ab3df71c41f886fcbe3f7262effdff812b560cf28623
-  data.tar.gz: e485b23974e0aeced4827f09a1f1d20b2050c5afff8514436c90d0bf63f01485cf3c13fefab4bdde251055faa471ccf3c6ceb4389c9cc6295496acd0ab0fefa1
+  metadata.gz: 568702e50ee8305c0858c46e2acad029e3cf9c3c6f45517fe566fa73980025b67e389316694e8d0ac878f5bea4da98c7cd19923deccaa340192384bb26a66a7c
+  data.tar.gz: 9acea8151aa28cb1a6d89d21a45553cba06b86b093ff20aa87f6632a95d9250b09b698bf6c160cfa3f14f5c0905f5472e259e9a2aab7d23b6a9e2d8d4aff176a

data/README.md

@@ -22,7 +22,7 @@ HotDocs is a set of optimized Rails components & tools for writing docs:
 | Styled components you can customize                       | ✅      | ✅     | ✅         |
 | Markdown (with syntax highlight & themes)                 | 🚀      | 👍     | 🚀         |
 | Static export                                             | 🔜 🚀   | 👍     | 🚀         |
-| Search                                                    | 🔜 ✅   | 🔌     | 🔌         |
+| Search                                                    |  ✅     | 🔌     | 🔌         |
 | Light / Dark                                              | 🔜 ✅   | 🔌     | ✅         |
 | Open source                                               | ✅      | ✅     | ✅         |
 | Free                                                      | ✅      | ✅     | ✅         |

data/app/assets/javascript/controllers/search_controller.js

@@ -0,0 +1,155 @@
+import { Controller } from "@hotwired/stimulus";
+import lunr from "lunr";
+
+export default class extends Controller {
+  static targets = ["search", "dialog", "results", "resultTemplate", "data"];
+
+  connect() {
+    this._allowOpening();
+  }
+
+  disconnect() {
+    document.removeEventListener("keydown", this.keydownOpen);
+    document.removeEventListener("click", this.clickClose, { once: true });
+  }
+
+  open() {
+    if (this.searchTarget.open) return;
+    this._allowClosing();
+    this._initSearch();
+    this.searchTarget.showModal();
+  }
+
+  search = debounce(this._search, 200);
+
+  _allowOpening() {
+    this.keydownOpen = (event) => {
+      if (this.searchTarget.open || event.key !== "/") return;
+      event.preventDefault();
+      this.open();
+    };
+
+    document.addEventListener("keydown", this.keydownOpen);
+  }
+
+  _allowClosing() {
+    this.clickClose = (event) => {
+      if (this.dialogTarget.contains(event.target)) return;
+      this.searchTarget.close();
+    };
+
+    document.addEventListener("click", this.clickClose, { once: true });
+  }
+
+  _initSearch() {
+    if (this.documents) {
+      this.searchTarget.classList.add("loaded");
+      return;
+    }
+    this._createSearchIndex();
+    this.searchTarget.classList.add("loaded");
+  }
+
+  _createSearchIndex() {
+    const documents = this._getDocuments();
+    if (documents.length === 0) return;
+    this.documents = documents;
+    this.searchIndex = lunr(function () {
+      this.ref("title");
+      this.field("title", { boost: 5 });
+      this.field("text");
+      this.metadataWhitelist = ["position"];
+      documents.forEach(function (doc) {
+        this.add(doc);
+      }, this);
+    });
+  }
+
+  _getDocuments() {
+    const searchData = JSON.parse(this.dataTarget.textContent);
+    if (searchData.length === 0) {
+      console.warn(
+        [
+          "The search data is not present in the HTML.",
+          "If you are in development, run `bundle exec rails hotdocs:index`.",
+          "If you are in production, assets compilation should have taken care of it.",
+        ].join(" ")
+      );
+    }
+    return searchData.map((data) => {
+      const div = document.createElement("div");
+      div.innerHTML = data.html;
+      return { ...data, text: div.innerText };
+    });
+  }
+
+  _search(event) {
+    if (!this.searchIndex) return;
+    const query = event.target.value;
+    const results = this.searchIndex.search(query).slice(0, 10);
+    this._displayResults(results);
+  }
+
+  _displayResults(results) {
+    this.resultsTarget.innerHTML = null;
+
+    results.forEach((result) => {
+      const matches = Object.keys(result.matchData.metadata);
+      const excerpt = this._withExcerpt(matches, result)[0];
+      if (!excerpt) return;
+      this.resultsTarget.appendChild(this._createResultElement(excerpt));
+    });
+  }
+
+  _withExcerpt(matches, result) {
+    return matches.flatMap((match) => {
+      return Object.keys(result.matchData.metadata[match]).map((key) => {
+        const position = result.matchData.metadata[match][key].position[0];
+        const [sliceStart, sliceLength] = key === "text" ? position : [0, 0];
+        const doc = this.documents.find((doc) => doc.title === result.ref);
+        const excerpt = this._excerpt(doc.text, sliceStart, sliceLength);
+        return { ...doc, excerpt };
+      });
+    });
+  }
+
+  _excerpt(doc, sliceStart, sliceLength) {
+    const startPos = Math.max(sliceStart - 80, 0);
+    const endPos = Math.min(sliceStart + sliceLength + 80, doc.length);
+    return [
+      startPos > 0 ? "..." : "",
+      doc.slice(startPos, sliceStart),
+      "<strong>" +
+        escapeHtmlEntities(doc.slice(sliceStart, sliceStart + sliceLength)) +
+        "</strong>",
+      doc.slice(sliceStart + sliceLength, endPos),
+      endPos < doc.length ? "..." : "",
+    ].join("");
+  }
+
+  _createResultElement(excerpt) {
+    const clone = this.resultTemplateTarget.content.cloneNode(true);
+    const li = clone.querySelector("li");
+    li.querySelector("h1").innerHTML = `${excerpt.parent} > ${excerpt.title}`;
+    li.querySelector("a").innerHTML = excerpt.excerpt;
+    li.querySelector("a").href = excerpt.url;
+    return clone;
+  }
+}
+
+function debounce(func, wait) {
+  let timeoutId;
+
+  return function (...args) {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => func.apply(this, args), wait);
+  };
+}
+
+function escapeHtmlEntities(string) {
+  return String(string)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

data/app/assets/stylesheets/hotdocs/application.css

@@ -246,6 +246,127 @@ body {
   font-weight: bold;
 }
 
+/* CSS: SEARCH */
+
+:root {
+  --search-background-color: #f5f6f7;
+  --search-button-background-color: #e9e9e9;
+  --search-excerpt-background-color: white;
+  --search-excerpt-border-color: #d7d7d7;
+  --search-text-color: var(--text-color);
+}
+
+[data-theme=dark]:root {
+  --search-background-color: #242526;
+  --search-button-background-color: #1b1b1b;
+  --search-excerpt-background-color: #1b1b1b;
+  --search-excerpt-border-color: #535353;
+}
+
+.search-button {
+  align-items: center;
+  background-color: var(--search-background-color);
+  border: solid 1px transparent;
+  border-radius: 99999px;
+  display: flex;
+  gap: 0.5ch;
+  padding: 0.5rem 0.5rem;
+
+  @media (min-width: 40rem) {
+    padding: 0.25rem 0.5rem;
+  }
+
+  &:hover {
+    background: none;
+    border: solid 1px var(--nav-link-color);
+  }
+}
+
+.search-button__icon {
+  height: 1.2rem;
+  width: 1.2rem;
+}
+
+.search-button__label {
+  display: none;
+
+  @media (min-width: 40rem) {
+    display: initial;
+  }
+}
+
+body:has(.search:open), body:has(.search[open]) {
+  overflow: hidden;
+}
+
+.search {
+  background-color: #000000dd;
+  bottom: 0;
+  color: var(--search-text-color);
+  height: 100vh;
+  left: 0;
+  max-height: 100vh;
+  max-width: 100vw;
+  padding-inline: 1rem;
+  position: fixed;
+  right: 0;
+  top: 0;
+  width: 100vw;
+}
+
+::backdrop {
+  display: none;
+}
+
+.search__dialog {
+  overflow: auto;
+  background-color: var(--search-background-color);
+  border-radius: 0.375rem;
+  max-height: calc(100vh - 120px);
+  margin: 60px auto auto;
+  max-width: 560px;
+  padding: 1rem;
+  width: auto;
+}
+
+.search__input {
+  background-color: var(--search-excerpt-background-color);
+  border: 1px solid #808080;
+  border-radius: 0.2rem;
+  padding: 0.3rem 0.5rem;
+  width: 100%;
+
+  &:focus-visible {
+    outline: solid 2px #0077ff;
+  }
+}
+
+.search__result {
+  margin-top: 1.5rem;
+
+  &:first-child {
+    margin-top: 1rem;
+  }
+}
+
+.search.loaded .search__result--loading {
+  display: none;
+}
+
+.search__result-excerpt {
+  background-color: var(--search-excerpt-background-color);
+  border: 1px solid var(--search-excerpt-border-color);
+  border-radius: 0.2rem;
+  box-shadow: 0 1px 3px 0 #0000001a;
+  display: block;
+  margin-top: 0.2rem;
+  padding: 0.3rem 0.5rem;
+
+  &:hover {
+    outline: solid 2px #0077ff;
+  }
+}
+
 /* CSS: MENU */
 
 :root {
@@ -363,8 +484,10 @@ body {
 .main {
   display: flex;
   flex-grow: 1;
-  max-width: 100%;
+  margin-inline: auto;
+  max-width: 82rem;
   padding-bottom: var(--content-padding-bottom);
+  width: 100%;
 
   @media (min-width: 64rem) {
     width: calc(100% - 20rem);

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

@@ -9,7 +9,30 @@
     <%= stylesheet_link_tag "hotdocs/application", media: "all", "data-turbo-track": "reload" %>
   </head>
 
-  <body>
+  <body data-controller="search">
+    <dialog data-search-target="search" class="search">
+      <div data-search-target="dialog" class="search__dialog">
+        <input autofocus data-action="input->search#search" type="text" class="search__input"></input>
+
+        <template data-search-target="resultTemplate">
+          <li class="search__result">
+            <h1></h1>
+            <a href="#" class="search__result-excerpt"></a>
+          </li>
+        </template>
+
+        <ul data-search-target="results">
+          <li class="search__result search__result--loading">
+            Loading index...
+          </li>
+        </ul>
+      </div>
+
+      <script type="application/json" data-search-target="data">
+        <%= raw(Rails.application.assets.resolver.read("search_data.json")&.force_encoding("UTF-8") || [].to_json) %>
+      </script>
+    </dialog>
+
     <nav class="nav" data-controller="sidenav" data-sidenav-open-class-value="sidenav--open" data-sidenav-main-menu-class-value="sidenav__sections--main">
       <div class="nav__section">
         <button class="nav__toggle" type="button" aria-label="Toggle navigation" aria-expanded="false" data-action="click->sidenav#open">
@@ -39,6 +62,14 @@
             <%= item %>
           <% end %>
         </div>
+
+        <button type="button" data-action="click->search#open:stop" class="search-button">
+          <svg class="search-button__icon" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z" />
+          </svg>
+
+          <span class="search-button__label">Type / to search</span>
+        </button>
       </div>
 
       <div class="sidenav-backdrop"></div>

data/lib/hotdocs/markdown.rb

@@ -3,9 +3,8 @@ require "open3"
 class MarkdownHandler
   def self.prepare(engine)
     # Install npm packages
+    # `capture3` raises if deno is not available
     Open3.capture3("deno --allow-read --allow-env --node-modules-dir=auto #{engine.root.join("lib/hotdocs/markdown.mjs")}", stdin_data: "")
-  rescue
-    Rails.logger.info("deno not found: Could not install npm packages.")
   end
 
   def initialize(engine)

data/lib/hotdocs/version.rb

@@ -1,3 +1,3 @@
 module Hotdocs
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/install/install.rb

@@ -7,7 +7,7 @@ def gem?(name)
 
   regex = /gem ["']#{name}["']/
   if File.readlines(gemfile_path).grep(regex).any?
-    say "#{name} already installed"
+    say "#{name} already bundled"
     false
   else
     run("bundle add #{name}") || abort("Failed to add #{name} to the bundle")
@@ -15,6 +15,19 @@ def gem?(name)
   end
 end
 
+def pin?(name)
+  importmap_path = Pathname(destination_root).join("config/importmap.rb")
+
+  regex = /pin ["']#{name}["']/
+  if File.readlines(importmap_path).grep(regex).any?
+    say "#{name} already pinned"
+    false
+  else
+    run("bin/importmap pin #{name}") || abort("Failed to pin #{name} to the importmap")
+    true
+  end
+end
+
 unless system("command -v deno > /dev/null 2>&1")
   abort "Install deno before running this task. Read more: https://deno.com"
 end
@@ -27,13 +40,14 @@ gem?("importmap-rails") && run("bin/rails importmap:install")
 gem?("turbo-rails") && run("bin/rails turbo:install")
 gem?("stimulus-rails") && run("bin/rails stimulus:install")
 
-generate(:controller, "hotdocs", "index", "--skip-routes --no-helper --no-test-framework --no-view-specs")
-remove_file(Pathname(destination_root).join("app/views/hotdocs/index.html.erb"))
-inject_into_class(Pathname(destination_root).join("app/controllers/hotdocs_controller.rb"), "HotdocsController", <<-LINES)
-  helper Hotdocs::Engine.helpers
-  layout "hotdocs"
+pin?("lunr")
 
-LINES
+create_file(Pathname(destination_root).join("app/controllers/hotdocs_controller.rb"), <<~CONTROLLER)
+  class HotdocsController < ApplicationController
+    helper Hotdocs::Engine.helpers
+    layout "hotdocs"
+  end
+CONTROLLER
 
 create_file(Pathname(destination_root).join("app/views/layouts/hotdocs.html.erb"), <<~LAYOUT)
   <% content_for :head do %>
@@ -127,6 +141,18 @@ create_file(Pathname(destination_root).join("app/helpers/hotdocs_helper.rb"), <<
 HELPER
 
 create_file(Pathname(destination_root).join("app/assets/stylesheets/prism.css"), <<~CSS)
+  /* Find more themes on: https://github.com/PrismJS/prism-themes */
+
+  /*
+     Darcula theme
+
+     Adapted from a theme based on:
+     IntelliJ Darcula Theme (https://github.com/bulenkov/Darcula)
+
+     @author Alexandre Paradis <service.paradis@gmail.com>
+     @version 1.0
+  */
+
   code[class*="language-"],
   pre[class*="language-"] {
     color: #a9b7c6;
@@ -278,10 +304,19 @@ create_file(Pathname(destination_root).join("app/assets/stylesheets/prism.css"),
   }
 CSS
 
+empty_directory "app/assets/builds"
+keep_file "app/assets/builds"
+if Pathname(destination_root).join(".gitignore").exist?
+  append_to_file(".gitignore", %(\n/app/assets/builds/*\n!/app/assets/builds/.keep\n))
+  append_to_file(".gitignore", %(\n/node_modules/\n))
+end
+
 routes_path = Pathname(destination_root).join("config/routes.rb")
-regex = /^\s*(?!#)root/
-if File.readlines(routes_path).grep(regex).any?
-  route "get '/hotdocs', to: 'hotdocs#index'"
-else
-  route "root to: 'hotdocs#index'"
+routes = File.readlines(routes_path)
+unless routes.grep(/hotdocs#index/).any?
+  if routes.grep(/^\s*(?!#)root/).any?
+    route "get '/hotdocs', to: 'hotdocs#index'"
+  else
+    route "root to: 'hotdocs#index'"
+  end
 end

data/lib/tasks/hotdocs_tasks.rake

@@ -1,9 +1,91 @@
 namespace :hotdocs do
   desc "Install HotDocs into the app"
   task :install do
-    previous_location = ENV["LOCATION"]
-    ENV["LOCATION"] = File.expand_path("../install/install.rb", __dir__)
-    Rake::Task["app:template"].invoke
-    ENV["LOCATION"] = previous_location
+    location = File.expand_path("../install/install.rb", __dir__)
+    system("#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{location}")
+    # Needed for hotdocs:index to find the generated ::HotdocsController
+    Rails.application.reloader.reload!
+    Rake::Task["hotdocs:index"].invoke
   end
+
+  desc "Build search data"
+  task index: :environment do
+    path = Rails.root.join("app/assets/builds/search_data.json")
+    # Propshaft caches the `@load_path`s. Rendering data goes through Propshaft
+    # because of the assets, so the file must exist before rendering.
+    File.write(path, "")
+    data = render_search_data.call.to_json
+    File.write(path, data)
+  end
+end
+
+if Rake::Task.task_defined?("assets:precompile")
+  Rake::Task["assets:precompile"].enhance([ "hotdocs:index" ])
+end
+
+if Rake::Task.task_defined?("test:prepare")
+  Rake::Task["test:prepare"].enhance([ "hotdocs:index" ])
+elsif Rake::Task.task_defined?("spec:prepare")
+  Rake::Task["spec:prepare"].enhance([ "hotdocs:index" ])
+elsif Rake::Task.task_defined?("db:test:prepare")
+  Rake::Task["db:test:prepare"].enhance([ "hotdocs:index" ])
+end
+
+def render_search_data
+  renderer = Class.new(::HotdocsController) do
+    include Hotdocs::ApplicationHelper
+
+    def call
+      with_no_view_annotations { render_search_data }
+    end
+
+    private
+
+    def with_no_view_annotations(&)
+      annotate = Rails.application.config.action_view.annotate_rendered_view_with_filenames
+      Rails.application.config.action_view.annotate_rendered_view_with_filenames = false
+      yield
+    ensure
+      Rails.application.config.action_view.annotate_rendered_view_with_filename = annotate
+    end
+
+    def render_search_data
+      pages = pages_from(menu_items)
+      $stderr.puts "Indexing #{pages.size} pages:"
+      render_pages(pages).tap { $stderr.puts }
+    end
+
+    def render_pages(pages)
+      pages.filter_map do |page|
+        $stderr.putc "."
+        html = render_path(page.fetch(:url))
+        next unless html
+        { **page, html: html }
+      end
+    end
+
+    def pages_from(menu_items, parent = "Docs")
+      menu_items
+        .filter { _1.fetch(:url).start_with?("/") }
+        .flat_map do |item|
+          current = { title: item.fetch(:label), parent: parent, url: item.fetch(:url) }
+          children = pages_from(item.fetch(:children, []), item.fetch(:label))
+          [ current ] + children
+        end
+    end
+
+    def render_path(path)
+      controller, action = Rails.application.routes.recognize_path(path).values_at(:controller, :action)
+      render_to_string("#{controller}/#{action}", layout: false)
+    rescue ActionController::RoutingError => error
+      logger.info("Skipped building #{path}: #{error}")
+      nil
+    end
+
+    def request
+      ActionDispatch::TestRequest.create
+    end
+  end
+
+  renderer.new
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: hotdocs
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - 3v0k4
 bindir: bin
 cert_chain: []
-date: 2025-03-20 00:00:00.000000000 Z
+date: 2025-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -36,6 +36,7 @@ files:
 - Rakefile
 - app/assets/images/hotdocs/icon.svg
 - app/assets/javascript/controllers/accordion_controller.js
+- app/assets/javascript/controllers/search_controller.js
 - app/assets/javascript/controllers/sidenav_controller.js
 - app/assets/javascript/controllers/toc_controller.js
 - app/assets/stylesheets/hotdocs/application.css