hotdocs 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9062e9c27d95f790d4a77b9508b3ac57b518d41573896f358e508d03eb5b676
-  data.tar.gz: 29d4da1687c46d5bf2821aae114a96d30191c94204ab6936fd82892f0ed117ce
+  metadata.gz: a04eac67f8afb072c5b6ef87e98bac8316659fe4da338d64b1fdb85b66334fd8
+  data.tar.gz: 542ea09084b1e53da0657368a3a8b4c559dbf9e0a6305be13f1ae2726ddf04f7
 SHA512:
-  metadata.gz: 568702e50ee8305c0858c46e2acad029e3cf9c3c6f45517fe566fa73980025b67e389316694e8d0ac878f5bea4da98c7cd19923deccaa340192384bb26a66a7c
-  data.tar.gz: 9acea8151aa28cb1a6d89d21a45553cba06b86b093ff20aa87f6632a95d9250b09b698bf6c160cfa3f14f5c0905f5472e259e9a2aab7d23b6a9e2d8d4aff176a
+  metadata.gz: 7b8fea60fa67ca77c4b4655e928429483b0a77779843c64863fce8e8f49dfaba102896e54c1b36151a19ad107bf5540fab6b5663727d791e71db27081acefedd
+  data.tar.gz: fcbfa4cf654c14cb2eb023c3905399479bf784c1dd349f99ff2357e3d7687f342a230b61eceb5b37c8f8ecf444b8b460608be5af07affeede0186c6707e3a95b

data/README.md

@@ -20,8 +20,8 @@ HotDocs is a set of optimized Rails components & tools for writing docs:
 | Embed docs in an existing Rails app                       | ✅      | ❌     | ❌         |
 | Standalone docs                                           | ✅      | ✅     | ✅         |
 | Styled components you can customize                       | ✅      | ✅     | ✅         |
-| Markdown (with syntax highlight & themes)                 | 🚀      | 👍     | 🚀         |
-| Static export                                             | 🔜 🚀   | 👍     | 🚀         |
+| Markdown (with syntax highlight & themes)                 | ✅      | ✅     | ✅         |
+| Static export                                             | ✅      | ✅     | ✅         |
 | Search                                                    |  ✅     | 🔌     | 🔌         |
 | Light / Dark                                              | 🔜 ✅   | 🔌     | ✅         |
 | Open source                                               | ✅      | ✅     | ✅         |

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

@@ -0,0 +1,29 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static values = {
+    host: String,
+    path: String,
+    fallback: String,
+  };
+
+  connect() {
+    if (!this.element.id) {
+      throw new Error("Element must have an id.");
+    }
+    this.element.innerHTML = this.fallbackValue || "Loading...";
+    this.element.style.visibility = "";
+    this.fetchElement();
+  }
+
+  fetchElement() {
+    fetch(`${this.hostValue}${this.pathValue}`)
+      .then((response) => response.text())
+      .then((text) => {
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(text, "text/html");
+        const fetchedElement = doc.querySelector(`#${this.element.id}`);
+        this.element.innerHTML = fetchedElement.innerHTML;
+      });
+  }
+}

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

@@ -10,7 +10,7 @@ export default class extends Controller {
 
   disconnect() {
     document.removeEventListener("keydown", this.keydownOpen);
-    document.removeEventListener("click", this.clickClose, { once: true });
+    document.removeEventListener("click", this._clickClose);
   }
 
   open() {
@@ -20,6 +20,11 @@ export default class extends Controller {
     this.searchTarget.showModal();
   }
 
+  close() {
+    this.searchTarget.close();
+    document.removeEventListener("click", this._clickClose);
+  }
+
   search = debounce(this._search, 200);
 
   _allowOpening() {
@@ -32,13 +37,15 @@ export default class extends Controller {
     document.addEventListener("keydown", this.keydownOpen);
   }
 
-  _allowClosing() {
-    this.clickClose = (event) => {
-      if (this.dialogTarget.contains(event.target)) return;
-      this.searchTarget.close();
-    };
+  _clickClose = (event) => {
+    if (!this.searchTarget.open) return;
+    if (this.dialogTarget.contains(event.target)) return;
+    this.close();
+  };
 
-    document.addEventListener("click", this.clickClose, { once: true });
+  _allowClosing() {
+    document.removeEventListener("click", this._clickClose);
+    document.addEventListener("click", this._clickClose);
   }
 
   _initSearch() {

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

@@ -73,7 +73,7 @@ body {
   --nav-background-color: white;
   --nav-link-active-color: var(--link-active-color);
   --nav-link-color: var(--link-color);
-  --nav-padding-horizontal: 1rem;
+  --nav-padding-horizontal: 1.5rem;
   --nav-padding-vertical: 0.5rem;
   --nav-shadow: 0 1px 2px 0 #0000001a;
   --nav-title-color: #1c1e21;
@@ -304,14 +304,21 @@ body:has(.search:open), body:has(.search[open]) {
   bottom: 0;
   color: var(--search-text-color);
   height: 100vh;
+  height: 100dvh;
   left: 0;
   max-height: 100vh;
+  height: 100dvh;
   max-width: 100vw;
-  padding-inline: 1rem;
+  max-width: 100dvw;
   position: fixed;
   right: 0;
   top: 0;
   width: 100vw;
+  width: 100dvw;
+
+  @media (min-width: 64rem) {
+    padding-inline: 1rem;
+  }
 }
 
 ::backdrop {
@@ -319,28 +326,57 @@ body:has(.search:open), body:has(.search[open]) {
 }
 
 .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;
+  height: 100vh;
+  height: 100dvh;
+  max-height: 100vh;
+  max-height: 100dvh;
+  max-width: 100vw;
+  max-width: 100dvw;
+  overflow: auto;
   padding: 1rem;
-  width: auto;
+  width: 100vw;
+  width: 100dvw;
+
+  @media (min-width: 64rem) {
+    border-radius: 0.375rem;
+    height: auto;
+    margin: 60px auto auto;
+    max-height: calc(100vh - 120px);
+    max-height: calc(100dvh - 120px);
+    max-width: 800px;
+    width: auto;
+  }
+}
+
+.search__header {
+  align-items: center;
+  display: flex;
+  gap: 1rem;
 }
 
 .search__input {
   background-color: var(--search-excerpt-background-color);
   border: 1px solid #808080;
   border-radius: 0.2rem;
+  flex: 1 0 auto;
   padding: 0.3rem 0.5rem;
-  width: 100%;
 
   &:focus-visible {
     outline: solid 2px #0077ff;
   }
 }
 
+.search__dismiss {
+  color: var(--search-text-color);
+  height: 1rem;
+  width: 1rem;
+
+  @media (min-width: 64rem) {
+    display: none;
+  }
+}
+
 .search__result {
   margin-top: 1.5rem;
 
@@ -688,7 +724,7 @@ body:has(.search:open), body:has(.search[open]) {
 .footer {
   background-color: var(--footer-background-color);
   flex: 0 0 auto;
-  padding: 4rem 1rem;
+  padding: 4rem var(--nav-padding-horizontal);
 }
 
 .footer__sections {
@@ -726,6 +762,7 @@ body:has(.search:open), body:has(.search[open]) {
 }
 
 .credits {
+  padding-block: 1rem;
   text-align: center;
 }
 
@@ -767,9 +804,9 @@ body:has(.search:open), body:has(.search[open]) {
   width: 1rem;
 }
 
-/* CSS: ADMONITIONS */
+/* CSS: ALERTS */
 
-.admonition {
+.alert {
   border: 1px solid;
   border-left: 0.5rem solid;
   border-radius: 0.375rem;
@@ -777,44 +814,44 @@ body:has(.search:open), body:has(.search[open]) {
   padding: 1rem;
 }
 
-.admonition--tip {
+.alert--tip {
   background: #00940011;
   border-color: #009400;
 }
 
-.admonition--info {
+.alert--info {
   background: #87cef911;
   border-color: #87cef9;
 }
 
-.admonition--warning {
+.alert--warning {
   background: #fea50011;
   border-color: #fea500;
 }
 
-.admonition--danger {
+.alert--danger {
   background: #db153b11;
   border-color: #db153b;
 }
 
-.admonition__header {
+.alert__header {
   align-items: center;
   display: flex;
   gap: 0.5ch;
   margin-bottom: 1rem;
 }
 
-.admonition__icon {
+.alert__icon {
   height: 1rem;
   width: 1rem;
 }
 
-.admonition__label {
+.alert__label {
   font-weight: bold;
   margin: 0;
   text-transform: uppercase;
 }
 
-.admonition__content > :last-of-type {
+.alert__content > :last-of-type {
   margin-bottom: 0;
 }

data/app/helpers/hotdocs/application_helper.rb

@@ -24,10 +24,11 @@ module Hotdocs
         [ *Array(old), *Array(new) ].join(" ")
       end
 
+      # Needs to be on one line otherwise kramdown chokes
       link_to(options, html_options) do
         concat(content_tag(:span, name))
 
-        concat(<<~SVG.html_safe)
+        concat(<<~SVG.gsub(/\n/, "").html_safe)
           <svg aria-hidden="true" viewBox="0 0 24 24" class="external-link__icon">
             <path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path>
           </svg>
@@ -70,6 +71,16 @@ module Hotdocs
       end
     end
 
+    def fetcher(id:, path:, fallback: nil, &)
+      data = {
+        controller: "fetcher",
+        "fetcher-host-value": fetcher_host,
+        "fetcher-path-value": path,
+        "fetcher-fallback-value": fallback
+      }
+      content_tag(:div, id: id, data: data, style: "visibility: hidden;", &)
+    end
+
     private
 
     def active_link?(url)

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

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html data-theme="light">
+<html data-theme="light" lang="<%= I18n.locale %>">
   <head>
     <title><%= content_for(:title) %></title>
 
@@ -12,7 +12,16 @@
   <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>
+        <div class="search__header">
+          <input autofocus data-action="input->search#search" type="text" class="search__input"></input>
+          <button aria-label="Close search dialog" type="button" class="search__dismiss" data-action="click->search#close">
+            <svg viewBox="0 0 15 15">
+              <g stroke="currentColor" stroke-width="1.2">
+                <path d="M.75.75l13.5 13.5M14.25.75L.75 14.25"></path>
+              </g>
+            </svg>
+          </button>
+        </div>
 
         <template data-search-target="resultTemplate">
           <li class="search__result">
@@ -33,88 +42,97 @@
       </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">
-          <svg viewBox="0 0 30 30" aria-hidden="true">
-            <path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path>
-          </svg>
-        </button>
-
-        <%= link_to root_path, class: "nav__brand" do %>
-          <div class="nav__logo-wrapper">
-            <img class="nav__logo" src="<%= logo.src %>" alt="<%= logo.alt %>" height="32" width="32" />
-          </div>
+    <% if content_for?(:hotdocs_nav) %>
+      <%= content_for(:hotdocs_nav) %>
 
-          <span class="nav__title">HotDocs</span>
-        <% end %>
+    <% else %>
+      <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">
+            <svg viewBox="0 0 30 30" aria-hidden="true">
+              <path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path>
+            </svg>
+          </button>
 
-        <div class="nav__links">
-          <% nav_left_items("nav__link").each do |item| %>
-            <%= item %>
-          <% end %>
-        </div>
-      </div>
+          <%= link_to root_path, class: "nav__brand" do %>
+            <% unless logo.nil? %>
+              <div class="nav__logo-wrapper">
+                <img class="nav__logo" src="<%= logo.src %>" alt="<%= logo.alt %>" height="32" width="32" />
+              </div>
+            <% end %>
 
-      <div class="nav__section">
-        <div class="nav__links">
-          <% nav_right_items("nav__link").each do |item| %>
-            <%= item %>
+            <span class="nav__title"><%= title %></span>
           <% 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>
-      <div class="sidenav">
-        <div class="sidenav__header">
-          <%= link_to root_path, class: "nav__brand" do %>
-            <div class="nav__logo-wrapper">
-              <img class="nav__logo" src="<%= logo.src %>" alt="<%= logo.alt %>" height="32" width="32" />
-            </div>
+          <div class="nav__links">
+            <% nav_left_items("nav__link").each do |item| %>
+              <%= item %>
+            <% end %>
+          </div>
+        </div>
 
-            <span class="nav__title">HotDocs</span>
-          <% end %>
+        <div class="nav__section">
+          <div class="nav__links">
+            <% nav_right_items("nav__link").each do |item| %>
+              <%= item %>
+            <% end %>
+          </div>
 
-          <button aria-label="Close navigation" class="sidenav__toggle" type="button" data-action="click->sidenav#close">
-            <svg viewBox="0 0 15 15">
-              <g stroke="currentColor" stroke-width="1.2">
-                <path d="M.75.75l13.5 13.5M14.25.75L.75 14.25"></path>
-              </g>
+          <button type="button" data-action="click->search#open:stop" class="search-button" aria-label="Open search dialog">
+            <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__sections" data-sidenav-target="sections">
-          <div class="sidenav__section">
-            <ul class="menu__section">
-              <% (nav_left_items("menu__link") + nav_right_items("menu__link")).each do |item| %>
-                <li>
-                  <div class="menu__row">
-                    <%= item %>
-                  </div>
-                </li>
+        <div class="sidenav-backdrop"></div>
+        <div class="sidenav">
+          <div class="sidenav__header">
+            <%= link_to root_path, class: "nav__brand" do %>
+              <% unless logo.nil? %>
+                <div class="nav__logo-wrapper">
+                  <img class="nav__logo" src="<%= logo.src %>" alt="<%= logo.alt %>" height="32" width="32" />
+                </div>
               <% end %>
-            </ul>
+
+              <span class="nav__title"><%= title %></span>
+            <% end %>
+
+            <button aria-label="Close navigation" class="sidenav__toggle" type="button" data-action="click->sidenav#close">
+              <svg viewBox="0 0 15 15">
+                <g stroke="currentColor" stroke-width="1.2">
+                  <path d="M.75.75l13.5 13.5M14.25.75L.75 14.25"></path>
+                </g>
+              </svg>
+            </button>
           </div>
 
-          <div class="sidenav__section">
-            <div class="menu__section">
-              <button type="button" class="sidenav__back-button" data-action="click->sidenav#back">← Back to main menu</button>
+          <div class="sidenav__sections" data-sidenav-target="sections">
+            <div class="sidenav__section">
+              <ul class="menu__section">
+                <% (nav_left_items("menu__link") + nav_right_items("menu__link")).each do |item| %>
+                  <li>
+                    <div class="menu__row">
+                      <%= item %>
+                    </div>
+                  </li>
+                <% end %>
+              </ul>
             </div>
 
-            <%= menu %>
+            <div class="sidenav__section">
+              <div class="menu__section">
+                <button type="button" class="sidenav__back-button" data-action="click->sidenav#back">← Back to main menu</button>
+              </div>
+
+              <%= menu %>
+            </div>
           </div>
         </div>
-      </div>
-    </nav>
+      </nav>
+    <% end %>
 
     <div class="content">
       <aside class="menu">
@@ -152,24 +170,31 @@
       </main>
     </div>
 
-    <footer class="footer">
-      <div class="footer__sections">
-        <% footer_items.each do |footer_item| %>
-          <div class="footer__section">
-            <p class="footer__heading"><%= footer_item.fetch(:heading) %></p>
+    <% if content_for?(:hotdocs_footer) %>
+      <%= content_for(:hotdocs_footer) %>
+
+    <% else %>
+      <footer class="footer">
+        <div class="footer__sections">
+          <% footer_items.each do |footer_item| %>
+            <div class="footer__section">
+              <p class="footer__heading"><%= footer_item.fetch(:heading) %></p>
+
+              <ul>
+                <% footer_item.fetch(:items).each do |item| %>
+                  <li><%= item %></li>
+                <% end %>
+              </ul>
+            </div>
+          <% end %>
+        </div>
 
-            <ul>
-              <% footer_item.fetch(:items).each do |item| %>
-                <li><%= item %></li>
-              <% end %>
-            </ul>
-          </div>
+        <% unless logo.nil? %>
+          <img class="footer__logo" src="<%= logo.src %>" alt="<%= logo.alt %>" height="150" width="150" />
         <% end %>
-      </div>
-
-      <img class="footer__logo" src="<%= logo.src %>" alt="<%= logo.alt %>" height="150" width="150" />
+      </footer>
+    <% end %>
 
-      <p class="credits">Built with Rails &amp; <a class="credits__link" href="https://hotdocsrails.com">HotDocs<img class="credits__logo" src="<%= asset_path "hotdocs/icon.svg" %>" alt="A humanized and happy hot dog" height="32" width="32" /></a></p>
-    </footer>
+    <p class="credits">Built with Rails &amp; <a class="credits__link" href="https://hotdocsrails.com">HotDocs<img class="credits__logo" src="<%= asset_path "hotdocs/icon.svg" %>" alt="A humanized and happy hot dog" height="32" width="32" /></a></p>
   </body>
 </html>

data/config/importmap.rb

@@ -1,3 +1,3 @@
 # Pin npm packages by running ./bin/importmap
 
-pin_all_from Hotdocs::Engine.root.join("app/assets/javascript/controllers"), under: "controllers"
+pin_all_from Hotdocs::Engine.root.join("app/assets/javascript/controllers"), to: "controllers", under: "hotdocs/controllers", preload: "hotdocs"

data/lib/hotdocs/engine.rb

@@ -13,8 +13,7 @@ module Hotdocs
     end
 
     config.before_initialize do
-      MarkdownHandler.prepare(self)
-      ActionView::Template.register_template_handler :mderb, MarkdownHandler.new(self)
+      ActionView::Template.register_template_handler :mderb, MarkdownHandler.new
     end
   end
 end

data/lib/hotdocs/kramdown_alerts.rb

@@ -0,0 +1,92 @@
+module Kramdown
+  class Element
+    def to_h
+      {
+        children: children.map(&:to_h),
+        type:,
+        value:
+      }
+    end
+  end
+end
+
+module Alert
+  PATHS_BY_ALERT_TYPE = {
+    "danger" => [
+      "M15.362 5.214A8.252 8.252 0 0 1 12 21 8.25 8.25 0 0 1 6.038 7.047 8.287 8.287 0 0 0 9 9.601a8.983 8.983 0 0 1 3.361-6.867 8.21 8.21 0 0 0 3 2.48Z",
+      "M12 18a3.75 3.75 0 0 0 .495-7.468 5.99 5.99 0 0 0-1.925 3.547 5.975 5.975 0 0 1-2.133-1.001A3.75 3.75 0 0 0 12 18Z"
+    ],
+    "warning" => [
+      "M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126ZM12 15.75h.007v.008H12v-.008Z"
+    ],
+    "tip" => [
+      "M12 18v-5.25m0 0a6.01 6.01 0 0 0 1.5-.189m-1.5.189a6.01 6.01 0 0 1-1.5-.189m3.75 7.478a12.06 12.06 0 0 1-4.5 0m3.75 2.383a14.406 14.406 0 0 1-3 0M14.25 18v-.192c0-.983.658-1.823 1.508-2.316a7.5 7.5 0 1 0-7.517 0c.85.493 1.509 1.333 1.509 2.316V18"
+    ],
+    "info" => [
+      "m11.25 11.25.041-.02a.75.75 0 0 1 1.063.852l-.708 2.836a.75.75 0 0 0 1.063.853l.041-.021M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Zm-9-3.75h.008v.008H12V8.25Z"
+    ]
+  }
+
+  def convert_blockquote(el, indent)
+    child = el.children[0]
+
+    case child.to_h
+    in {
+      type: :p,
+      children: [
+        { type: :text, value: /\A\[!(INFO|TIP|WARNING|DANGER)\]\z/ },
+        { type: :br },
+        *
+      ]
+    }
+      alert_type = $+.downcase
+      child.children.slice!(0, 2) # remove :text & :br
+
+      svg = Kramdown::Element.new(
+        :html_element,
+        :svg,
+        {
+          class: "alert__icon",
+          xmlns: "http://www.w3.org/2000/svg",
+          fill: "none",
+          viewBox: "0 0 24 24",
+          "stroke-width": "1.5",
+          stroke: "currentColor"
+        }
+      )
+
+      PATHS_BY_ALERT_TYPE[alert_type].each do |path|
+        svg.children << Kramdown::Element.new(:html_element, :path, {
+          "stroke-linecap": "round",
+          "stroke-linejoin": "round",
+          d: path
+        })
+      end
+
+      label = Kramdown::Element.new(:html_element, :span, { class: "alert__label" })
+      label.children << Kramdown::Element.new(:text, alert_type.upcase)
+
+      header = Kramdown::Element.new(:html_element, :div, { class: "alert__header" })
+      header.children << svg
+      header.children << label
+
+      content = Kramdown::Element.new(:html_element, :div, { class: "alert__content" })
+      content.children.push(*el.children)
+
+      alert = Kramdown::Element.new(:html_element, :div, {})
+      alert.children << header
+      alert.children << content
+
+      format_as_block_html(
+        "div",
+        { class: "alert alert--#{alert_type}" },
+        format_as_indented_block_html("div", {}, inner(alert, indent), indent),
+        indent
+      )
+    else
+      super
+    end
+  end
+end
+
+Kramdown::Converter::Html.prepend(Alert)