infodocs 0.3.0

data/lib/infodocs/tree_editor.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+
+module Infodocs
+  # Moves a page or folder to another folder / position by renaming files and
+  # rewriting the `order` lists of the affected `_tree.yml` manifests.
+  class TreeEditor
+    class Invalid < Error; end
+
+    def initialize(tree)
+      @tree = tree
+    end
+
+    # slug:   node to move; parent: slug of the destination folder ("" = top);
+    # before: slug of the sibling it goes in front of (nil = last).
+    def move(slug:, parent:, before: nil)
+      node = @tree.node(slug)
+      raise Invalid, "unknown node #{slug.inspect}" if node.nil? || node.path.nil?
+
+      target = @tree.node(parent)
+      raise Invalid, "unknown destination #{parent.inspect}" if target.nil? || !target.folder?
+      raise Invalid, "cannot place items next to multiple source roots" if target.path.nil?
+      raise Invalid, "source folders cannot be moved" if @tree.root.children.include?(node) && @tree.multiple_roots?
+      raise Invalid, "cannot move a folder into itself" if node.folder? && (target.slug == node.slug || target.slug.start_with?("#{node.slug}/"))
+
+      source_dir = node.path.parent
+      name = node.name
+      destination = target.path.join(node.folder? ? name : "#{name}.md")
+
+      if source_dir != target.path
+        raise Invalid, "#{destination.basename} already exists in the destination" if destination.exist?
+
+        carried = node.leaf? ? (@tree.node(node.slug)&.page&.manifest_tags || []) : []
+        moved_pages = pages_under(node)
+        rename(node.path, destination)
+        leave_redirects(moved_pages, node, destination, target)
+        update_manifest(source_dir) { |manifest| remove_name(manifest, name) }
+        update_manifest(target.path) { |manifest| set_tags(manifest, name, carried) }
+      end
+
+      order = ordered_names(target, exclude: name)
+      sibling = before && @tree.node(before)&.name
+      index = sibling && order.index(sibling) || order.size
+      order.insert(index, name)
+      update_manifest(target.path) { |manifest| manifest["order"] = order }
+    end
+
+    # Saves the tags of a page in its folder's `_tree.yml` (`tags: { name: [..] }`).
+    # Tags that come from the page's own frontmatter are left alone.
+    def tag(slug:, tags:)
+      node = @tree.node(slug)
+      raise Invalid, "unknown page #{slug.inspect}" if node.nil? || node.path.nil? || !node.leaf?
+
+      list = Page.normalize_tags(tags) - Page.normalize_tags(node.page.frontmatter["tags"])
+      update_manifest(node.path.parent) { |manifest| set_tags(manifest, node.name, list) }
+      list
+    end
+
+    # Creates a page (`name.md`) or an (empty) folder with a `_tree.yml` titled
+    # after it, at the end of `parent`. Returns the slug of the new node.
+    def create(parent:, title:, kind: :page)
+      title = title.to_s.strip
+      raise Invalid, "title can't be blank" if title.empty?
+
+      target = @tree.node(parent)
+      raise Invalid, "unknown destination #{parent.inspect}" if target.nil? || !target.folder? || target.path.nil?
+
+      name = unique_name(target, title.parameterize.presence || "untitled")
+      if kind.to_s == "folder"
+        dir = target.path.join(name)
+        FileUtils.mkdir_p(dir)
+        dir.join(Tree::MANIFEST).write({ "title" => title }.to_yaml.sub(/\A---\s*\n/, ""))
+      else
+        target.path.join("#{name}.md").write("# #{title}\n\n")
+      end
+
+      order = ordered_names(target, exclude: name) << name
+      update_manifest(target.path) { |manifest| manifest["order"] = order }
+      [target.slug, name].reject(&:empty?).join("/")
+    end
+
+    # Deletes a page or a whole folder (with everything inside). Returns the
+    # slug of the folder that contained it. Tracked files go through `git rm`.
+    def delete(slug:)
+      node = @tree.node(slug)
+      raise Invalid, "unknown node #{slug.inspect}" if node.nil? || node.path.nil? || node.slug.empty?
+      raise Invalid, "source folders cannot be deleted" if @tree.root.children.include?(node) && @tree.multiple_roots?
+      raise Invalid, "path is outside the docs sources" unless inside_source?(node.path)
+
+      parent_dir = node.path.parent
+      remove(node.path)
+      update_manifest(parent_dir) { |manifest| remove_name(manifest, node.name) }
+      File.dirname(node.slug).sub(/\A\.\z/, "")
+    end
+
+    private
+
+    def inside_source?(path)
+      real = path.realpath
+      @tree.sources.any? { |source| real.to_s.start_with?("#{source.path.realpath}/") }
+    rescue Errno::ENOENT
+      false
+    end
+
+    def remove(path)
+      _out, _err, status = Open3.capture3("git", "rm", "-rq", "--", path.to_s, chdir: path.parent.to_s)
+      FileUtils.rm_rf(path) unless status.success?
+    end
+
+    def unique_name(folder, base)
+      taken = folder.children.map(&:name) + folder.path.children.map { |child| child.basename(".md").to_s }
+      name = base
+      counter = 1
+      name = "#{base}-#{counter += 1}" while taken.include?(name) || name.start_with?("_")
+      name
+    end
+
+    # Current display order of the folder's children (all, hidden included).
+    def ordered_names(folder, exclude:)
+      folder.children.map(&:name) - [exclude]
+    end
+
+    # [page, path relative to the moved node] for the page, or every page in the folder.
+    def pages_under(node)
+      return [[node.page, nil]] if node.leaf?
+
+      @tree.all_pages.select { |page| page.slug == node.slug || page.slug.start_with?("#{node.slug}/") }
+           .map { |page| [page, page.file.relative_path_from(node.path)] }
+    end
+
+    # Old URLs keep working: each moved page lists its previous slug in `redirect_from`.
+    def leave_redirects(moved_pages, node, destination, target)
+      new_prefix = [target.slug, node.name].reject(&:empty?).join("/")
+      moved_pages.each do |page, relative|
+        file = relative ? destination.join(relative) : destination
+        next unless file.file?
+
+        old_slug = page.slug
+        new_slug = node.leaf? ? new_prefix : old_slug.sub(/\A#{Regexp.escape(node.slug)}/, new_prefix)
+        moved = Page.new(file: file, slug: new_slug, root: target.path)
+        moved.add_redirect_from(old_slug)
+      end
+    end
+
+    def set_tags(manifest, name, tags)
+      map = manifest["tags"].is_a?(Hash) ? manifest["tags"].transform_keys(&:to_s) : {}
+      tags.empty? ? map.delete(name) : map[name] = tags
+      map.empty? ? manifest.delete("tags") : manifest["tags"] = map
+    end
+
+    def remove_name(manifest, name)
+      set_tags(manifest, name, []) if manifest["tags"].is_a?(Hash)
+      manifest["order"] = Array(manifest["order"]).map(&:to_s) - [name] if manifest.key?("order")
+      manifest["hidden"] = Array(manifest["hidden"]).map(&:to_s) - [name] if manifest.key?("hidden")
+    end
+
+    def update_manifest(dir)
+      file = dir.join(Tree::MANIFEST)
+      manifest = file.file? ? (YAML.safe_load(file.read) || {}) : {}
+      yield manifest
+      manifest.delete("order") if manifest["order"] == []
+      manifest.delete("hidden") if manifest["hidden"] == []
+      if manifest.empty?
+        file.delete if file.exist?
+      else
+        file.write(manifest.to_yaml.sub(/\A---\s*\n/, ""))
+      end
+    end
+
+    # `git mv` keeps history readable when the file is tracked; plain rename otherwise.
+    def rename(from, to)
+      Open3.capture3("git", "mv", from.to_s, to.to_s, chdir: from.parent.to_s).then do |_out, _err, status|
+        FileUtils.mv(from, to) unless status.success?
+      end
+    end
+  end
+end

data/lib/infodocs/url_helper.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Infodocs
+  # Link to the docs from the host app: `link_to "Setup", infodocs_page_path("guides/setup")`.
+  # Included into the host's views and controllers by the engine.
+  module UrlHelper
+    def infodocs_page_path(slug = nil, **options)
+      slug = clean_infodocs_slug(slug)
+      slug.empty? ? infodocs.root_path(**options) : infodocs.page_path(slug, **options)
+    end
+
+    def infodocs_page_url(slug = nil, **options)
+      slug = clean_infodocs_slug(slug)
+      slug.empty? ? infodocs.root_url(**options) : infodocs.page_url(slug, **options)
+    end
+
+    private
+
+    def clean_infodocs_slug(slug)
+      slug.to_s.delete_prefix("/").delete_suffix("/").delete_suffix(".md")
+    end
+  end
+end

data/lib/infodocs/version.rb

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

data/lib/infodocs.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "infodocs/version"
+
+module Infodocs
+  class Error < StandardError; end
+end
+
+require_relative "infodocs/source"
+require_relative "infodocs/code_theme"
+require_relative "infodocs/configuration"
+require_relative "infodocs/page"
+require_relative "infodocs/tree"
+require_relative "infodocs/tree_editor"
+require_relative "infodocs/renderer"
+require_relative "infodocs/url_helper"
+require_relative "infodocs/link_checker"
+require_relative "infodocs/linter"
+require_relative "infodocs/search"
+require_relative "infodocs/engine" if defined?(Rails)
+
+module Infodocs
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset!
+      @config = nil
+      @tree = nil
+      @search = nil
+      @rendered = nil
+    end
+
+    def tree
+      @tree ||= Tree.build(config.paths, drafts: show_drafts?)
+    end
+
+    # `draft: true` pages are visible only while developing the docs.
+    def show_drafts?
+      defined?(Rails) && Rails.env.development?
+    end
+
+    # Editing is a development-only feature, on top of `config.editable`.
+    def editing_enabled?
+      config.editable && Rails.env.development?
+    end
+
+    RENDER_CACHE_LIMIT = 500
+
+    # Rendered page, cached until the file changes on disk.
+    def render(page, mount_path: "/docs")
+      stat = page.file.stat
+      key = [page.file.to_s, stat.mtime.to_r, stat.size, mount_path]
+      @rendered ||= {}
+      @rendered.delete(@rendered.keys.first) if @rendered.size >= RENDER_CACHE_LIMIT && !@rendered.key?(key)
+      @rendered[key] ||= Renderer.new(page, mount_path: mount_path).call
+    end
+
+    def reload!
+      @tree = nil
+      @search = nil
+    end
+
+    # Reindexed once per tree load (every reload in development).
+    def search
+      @search ||= Search.new(tree, db_path: config.index_path.to_s).tap(&:reindex!)
+    end
+  end
+end

data/lib/tasks/infodocs.rake

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+namespace :infodocs do
+  desc "Report broken relative links, anchors and images in the docs"
+  task check_links: :environment do
+    problems = Infodocs::LinkChecker.new(Infodocs.tree).call
+    problems.each { |problem| puts "#{problem.page.file}: #{problem.target} (#{problem.reason})" }
+    puts "#{problems.size} broken link#{'s' unless problems.size == 1}"
+    exit(1) if problems.any?
+  end
+
+  desc "Check content: titles, frontmatter keys, hidden pages nobody links to, useless redirects"
+  task lint: :environment do
+    problems = Infodocs::Linter.new(Infodocs.tree).call
+    problems.each { |problem| puts "#{problem.page.file}: #{problem.message} [#{problem.rule}]" }
+    puts "#{problems.size} problem#{'s' unless problems.size == 1}"
+    exit(1) if problems.any?
+  end
+
+  desc "Export the docs as static HTML (default dir: tmp/infodocs-export). Run assets:precompile first"
+  task :export, [:dir] => :environment do |_task, args|
+    require "fileutils"
+    out = Pathname(args[:dir] || Rails.root.join("tmp/infodocs-export"))
+    mount = Infodocs::Engine.routes.find_script_name({}).presence || "/docs"
+    session = ActionDispatch::Integration::Session.new(Rails.application)
+    session.host! "localhost"
+
+    slugs = Infodocs.tree.all_pages.map(&:slug)
+    slugs.each do |slug|
+      path = [mount, slug].reject(&:empty?).join("/")
+      session.get(path)
+      abort "#{path} returned #{session.response.status}; static export needs auth = :none" unless session.response.successful?
+
+      target = out.join(*mount.split("/").reject(&:empty?), *slug.split("/"), "index.html")
+      FileUtils.mkdir_p(target.dirname)
+      target.write(session.response.body)
+    end
+
+    %w[llms.txt sitemap.xml].each do |name|
+      session.get("#{mount}/#{name}")
+      File.write(out.join(*mount.split("/").reject(&:empty?), name), session.response.body) if session.response.successful?
+    end
+
+    # Images and files next to the pages.
+    Infodocs.tree.sources.each do |source|
+      Dir.glob(source.path.join("**/*")).each do |file|
+        next unless Infodocs::Tree::ASSET_TYPES.key?(File.extname(file).downcase)
+
+        relative = Pathname(file).relative_path_from(source.path).to_s
+        next if relative.split("/").any? { |part| part.start_with?("_", ".") }
+
+        slug = Infodocs.tree.multiple_roots? ? File.join(source.key, relative) : relative
+        copy = out.join(*mount.split("/").reject(&:empty?), "_asset", slug)
+        FileUtils.mkdir_p(copy.dirname)
+        FileUtils.cp(file, copy)
+      end
+    end
+
+    public_assets = Rails.root.join("public/assets")
+    FileUtils.cp_r(public_assets, out.join("assets")) if public_assets.directory?
+    puts "Exported #{slugs.size} pages to #{out}"
+  end
+end

data/sig/infodocs.rbs

@@ -0,0 +1,4 @@
+module Infodocs
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,192 @@
+--- !ruby/object:Gem::Specification
+name: infodocs
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Jakub Cieślar
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-27 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'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: commonmarker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: stimulus-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: Mountable Rails engine that serves .md files from your repo as a docs
+  site with a sidebar tree (_tree.yml ordering), SQLite FTS5 search, server-side syntax
+  highlighting and Mermaid diagrams. Tailwind + Stimulus.
+email:
+- cieslar.jakub@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/infodocs/application_controller.rb
+- app/controllers/infodocs/assets_controller.rb
+- app/controllers/infodocs/editor_controller.rb
+- app/controllers/infodocs/indexes_controller.rb
+- app/controllers/infodocs/pages_controller.rb
+- app/controllers/infodocs/raws_controller.rb
+- app/controllers/infodocs/searches_controller.rb
+- app/controllers/infodocs/tags_controller.rb
+- app/controllers/infodocs/trees_controller.rb
+- app/helpers/infodocs/application_helper.rb
+- app/javascript/infodocs/application.js
+- app/javascript/infodocs/controllers/editor_controller.js
+- app/javascript/infodocs/controllers/highlight_controller.js
+- app/javascript/infodocs/controllers/mermaid_controller.js
+- app/javascript/infodocs/controllers/search_controller.js
+- app/javascript/infodocs/controllers/sidebar_controller.js
+- app/javascript/infodocs/controllers/toc_controller.js
+- app/javascript/infodocs/controllers/tree_editor_controller.js
+- app/javascript/infodocs/controllers/tree_state_controller.js
+- app/javascript/infodocs/vendor/sortable.esm.js
+- app/views/infodocs/_delete_button.html.erb
+- app/views/infodocs/_handle.html.erb
+- app/views/infodocs/_tree.html.erb
+- app/views/infodocs/editor/edit.html.erb
+- app/views/infodocs/pages/empty_folder.html.erb
+- app/views/infodocs/pages/not_found.html.erb
+- app/views/infodocs/pages/show.html.erb
+- app/views/infodocs/searches/index.html.erb
+- app/views/infodocs/tags/index.html.erb
+- app/views/layouts/infodocs/application.html.erb
+- config/importmap.rb
+- config/routes.rb
+- lib/generators/infodocs/install/install_generator.rb
+- lib/generators/infodocs/install/templates/getting-started.md.tt
+- lib/generators/infodocs/install/templates/initializer.rb.tt
+- lib/generators/infodocs/views/views_generator.rb
+- lib/infodocs.rb
+- lib/infodocs/code_theme.rb
+- lib/infodocs/configuration.rb
+- lib/infodocs/engine.rb
+- lib/infodocs/link_checker.rb
+- lib/infodocs/linter.rb
+- lib/infodocs/page.rb
+- lib/infodocs/rails_lexer.rb
+- lib/infodocs/renderer.rb
+- lib/infodocs/search.rb
+- lib/infodocs/source.rb
+- lib/infodocs/tree.rb
+- lib/infodocs/tree_editor.rb
+- lib/infodocs/url_helper.rb
+- lib/infodocs/version.rb
+- lib/tasks/infodocs.rake
+- sig/infodocs.rbs
+homepage: https://github.com/jcieslar/infodocs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jcieslar/infodocs
+  source_code_uri: https://github.com/jcieslar/infodocs
+  rubygems_mfa_required: 'true'
+  changelog_uri: https://github.com/jcieslar/infodocs/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: 'Markdown documentation browser for Rails: tree sidebar, full-text search,
+  Mermaid.'
+test_files: []