hotdocs 0.1.0

data/lib/hotdocs/markdown.mjs

@@ -0,0 +1,177 @@
+// Example usage:
+// echo "# title" || deno --allow-read --allow-env --node-modules-dir=auto config/initializers/markdown.mjs
+
+import remarkParse from "npm:remark-parse";
+import remarkPrism from "npm:remark-prism";
+import remarkRehype from "npm:remark-rehype";
+import rehypeStringify from "npm:rehype-stringify";
+import { unified } from "npm:unified";
+
+process.stdin.on("data", async (data) => {
+  try {
+    const file = await unified()
+      .use(remarkParse)
+      .use(remarkDirective)
+      .use(remarkAdmonitions)
+      .use(remarkPrism)
+      // `allowDangerousHtml` to avoid sanitizing the raw Html from `data`
+      .use(remarkRehype, { allowDangerousHtml: true })
+      .use(rehypeStringify, { allowDangerousHtml: true })
+      .process(data);
+    process.stdout.write(String(file));
+  } catch (error) {
+    console.error(`Error: ${error.message}\nStack trace:\n${error.stack}`);
+    process.stdout.write(
+      `Error: ${error.message}<br />Stack trace:\n${error.stack}`
+    );
+  }
+});
+
+const ADMONITIONS = {
+  tip: {
+    svg: {
+      xmlns: "http://www.w3.org/2000/svg",
+      fill: "none",
+      viewBox: "0 0 24 24",
+      strokeWidth: "1.5",
+      stroke: "currentColor",
+    },
+    paths: [
+      {
+        strokeLinecap: "round",
+        strokeLinejoin: "round",
+        d: "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: {
+    svg: {
+      xmlns: "http://www.w3.org/2000/svg",
+      fill: "none",
+      viewBox: "0 0 24 24",
+      strokeWidth: "1.5",
+      stroke: "currentColor",
+    },
+    paths: [
+      {
+        strokeLinecap: "round",
+        strokeLinejoin: "round",
+        d: "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",
+      },
+    ],
+  },
+  warning: {
+    svg: {
+      xmlns: "http://www.w3.org/2000/svg",
+      fill: "none",
+      viewBox: "0 0 24 24",
+      strokeWidth: "1.5",
+      stroke: "currentColor",
+    },
+    paths: [
+      {
+        strokeLinecap: "round",
+        strokeLinejoin: "round",
+        d: "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",
+      },
+    ],
+  },
+  danger: {
+    svg: {
+      xmlns: "http://www.w3.org/2000/svg",
+      fill: "none",
+      viewBox: "0 0 24 24",
+      strokeWidth: "1.5",
+      stroke: "currentColor",
+    },
+    paths: [
+      {
+        strokeLinecap: "round",
+        strokeLinejoin: "round",
+        d: "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",
+      },
+      {
+        strokeLinecap: "round",
+        strokeLinejoin: "round",
+        d: "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",
+      },
+    ],
+  },
+};
+
+import { directiveFromMarkdown } from "npm:mdast-util-directive";
+import { directive } from "npm:micromark-extension-directive";
+
+// https://github.com/remarkjs/remark-directive/blob/23b8f416da165b6ddaa4c5e7e82addaf6dcb96a9/lib/index.js
+function remarkDirective() {
+  const self = this;
+  const data = self.data();
+
+  const micromarkExtensions =
+    data.micromarkExtensions || (data.micromarkExtensions = []);
+  const fromMarkdownExtensions =
+    data.fromMarkdownExtensions || (data.fromMarkdownExtensions = []);
+
+  const directiveContainer = directive();
+  // From:
+  // {
+  //   text: {[codes.colon]: directiveText},
+  //   flow: {[codes.colon]: [directiveContainer, directiveLeaf]}
+  // }
+  // To:
+  // {
+  //   text: {},
+  //   flow: {[codes.colon]: [directiveContainer]}
+  // }
+  directiveContainer.text = {};
+  directiveContainer.flow[Object.keys(directiveContainer.flow)[0]].pop();
+
+  micromarkExtensions.push(directiveContainer);
+  fromMarkdownExtensions.push(directiveFromMarkdown());
+}
+
+import { h, s } from "npm:hastscript";
+import { visit } from "npm:unist-util-visit";
+
+function remarkAdmonitions() {
+  return (tree) => {
+    visit(tree, (node) => {
+      if (node.type === "containerDirective") {
+        const level = node.name;
+        const admonition = ADMONITIONS[level];
+        if (!admonition) return;
+
+        const svg = s(
+          "svg.admonition__icon",
+          admonition.svg,
+          admonition.paths.map((path) => s("path", path))
+        );
+
+        const label = h("span.admonition__label", level.toLocaleUpperCase());
+        const header = h("div", { class: "admonition__header" }, [svg, label]);
+        const content = h("div", { class: "admonition__content" }, [
+          ...node.children,
+        ]);
+
+        node.tagName = "div";
+        node.properties = h("div", {
+          class: `admonition admonition--${level}`,
+        }).properties;
+        node.children = [header, content];
+
+        const decorateHast = (node) => {
+          Object.assign(node.data ?? (node.data = {}), {
+            hName: node.tagName,
+            hProperties: node.properties,
+          });
+
+          if (node.children && Array.isArray(node.children)) {
+            node.children.forEach(decorateHast);
+          }
+        };
+
+        decorateHast(node);
+      }
+    });
+  };
+}

data/lib/hotdocs/markdown.rb

@@ -0,0 +1,42 @@
+require "open3"
+
+class MarkdownHandler
+  def self.prepare(engine)
+    # Install npm packages
+    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)
+    @engine = engine
+  end
+
+  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
+    end
+
+    content_fors = ActionView::Template::Handlers::ERB
+      .new
+      .call(template, source)
+      .split(";")
+      .grep(/content_for.*\(.*:/)
+
+    <<~STRING
+      #{content_fors.join(";")}
+      @output_buffer.safe_append='#{out}'.freeze;
+      @output_buffer
+    STRING
+  end
+end

data/lib/hotdocs/version.rb

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

data/lib/hotdocs.rb

@@ -0,0 +1,5 @@
+require "hotdocs/version"
+require "hotdocs/engine"
+
+module Hotdocs
+end

data/lib/install/install.rb

@@ -0,0 +1,287 @@
+def source_paths # used by copy() & template()
+  [ File.expand_path("../..", __dir__) ]
+end
+
+def gem?(name)
+  gemfile_path = Pathname(destination_root).join("Gemfile")
+
+  regex = /gem ["']#{name}["']/
+  if File.readlines(gemfile_path).grep(regex).any?
+    say "#{name} already installed"
+    false
+  else
+    run("bundle add #{name}") || abort("Failed to add #{name} to the bundle")
+    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
+
+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
+
+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"
+
+LINES
+
+create_file(Pathname(destination_root).join("app/views/layouts/hotdocs.html.erb"), <<~LAYOUT)
+  <% 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 %>
+  <% end %>
+
+  <%= render template: "layouts/hotdocs/application" %>
+LAYOUT
+
+create_file(Pathname(destination_root).join("app/views/hotdocs/index.html.mderb"), <<~VIEW)
+  <%= content_for(:title, "Welcome") %>
+
+  # Welcome to HotDocs
+
+  Find this markdown in `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
+
+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)
+  module HotdocsHelper
+    def logo
+      Struct.new(:src, :alt).new(asset_path("hotdocs.svg"), "A humanized and happy hot dog")
+    end
+
+    def nav_left_items(classes)
+      [
+        active_link_to("Docs", root_path, class: Array(classes))
+      ]
+    end
+
+    def nav_right_items(classes)
+      [
+        external_link_to("GitHub", "https://github.com/3v0k4/hotdocs", class: Array(classes))
+      ]
+    end
+
+    # { label: "", url: *_path, children: [], expanded: false/true }
+    def menu_items
+      [
+        { label: "Welcome", url: root_path },
+      ]
+    end
+
+    def repository_base_url
+      "https://github.com/3v0k4/hotdocs/blob/main"
+    end
+
+    def footer_items
+      [
+        {
+          heading: "Contribute",
+          items: [
+            external_link_to("Source Code", "https://github.com/3v0k4/hotdocs", class: "footer__link")
+          ]
+        },
+        {
+          heading: "Community",
+          items: [
+            external_link_to("GitHub Discussions", "https://github.com/3v0k4/hotdocs/discussions", class: "footer__link")
+          ]
+        },
+        {
+          heading: "(il)Legal",
+          items: [
+            "Nothing to see here."
+          ]
+        },
+        {
+          heading: "HotDocs",
+          items: [
+            "Write your docs with Ruby on Rails."
+          ]
+        }
+      ]
+    end
+  end
+HELPER
+
+create_file(Pathname(destination_root).join("app/assets/stylesheets/prism.css"), <<~CSS)
+  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;
+  }
+
+  .token.deleted {
+    background: #484a4a;
+  }
+
+  code.language-css .token.property,
+  code.language-css .token.property + .token.punctuation {
+    color: #a9b7c6;
+  }
+
+  code.language-css .token.id {
+    color: #ffc66d;
+  }
+
+  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;
+  }
+CSS
+
+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'"
+end

data/lib/tasks/hotdocs_tasks.rake

@@ -0,0 +1,9 @@
+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
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: hotdocs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- 3v0k4
+bindir: bin
+cert_chain: []
+date: 2025-03-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+description: HotDocs is a set of optimized Rails components & tools for writing docs.
+email:
+- riccardo.odone@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- LICENSE-LGPL
+- README.md
+- Rakefile
+- app/assets/images/hotdocs/icon.svg
+- app/assets/javascript/controllers/accordion_controller.js
+- app/assets/javascript/controllers/sidenav_controller.js
+- app/assets/javascript/controllers/toc_controller.js
+- app/assets/stylesheets/hotdocs/application.css
+- app/assets/stylesheets/hotdocs/reset.css
+- app/helpers/hotdocs/application_helper.rb
+- app/views/hotdocs/_menu_row.html.erb
+- app/views/layouts/hotdocs/application.html.erb
+- config/importmap.rb
+- lib/hotdocs.rb
+- lib/hotdocs/engine.rb
+- lib/hotdocs/markdown.mjs
+- lib/hotdocs/markdown.rb
+- lib/hotdocs/version.rb
+- lib/install/install.rb
+- lib/tasks/hotdocs_tasks.rake
+homepage: https://hotdocsrails.com/
+licenses:
+- LGPL-3.0
+- Commercial
+metadata:
+  homepage_uri: https://hotdocsrails.com/
+  source_code_uri: https://github.com/3v0k4/hotdocs
+  changelog_uri: https://github.com/3v0k4/hotdocs/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Write your docs with Ruby on Rails
+test_files: []