hotdocs 0.2.0 → 0.3.0

data/lib/hotdocs/markdown.rb

@@ -1,31 +1,28 @@
-require "open3"
+require "kramdown"
+require "kramdown-parser-gfm"
+require "rouge"
 
-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: "")
-  end
-
-  def initialize(engine)
-    @engine = engine
-  end
+require_relative "kramdown_alerts"
 
+class MarkdownHandler
   def call(template, source)
-    compiled = ::HotdocsController.render(inline: source, handler: :erb)
-    # `capture3` raises if deno is not available
-    out, err, status = Open3.capture3("deno --allow-read --allow-env --node-modules-dir=auto #{@engine.root.join("lib/hotdocs/markdown.mjs")}", stdin_data: compiled)
-    Rails.logger.error("Failed to compile markdown: #{err}") unless status.success?
-
-    if !err.empty? && !err.include?("The following packages are deprecated")
-      # Render the compiled erb (without the md step).
-      # It won't look great, but better than nothing.
-      return <<~STRING
-        @output_buffer.safe_append='#{compiled}'.freeze;
-        @output_buffer
-      STRING
+    # If the template contains a `fetcher`, do not allow Rails to cache the page.
+    if source.match?(%r{<%= fetcher.* do %>})
+      ActionView::PathRegistry.all_resolvers.each do |resolver|
+        resolver.instance_eval do
+          @unbound_templates.delete(template.virtual_path)
+        end
+      end
     end
 
+    compiled_template = ::HotdocsController.render(inline: source, handler: :erb)
+    out = Kramdown::Document.new(
+      compiled_template,
+      input: "GFM",
+      auto_ids: false,
+      syntax_highlighter_opts: { css_class: "highlight" }
+    ).to_html
+
     content_fors = ActionView::Template::Handlers::ERB
       .new
       .call(template, source)
@@ -34,7 +31,7 @@ class MarkdownHandler
 
     <<~STRING
       #{content_fors.join(";")}
-      @output_buffer.safe_append='#{out}'.freeze;
+      @output_buffer.safe_append='#{out.gsub("'", "\\\\'")}'.freeze;
       @output_buffer
     STRING
   end

data/lib/hotdocs/version.rb

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

data/lib/install/install.rb

@@ -15,23 +15,18 @@ def gem?(name)
   end
 end
 
-def pin?(name)
+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
+    gsub_file importmap_path, /(pin ["']#{name}["'])(.*)/, '\1, preload: "hotdocs"\2'
   end
 end
 
-unless system("command -v deno > /dev/null 2>&1")
-  abort "Install deno before running this task. Read more: https://deno.com"
-end
-
 if File.exist?("app/assets/config/manifest.js")
   abort "Migrate to Propshaft before running this task. Read more: https://github.com/rails/propshaft/blob/main/UPGRADING.md#3-migrate-from-sprockets-to-propshaft"
 end
@@ -40,27 +35,40 @@ gem?("importmap-rails") && run("bin/rails importmap:install")
 gem?("turbo-rails") && run("bin/rails turbo:install")
 gem?("stimulus-rails") && run("bin/rails stimulus:install")
 
-pin?("lunr")
+create_file(Pathname(destination_root).join("app/javascript/hotdocs.js"), <<~FILE)
+  import "@hotwired/turbo-rails";
+  import "controllers";
 
-create_file(Pathname(destination_root).join("app/controllers/hotdocs_controller.rb"), <<~CONTROLLER)
+  import { application } from "controllers/application"
+  import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+  eagerLoadControllersFrom("hotdocs/controllers", application)
+FILE
+
+importmap_path = Pathname(destination_root).join("config/importmap.rb")
+append_to_file(importmap_path, %(pin "hotdocs", preload: "hotdocs"\n))
+pin("lunr")
+
+create_file(Pathname(destination_root).join("app/controllers/hotdocs_controller.rb"), <<~FILE)
   class HotdocsController < ApplicationController
     helper Hotdocs::Engine.helpers
     layout "hotdocs"
   end
-CONTROLLER
+FILE
 
-create_file(Pathname(destination_root).join("app/views/layouts/hotdocs.html.erb"), <<~LAYOUT)
+create_file(Pathname(destination_root).join("app/views/layouts/hotdocs.html.erb"), <<~FILE)
   <% content_for :head do %>
     <%= content_for(:title, "HotDocs") unless content_for?(:title) %>
     <meta name="viewport" content="width=device-width,initial-scale=1">
-    <%= stylesheet_link_tag :app %>
-    <%= javascript_importmap_tags %>
+    <%= stylesheet_link_tag "hotdocs/application" %>
+    <%= stylesheet_link_tag "website" %>
+    <%= stylesheet_link_tag "rouge" %>
+    <%= javascript_importmap_tags "hotdocs" %>
   <% end %>
 
   <%= render template: "layouts/hotdocs/application" %>
-LAYOUT
+FILE
 
-create_file(Pathname(destination_root).join("app/views/hotdocs/index.html.mderb"), <<~VIEW)
+create_file(Pathname(destination_root).join("app/views/hotdocs/index.html.mderb"), <<~FILE)
   <%= content_for(:title, "Welcome") %>
 
   # Welcome to HotDocs
@@ -69,23 +77,24 @@ create_file(Pathname(destination_root).join("app/views/hotdocs/index.html.mderb"
 
   ## Todos
 
-  <input type="checkbox" id="first">
-  <label for="first"> Update <code>app/views/layouts/hotdocs.html.erb</code></label><br>
-  <input type="checkbox" id="second">
-  <label for="second"> Update <code>app/helpers/hotdocs_helper.rb</code></label><br>
-  <input type="checkbox" id="third">
-  <label for="third"> Maybe read the docs: <a href="https://hotdocsrails.com/" target="_blank">hotdocsrails.com</a></label>
-VIEW
+  <input type="checkbox" id="first"><label for="first"> Update <code>app/views/layouts/hotdocs.html.erb</code></label>
+  <input type="checkbox" id="second"><label for="second"> Update <code>app/helpers/hotdocs_helper.rb</code></label>
+  <input type="checkbox" id="third"><label for="third"> Maybe read the docs: <a href="https://hotdocsrails.com/" target="_blank">hotdocsrails.com</a></label>
+FILE
 
 copy_file("app/assets/images/hotdocs/icon.svg", Pathname(destination_root).join("app/assets/images/hotdocs.svg"))
 
-inject_into_module(Pathname(destination_root).join("app/helpers/application_helper.rb"), "ApplicationHelper", "  include HotdocsHelper\n\n")
-create_file(Pathname(destination_root).join("app/helpers/hotdocs_helper.rb"), <<~HELPER)
+create_file(Pathname(destination_root).join("app/helpers/hotdocs_helper.rb"), <<~FILE)
   module HotdocsHelper
+    # @return [Logo, nil]
     def logo
       Struct.new(:src, :alt).new(asset_path("hotdocs.svg"), "A humanized and happy hot dog")
     end
 
+    def title
+      "HotDocs"
+    end
+
     def nav_left_items(classes)
       [
         active_link_to("Docs", root_path, class: Array(classes))
@@ -137,172 +146,144 @@ create_file(Pathname(destination_root).join("app/helpers/hotdocs_helper.rb"), <<
         }
       ]
     end
-  end
-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;
-    font-family: Consolas, Monaco, 'Andale Mono', monospace;
-    direction: ltr;
-    text-align: left;
-    white-space: pre;
-    word-spacing: normal;
-    word-break: normal;
-    line-height: 1.5;
-
-    -moz-tab-size: 4;
-    -o-tab-size: 4;
-    tab-size: 4;
-
-    -webkit-hyphens: none;
-    -moz-hyphens: none;
-    -ms-hyphens: none;
-    hyphens: none;
-  }
-
-  pre[class*="language-"]::-moz-selection, pre[class*="language-"] ::-moz-selection,
-  code[class*="language-"]::-moz-selection, code[class*="language-"] ::-moz-selection {
-    color: inherit;
-    background: rgba(33, 66, 131, .85);
-  }
-
-  pre[class*="language-"]::selection, pre[class*="language-"] ::selection,
-  code[class*="language-"]::selection, code[class*="language-"] ::selection {
-    color: inherit;
-    background: rgba(33, 66, 131, .85);
-  }
-
-  /* Code blocks */
-  pre[class*="language-"] {
-    padding: 1em;
-    margin: .5em 0;
-    overflow: auto;
-  }
-
-  :not(pre) > code[class*="language-"],
-  pre[class*="language-"] {
-    background: #2b2b2b;
-  }
-
-  /* Inline code */
-  :not(pre) > code[class*="language-"] {
-    padding: .1em;
-    border-radius: .3em;
-  }
-
-  .token.comment,
-  .token.prolog,
-  .token.cdata {
-    color: #808080;
-  }
-
-  .token.delimiter,
-  .token.boolean,
-  .token.keyword,
-  .token.selector,
-  .token.important,
-  .token.atrule {
-    color: #cc7832;
-  }
-
-  .token.operator,
-  .token.punctuation,
-  .token.attr-name {
-    color: #a9b7c6;
-  }
 
-  .token.tag,
-  .token.tag .punctuation,
-  .token.doctype,
-  .token.builtin {
-    color: #e8bf6a;
-  }
-
-  .token.entity,
-  .token.number,
-  .token.symbol {
-    color: #6897bb;
-  }
-
-  .token.property,
-  .token.constant,
-  .token.variable {
-    color: #9876aa;
-  }
-
-  .token.string,
-  .token.char {
-    color: #6a8759;
-  }
-
-  .token.attr-value,
-  .token.attr-value .punctuation {
-    color: #a5c261;
-  }
-
-  .token.attr-value .punctuation:first-child {
-    color: #a9b7c6;
-  }
-
-  .token.url {
-    color: #287bde;
-    text-decoration: underline;
-  }
-
-  .token.function {
-    color: #ffc66d;
-  }
-
-  .token.regex {
-    background: #364135;
-  }
-
-  .token.bold {
-    font-weight: bold;
-  }
-
-  .token.italic {
-    font-style: italic;
-  }
-
-  .token.inserted {
-    background: #294436;
-  }
+    def fetcher_host
+      "http://127.0.0.1:3000"
+    end
+  end
+FILE
 
-  .token.deleted {
-    background: #484a4a;
+create_file(Pathname(destination_root).join("app/assets/stylesheets/website.css"), <<~FILE)
+  :root {
+    --docs-code-background-color: #eee;
+    --docs-code-border-color: #00000022;
+    --docs-text-color: #1c1e21;
   }
 
-  code.language-css .token.property,
-  code.language-css .token.property + .token.punctuation {
-    color: #a9b7c6;
+  [data-theme=dark]:root {
+    --docs-code-background-color: #2b2b2b;
+    --docs-code-border-color: #ffffff22;
+    --docs-text-color: #e3e1de;
   }
 
-  code.language-css .token.id {
-    color: #ffc66d;
+  .article {
+    color: var(--docs-text-color);
+
+    a {
+      color: var(--docs-text-color);
+
+      &:has(code) {
+        text-underline-position: under;
+        text-decoration-thickness: 1px;
+      }
+    }
+
+    pre {
+      -webkit-overflow-scrolling: touch;
+      border-radius: .375rem;
+      box-sizing: border-box;
+      overflow-x: auto;
+      width: 100%;
+    }
+
+    code:not(pre code) {
+      background: var(--docs-code-background-color);
+      border-radius: 0.375rem;
+      border: .1rem solid var(--docs-code-border-color);
+      display: inline;
+      overflow-x: auto;
+      overflow: auto;
+      padding: 0.1rem 0.2rem;
+      word-break: break-word;
+    }
   }
-
-  code.language-css .token.selector > .token.class,
-  code.language-css .token.selector > .token.attribute,
-  code.language-css .token.selector > .token.pseudo-class,
-  code.language-css .token.selector > .token.pseudo-element {
-    color: #ffc66d;
+FILE
+
+create_file(Pathname(destination_root).join("app/assets/stylesheets/rouge.css"), <<~FILE)
+  .article {
+    .highlight .hll { background-color: #6e7681 }
+    .highlight { background: #0d1117; color: #e6edf3 }
+    .highlight .c { color: #8b949e; font-style: italic } /* Comment */
+    .highlight .err { color: #f85149 } /* Error */
+    .highlight .esc { color: #e6edf3 } /* Escape */
+    .highlight .g { color: #e6edf3 } /* Generic */
+    .highlight .k { color: #ff7b72 } /* Keyword */
+    .highlight .l { color: #a5d6ff } /* Literal */
+    .highlight .n { color: #e6edf3 } /* Name */
+    .highlight .o { color: #ff7b72; font-weight: bold } /* Operator */
+    .highlight .x { color: #e6edf3 } /* Other */
+    .highlight .p { color: #e6edf3 } /* Punctuation */
+    .highlight .ch { color: #8b949e; font-style: italic } /* Comment.Hashbang */
+    .highlight .cm { color: #8b949e; font-style: italic } /* Comment.Multiline */
+    .highlight .cp { color: #8b949e; font-weight: bold; font-style: italic } /* Comment.Preproc */
+    .highlight .cpf { color: #8b949e; font-style: italic } /* Comment.PreprocFile */
+    .highlight .c1 { color: #8b949e; font-style: italic } /* Comment.Single */
+    .highlight .cs { color: #8b949e; font-weight: bold; font-style: italic } /* Comment.Special */
+    .highlight .gd { color: #ffa198; background-color: #490202 } /* Generic.Deleted */
+    .highlight .ge { color: #e6edf3; font-style: italic } /* Generic.Emph */
+    .highlight .ges { color: #e6edf3; font-weight: bold; font-style: italic } /* Generic.EmphStrong */
+    .highlight .gr { color: #ffa198 } /* Generic.Error */
+    .highlight .gh { color: #79c0ff; font-weight: bold } /* Generic.Heading */
+    .highlight .gi { color: #56d364; background-color: #0f5323 } /* Generic.Inserted */
+    .highlight .go { color: #8b949e } /* Generic.Output */
+    .highlight .gp { color: #8b949e } /* Generic.Prompt */
+    .highlight .gs { color: #e6edf3; font-weight: bold } /* Generic.Strong */
+    .highlight .gu { color: #79c0ff } /* Generic.Subheading */
+    .highlight .gt { color: #ff7b72 } /* Generic.Traceback */
+    .highlight .g-Underline { color: #e6edf3; text-decoration: underline } /* Generic.Underline */
+    .highlight .kc { color: #79c0ff } /* Keyword.Constant */
+    .highlight .kd { color: #ff7b72 } /* Keyword.Declaration */
+    .highlight .kn { color: #ff7b72 } /* Keyword.Namespace */
+    .highlight .kp { color: #79c0ff } /* Keyword.Pseudo */
+    .highlight .kr { color: #ff7b72 } /* Keyword.Reserved */
+    .highlight .kt { color: #ff7b72 } /* Keyword.Type */
+    .highlight .ld { color: #79c0ff } /* Literal.Date */
+    .highlight .m { color: #a5d6ff } /* Literal.Number */
+    .highlight .s { color: #a5d6ff } /* Literal.String */
+    .highlight .na { color: #e6edf3 } /* Name.Attribute */
+    .highlight .nb { color: #e6edf3 } /* Name.Builtin */
+    .highlight .nc { color: #f0883e; font-weight: bold } /* Name.Class */
+    .highlight .no { color: #79c0ff; font-weight: bold } /* Name.Constant */
+    .highlight .nd { color: #d2a8ff; font-weight: bold } /* Name.Decorator */
+    .highlight .ni { color: #ffa657 } /* Name.Entity */
+    .highlight .ne { color: #f0883e; font-weight: bold } /* Name.Exception */
+    .highlight .nf { color: #d2a8ff; font-weight: bold } /* Name.Function */
+    .highlight .nl { color: #79c0ff; font-weight: bold } /* Name.Label */
+    .highlight .nn { color: #ff7b72 } /* Name.Namespace */
+    .highlight .nx { color: #e6edf3 } /* Name.Other */
+    .highlight .py { color: #79c0ff } /* Name.Property */
+    .highlight .nt { color: #7ee787 } /* Name.Tag */
+    .highlight .nv { color: #79c0ff } /* Name.Variable */
+    .highlight .ow { color: #ff7b72; font-weight: bold } /* Operator.Word */
+    .highlight .pm { color: #e6edf3 } /* Punctuation.Marker */
+    .highlight .w { color: #6e7681 } /* Text.Whitespace */
+    .highlight .mb { color: #a5d6ff } /* Literal.Number.Bin */
+    .highlight .mf { color: #a5d6ff } /* Literal.Number.Float */
+    .highlight .mh { color: #a5d6ff } /* Literal.Number.Hex */
+    .highlight .mi { color: #a5d6ff } /* Literal.Number.Integer */
+    .highlight .mo { color: #a5d6ff } /* Literal.Number.Oct */
+    .highlight .sa { color: #79c0ff } /* Literal.String.Affix */
+    .highlight .sb { color: #a5d6ff } /* Literal.String.Backtick */
+    .highlight .sc { color: #a5d6ff } /* Literal.String.Char */
+    .highlight .dl { color: #79c0ff } /* Literal.String.Delimiter */
+    .highlight .sd { color: #a5d6ff } /* Literal.String.Doc */
+    .highlight .s2 { color: #a5d6ff } /* Literal.String.Double */
+    .highlight .se { color: #79c0ff } /* Literal.String.Escape */
+    .highlight .sh { color: #79c0ff } /* Literal.String.Heredoc */
+    .highlight .si { color: #a5d6ff } /* Literal.String.Interpol */
+    .highlight .sx { color: #a5d6ff } /* Literal.String.Other */
+    .highlight .sr { color: #79c0ff } /* Literal.String.Regex */
+    .highlight .s1 { color: #a5d6ff } /* Literal.String.Single */
+    .highlight .ss { color: #a5d6ff } /* Literal.String.Symbol */
+    .highlight .bp { color: #e6edf3 } /* Name.Builtin.Pseudo */
+    .highlight .fm { color: #d2a8ff; font-weight: bold } /* Name.Function.Magic */
+    .highlight .vc { color: #79c0ff } /* Name.Variable.Class */
+    .highlight .vg { color: #79c0ff } /* Name.Variable.Global */
+    .highlight .vi { color: #79c0ff } /* Name.Variable.Instance */
+    .highlight .vm { color: #79c0ff } /* Name.Variable.Magic */
+    .highlight .il { color: #a5d6ff } /* Literal.Number.Integer.Long */
   }
-CSS
+FILE
 
 empty_directory "app/assets/builds"
 keep_file "app/assets/builds"

data/lib/tasks/hotdocs_tasks.rake

@@ -75,7 +75,9 @@ def render_search_data
     end
 
     def render_path(path)
-      controller, action = Rails.application.routes.recognize_path(path).values_at(:controller, :action)
+      base = ENV.fetch("RAILS_RELATIVE_URL_ROOT", "")
+      baseless_path = path.sub(/\A#{base}/, "")
+      controller, action = Rails.application.routes.recognize_path(baseless_path).values_at(:controller, :action)
       render_to_string("#{controller}/#{action}", layout: false)
     rescue ActionController::RoutingError => error
       logger.info("Skipped building #{path}: #{error}")

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: hotdocs
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - 3v0k4
 bindir: bin
 cert_chain: []
-date: 2025-04-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -23,6 +23,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 7.1.0
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: kramdown-parser-gfm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
 description: HotDocs is a set of optimized Rails components & tools for writing docs.
 email:
 - riccardo.odone@gmail.com
@@ -36,6 +78,7 @@ files:
 - Rakefile
 - app/assets/images/hotdocs/icon.svg
 - app/assets/javascript/controllers/accordion_controller.js
+- app/assets/javascript/controllers/fetcher_controller.js
 - app/assets/javascript/controllers/search_controller.js
 - app/assets/javascript/controllers/sidenav_controller.js
 - app/assets/javascript/controllers/toc_controller.js
@@ -47,7 +90,7 @@ files:
 - config/importmap.rb
 - lib/hotdocs.rb
 - lib/hotdocs/engine.rb
-- lib/hotdocs/markdown.mjs
+- lib/hotdocs/kramdown_alerts.rb
 - lib/hotdocs/markdown.rb
 - lib/hotdocs/version.rb
 - lib/install/install.rb
@@ -75,7 +118,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Write your docs with Ruby on Rails
 test_files: []