infodocs 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 533feb13c1f6b783ea3c35e75c9ddee6eb8aeb75824211ba63b14abbef9ff365
+  data.tar.gz: 1fa1dbcbfe09aa223887c25f3531da22c85345554c4c7a82ff9c35f15501d8be
+SHA512:
+  metadata.gz: 51b65648f39c3aa0ee255d2f6d69d5260ad1078eef149642a7f49a9bf20934bd3a7186a82259f1b6904c3394bae0bedd38f9cdf7fec67837ade5c66fbdf58e2d
+  data.tar.gz: 0746e6d98ee89475c1517ea068320d7b843a3d2a476ee1d0ee69c3c74839b4541bfc2572c0e1a85464c6d1ede421a7e0b7f90015a1aedc41a745ff73e01755a8

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.3.0 - 2026-10-28
+
+- `infodocs:lint` content checks; `CONTRIBUTING.md` with a browser checklist
+- "Copy Markdown" button and `/docs/_raw/<page>`
+- "On this page" on small screens, sidebar remembers open folders and scrolls to the current page, search terms highlighted on the target page, SortableJS bundled, `config.mermaid_url`
+- Footnotes, heading anchors, code embeds from files (`file=app/x.rb#L1-20`)
+- Branding (`logo`, `favicon`, `header_links`, `head_html`) and `infodocs_page_path` / `infodocs_page_url` helpers for the host app
+- `redirect_from` frontmatter (301); moving pages in edit mode leaves redirects behind
+- `draft: true` frontmatter (development only) and `config.page_authorize` for per-page visibility
+
+## 0.2.0 - 2026-10-19
+
+- Read-only docs browser: tree sidebar (`_tree.yml` ordering), FTS5 search with advanced syntax, Rouge highlighting, Mermaid, auth modes (none/basic/devise/lambda), several named sources
+- Development-only edit mode: split Markdown editor with live preview, create, move/reorder, delete
+- Code palettes (`one`, `github`, `vscode`, `catppuccin`), code block header with copy button, line numbers and highlighted lines
+- GitHub-style alerts (`> [!NOTE]`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`)
+- Images and files next to pages are served by the engine; `infodocs:check_links` rake task
+- Page footer: last updated (git) and optional "Edit on GitHub" (`repo_url`, `repo_branch`)
+- Page tags (frontmatter or `_tree.yml`), sidebar tag filter, tag pages, `tag:` search, tags field in the editor
+- Live search dropdown with history; render cache
+- `llms.txt`, `sitemap.xml`, `infodocs:export` static export
+- 404 page suggests matching pages; print stylesheet; skip-to-content link
+- Fix: duplicate heading `id` attributes, crash on headings with inline code/emphasis
+- CI workflow, `rubygems_mfa_required`

data/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+The tests cover the Ruby side and the rendered HTML. The JavaScript (Stimulus controllers) and the look of the pages are **not** covered by automated tests, so before a release click through the checklist below in a real browser, in a host app with the gem installed (`bin/rails g infodocs:install`).
+
+## Browser checklist
+
+Desktop (≥ 1280px) and a phone-sized window (≈ 390px), light and dark mode:
+
+- [ ] Sidebar: folders open/close, the state survives a reload, the current page is scrolled into view; on a phone it is a drawer.
+- [ ] Header: logo, links and title look right; search field is usable on a phone.
+- [ ] Search: `⌘K` / `/` focuses the field; typing shows results; arrows + Enter open one; the page marks the matching words; an empty field shows recent searches.
+- [ ] Page: breadcrumbs, tags, last updated, previous/next; "On this page" is collapsible below 1280px and a sticky list above.
+- [ ] Code: highlighting for Ruby/JS, Copy button, line numbers and highlighted lines (`{2,4-6} showLineNumbers`), `file=` embeds.
+- [ ] Mermaid diagram renders and follows dark mode.
+- [ ] Alerts (`> [!NOTE]`), footnotes, heading `#` links, images next to a page.
+- [ ] Copy Markdown puts the page source on the clipboard.
+- [ ] Tags: chips filter the sidebar, `/docs/_tags` and `/docs/_tags/<tag>` work.
+- [ ] Draft pages show only in development (with a badge); `page_authorize` hides pages from the sidebar, search and by URL.
+- [ ] Edit mode (development only): editor toolbar and ⌘S, live preview, Tags field, New page/folder, drag & drop reorder/move (a redirect is left behind), delete with confirmation.
+- [ ] Printing a page hides the sidebar, header and buttons.
+
+## Before a release
+
+1. Update `lib/infodocs/version.rb` and `CHANGELOG.md`.
+2. `bundle exec rake test`, `bin/rails infodocs:check_links` and `bin/rails infodocs:lint` in a host app.
+3. `gem build infodocs.gemspec`, inspect the file list, then tag and push.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jakub Cieślar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,341 @@
+# Infodocs
+
+A mountable Rails engine that turns the Markdown files in your repository into a modern documentation site: a sidebar tree, powerful full-text search, syntax highlighting, Mermaid diagrams and a layout that works well on phones. Built for apps using **Tailwind**, **Stimulus** and **importmap**.
+
+There is no database and no build step. Your `.md` files are the source of truth, so docs are versioned, reviewed and deployed together with your code.
+
+## Features
+
+- **Sidebar tree** built from your folders, with collapsible sections and the current page highlighted.
+- **Explicit ordering** through a small `_tree.yml` per folder (title, order, hidden entries, tags).
+- **Full-text search** powered by SQLite FTS5: ranking, snippets with highlighted matches, phrases, `OR`, exclusions, prefixes and field filters; live results while typing. Diacritics are folded (Polish `ł`, `ą`, `ę`… work).
+- **GitHub-flavoured Markdown**: tables, task lists, strikethrough, autolinks, `> [!NOTE]` style alerts.
+- **Server-side syntax highlighting** with Rouge (Ruby, Rails DSL, JS, and every other Rouge language), your choice of palette, copy button, optional line numbers and highlighted lines.
+- **Mermaid diagrams** from ` ```mermaid ` blocks, loaded lazily only on pages that contain one, dark-mode aware.
+- **Relative links and images**: `[setup](../guides/setup.md#install)` and `![](img/flow.png)` work on GitHub and on the docs site; `infodocs:check_links` finds broken ones.
+- **Tags**: several per page, filter chips in the sidebar, tag pages, `tag:` search.
+- **Table of contents** (h2/h3) with scroll-spy (a collapsible "On this page" on small screens), the sidebar remembers open folders and scrolls to the current page, breadcrumbs, previous/next navigation, last-updated date and an optional "Edit on GitHub" link.
+- **Mobile friendly**: the sidebar becomes a drawer, tap targets are 44px, code and tables scroll horizontally.
+- **Dark mode** through Tailwind's `dark:` variants (follows the system setting).
+- **Access control**: public, HTTP basic auth, Devise (with optional role check) or your own lambda.
+- **Keyboard shortcuts**: `⌘K` / `Ctrl+K` or `/` focuses search.
+- **Multiple source folders** from anywhere in the app (or a git submodule / checkout), mounted under one site with their own URL names and titles.
+- **Edit mode (development only)**: Markdown editor with live preview, create, drag & drop reorder/move and delete of pages and folders, all written to your `.md` files.
+- **`llms.txt`, `sitemap.xml` and static export** for hosting the docs elsewhere.
+- **Live pickup of changes** in development: edit a file, refresh the page.
+
+## Requirements
+
+Ruby 3.2+, Rails 7.1+ with `tailwindcss-rails` (Tailwind 4), `importmap-rails` and `stimulus-rails` in the host app. SQLite is used for the search index even if your app uses another database. Devise is only needed for `auth = :devise`.
+
+## Installation
+
+Add the gem to your `Gemfile` (not published on RubyGems yet, so use the repository or a local path):
+
+```ruby
+gem "infodocs", github: "jcieslar/infodocs"
+# or: gem "infodocs", path: "../infodocs"
+```
+
+Install and run the generator:
+
+```sh
+bundle install
+bin/rails g infodocs:install
+```
+
+Options: `--path=docs` (folder with your Markdown, relative to the app root) and `--mount=/docs` (URL prefix).
+
+The generator:
+
+1. creates `config/initializers/infodocs.rb`,
+2. mounts the engine in `config/routes.rb`,
+3. creates the docs folder with `_tree.yml` and a sample page,
+4. adds `@plugin "@tailwindcss/typography"` and an `@source` line for the engine's views to your Tailwind entry CSS (`app/assets/tailwind/application.css`),
+5. adds `/tmp/infodocs/` to `.gitignore`.
+
+Then start the app and open `/docs`. It is safe to re-run the generator; it will not duplicate the route or CSS lines.
+
+> The `@source` line contains the absolute path of the installed gem. Re-run `bin/rails g infodocs:install` after the gem path changes (for example after a version bump with a git or path source).
+
+## Writing docs
+
+```
+docs/
+  _tree.yml          # optional: title, order, hidden, tags
+  index.md           # landing page of the folder (index.md or README.md)
+  getting-started.md
+  guides/
+    _tree.yml
+    setup.md
+    deploy.md
+```
+
+Files and folders starting with `_` or `.` are ignored.
+
+`_tree.yml`:
+
+```yaml
+title: Guides            # name of the folder in the sidebar
+order: [setup, deploy]   # file names without .md, or subfolder names; the rest follows alphabetically
+hidden: [drafts]         # reachable by URL, not shown in the sidebar or prev/next
+tags:                    # optional, see "Tags"
+  setup: [guide, rails]
+```
+
+Page title: the `title:` key in YAML frontmatter, otherwise the first `# Heading`, otherwise the file name.
+
+A page:
+
+````markdown
+---
+title: Setup guide
+tags: [guide, rails]
+---
+
+# Setup
+
+## Install
+
+```ruby
+puts "highlighted by Rouge"
+```
+
+```mermaid
+graph LR
+  Markdown --> Infodocs --> Docs
+```
+````
+
+### Alerts
+
+GitHub-style alerts: put `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` on the first line of a blockquote:
+
+```markdown
+> [!WARNING]
+> Back up the database first.
+```
+
+### Images and files
+
+Relative paths work next to a page: `![Diagram](img/flow.png)`. The engine serves png, jpg, gif, webp, avif, svg, pdf, mp4 and webm from inside the docs directories only (never `_`/`.` entries).
+
+### Code blocks
+
+Rouge highlights fenced blocks by language: `ruby`, `rails` (Ruby plus Rails DSL: associations, callbacks such as `after_create_commit`, routes, migrations), `erb`, `js`/`javascript`, `yaml`, `shell`, `json`, `html`, `css`, `sql` and everything else Rouge supports. Highlighting happens on the server, so there is no flash of unstyled code.
+
+Each block has a header with the language, an optional file name and a **Copy** button. After the language you can add line highlights, `showLineNumbers` and a file name, in any order:
+
+````markdown
+```ruby {2,4-6} showLineNumbers app/models/note.rb
+class Note < ApplicationRecord
+end
+```
+````
+
+To show a real file from your app instead of pasting it, use `file=` (optionally with a line range). The block body is ignored:
+
+````markdown
+```ruby file=app/models/note.rb#L3-12 showLineNumbers
+```
+````
+
+Only files inside `Rails.root` can be embedded; dotfiles, credentials, keys and `..` paths are refused (the block shows an error and `infodocs:check_links` reports it). The language is guessed from the file name when you leave it out.
+
+Headings get a `#` link on hover, and footnotes (`text[^1]` with `[^1]: note`) are supported.
+
+Pick a palette in the initializer; every palette has a light and a dark variant (dark follows `prefers-color-scheme` or a `.dark` class):
+
+```ruby
+config.code_theme = :one          # :one (default), :github, :vscode, :catppuccin
+
+# or tweak colours of a base palette (roles: fg bg comment keyword string number
+# function type variable builtin operator punctuation tag attribute escape regex symbol)
+config.code_theme = { base: :one, dark: { keyword: "#ff79c6" } }
+```
+
+### Tags
+
+A page can have several tags, from either place (they are merged and lower-cased):
+
+```markdown
+---
+tags: [guide, deploy]
+---
+```
+
+```yaml
+# guides/_tree.yml, which is what the edit page's "Tags" field writes (development only)
+tags:
+  setup: [guide, rails]     # page name => tags
+```
+
+When any tag exists the sidebar shows tag chips: click one to filter the tree (`?tag=guide`, kept while you navigate), click again to clear. `/docs/_tags` lists all tags, `/docs/_tags/guide` the pages with that tag. Tags follow a page when it is moved in the tree.
+
+## Search
+
+Results link to the page with `?q=…`, which marks the matching words on the page and scrolls to the first one. Typing in the header field shows live results (arrow keys + Enter); with an empty field the last searches are offered. `GET /docs/search.json?q=…` returns the same results as JSON.
+
+| Query | Meaning |
+| --- | --- |
+| `deploy kamal` | both words (AND) |
+| `"exact phrase"` | phrase |
+| `deploy OR release` | either word |
+| `deploy -docker` | exclude a word |
+| `depl*` | prefix |
+| `title:setup` | match in the page title only |
+| `heading:install` | match in headings only |
+| `path:guides` | match in the URL path |
+| `tag:guide` | pages with the tag (alone or combined with words) |
+
+Results are ranked with BM25 (title and headings weigh more than body text) and show a snippet with the matching terms marked. The index is stored in `tmp/infodocs/index.sqlite3` and updated from file modification times.
+
+## Configuration
+
+`config/initializers/infodocs.rb`:
+
+```ruby
+Infodocs.configure do |config|
+  # One or more directories. With several, each becomes a top-level folder
+  # named after the directory...
+  config.paths = [Rails.root.join("docs"), Rails.root.join("guides")]
+
+  # ...or name them yourself (slug = URL segment, title = sidebar label):
+  config.paths = [
+    { path: Rails.root.join("docs"), slug: "app", title: "Application" },
+    { path: Rails.root.join("vendor/shared-docs/docs"), slug: "shared" }  # e.g. a git submodule
+  ]
+
+  config.title = "Docs"                                   # header + <title>
+  config.editable = Rails.env.development?                # edit mode, development only (see below)
+  config.code_theme = :one                                # see "Code blocks"
+  config.stylesheets = %w[tailwind]                       # stylesheet tags in the docs layout
+  config.index_path = Rails.root.join("tmp/infodocs/index.sqlite3")
+
+  config.repo_url = "https://github.com/acme/app"         # optional: "Edit on GitHub" link in the footer
+  config.repo_branch = "main"
+
+  config.auth = :none                                     # see below
+end
+```
+
+### Copy as Markdown
+
+Every page has a **Copy Markdown** button that copies the source (without frontmatter) to the clipboard, handy for pasting into an AI assistant. The same text is served at `/docs/_raw/<page>` under the page's normal access rules.
+
+### Redirects
+
+When a page gets a new address, list the old ones in its frontmatter and they answer with a 301 to the new page:
+
+```yaml
+---
+redirect_from: [old/path, getting-started]
+---
+```
+
+Moving a page or a folder in edit mode adds the old addresses for you (the page's frontmatter is rewritten as YAML, so comments inside it are not kept). A real page at the old address always wins over a redirect.
+
+### Drafts and per-page visibility
+
+`draft: true` in a page's frontmatter keeps it out of the docs everywhere except development (where it is marked with a *draft* badge): no URL, no sidebar entry, no search result, not in `llms.txt` or `sitemap.xml`.
+
+To show some pages only to some visitors, return false from `page_authorize`. A hidden page behaves as if it did not exist (404, missing from the sidebar, search, tags, prev/next, `llms.txt` and `sitemap.xml`):
+
+```ruby
+config.page_authorize = ->(page, user) { !page.tags.include?("internal") || user&.admin? }
+```
+
+`user` is the signed-in Devise user (`auth = :devise`) or `current_user` if your controllers define it, otherwise `nil`. This is independent of the global `auth` check below, which gates the whole site.
+
+### Access control
+
+```ruby
+config.auth = :none                       # public (default)
+
+config.auth = :basic                      # HTTP basic auth
+config.basic_auth = { user: ENV["DOCS_USER"], password: ENV["DOCS_PASSWORD"] }
+
+config.auth = :devise                     # require a signed-in Devise user
+config.devise = { scope: :user, authorize: ->(user) { user.admin? } }
+
+config.auth = -> { current_user&.staff? } # any lambda, evaluated in the controller;
+                                          # truthy allows, falsy returns 403
+```
+
+## Edit mode (development only)
+
+In `Rails.env.development`, with `config.editable = true`, the docs get editing tools (only on this machine, only for users who pass the docs `auth`):
+
+- **Edit** on a page opens a Markdown editor with a toolbar (bold, italic, code, link, headings, lists, Ruby/JS/Mermaid blocks), a **Tags** field and a live server-rendered preview (tabs on mobile). `⌘S` / **Save** writes the `.md` file.
+- **New page** in the sidebar creates a page or a folder (a folder needs no `index.md`).
+- **Reorder** lets you drag pages and folders to reorder or move them; `_tree.yml` files are updated and files are moved with `git mv`.
+- The trash icon deletes a page or a folder with its contents (`git rm`, with a confirmation).
+
+Everything lands in your working tree: review and commit it with git.
+
+Safeguards: the routes return 404 unless the app runs in development, the request comes from this machine and `editable` is on. Users must also pass the docs `auth` check. Only files inside the configured docs folders can be written, moved or deleted.
+
+## Tools
+
+```sh
+bin/rails infodocs:check_links          # broken relative links, anchors, images and embeds (exit 1 if any, for CI)
+bin/rails infodocs:lint                 # content checks, see below (exit 1 if any)
+bin/rails "infodocs:export[tmp/site]"   # static HTML export
+```
+
+`infodocs:lint` reports pages without a title (`# Heading` or `title:`), unknown frontmatter keys (known: `title`, `description`, `tags`, `draft`, `redirect_from`), hidden pages that no page links to, and `redirect_from` entries that are shadowed by a real page or claimed twice.
+
+The export includes images, `llms.txt`, `sitemap.xml` and `public/assets` if present; run `assets:precompile` first and set `auth = :none`. Live search and edit mode need the Rails server, so they do not work in the export.
+
+The engine also serves `/docs/llms.txt` and `/docs/sitemap.xml` behind the same auth as the docs (URLs use the request host). `config.repo_url` adds an "Edit on GitHub" link to the page footer.
+
+## Branding and linking from your app
+
+```ruby
+config.logo = "/logo.svg"                 # shown before the title
+config.favicon = "/favicon.ico"
+config.header_links = [{ label: "App", url: "/" }, { label: "Status", url: "https://status.example.com" }]
+config.head_html = '<script defer src="https://analytics.example.com/script.js"></script>'   # trusted HTML for <head>
+
+# logo, favicon and head_html can also be lambdas that receive the view:
+config.logo = ->(view) { view.image_path("logo.svg") }
+```
+
+Mermaid is loaded from a CDN by default (SortableJS for drag & drop ships inside the gem). To self-host Mermaid, e.g. for a strict CSP or an offline network, point `config.mermaid_url` at your copy of `mermaid.esm.min.mjs` (its chunk files must sit next to it).
+
+Header links collapse into the sidebar drawer on phones. In your own views and controllers link to a docs page with `infodocs_page_path("guides/setup")` (also `infodocs_page_url`); without an argument it points to the docs home. (`infodocs_path` is the route helper Rails creates for the mount itself and always points to the docs root.)
+
+## Customising the look
+
+Everything is plain ERB with Tailwind utility classes. Copy the views into your app and edit them:
+
+```sh
+bin/rails g infodocs:views
+```
+
+Views then live in `app/views/infodocs` and `app/views/layouts/infodocs`.
+
+## How it works
+
+- `Infodocs::Tree` scans the configured folders and `_tree.yml` files.
+- `Infodocs::Renderer` converts Markdown with commonmarker, highlights code with Rouge, builds the TOC and rewrites links.
+- `Infodocs::Search` maintains the FTS5 index.
+- The engine ships its own small Stimulus application (`infodocs/application`) with sidebar, search shortcut, TOC and Mermaid controllers, pinned through importmap, so it does not touch your own JavaScript.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+## Roadmap
+
+- Sources from remote git repositories.
+- Translations (`docs/pl`, `docs/en`) with a language switcher.
+- A visual (WYSIWYG) editor mode.
+- Browser (system) tests; for now see `CONTRIBUTING.md` for the manual checklist.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create do |t|
+  t.warning = false
+end
+
+task default: :test

data/app/controllers/infodocs/application_controller.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Infodocs
+  class ApplicationController < ActionController::Base
+    layout "infodocs/application"
+
+    before_action :authenticate_docs!
+    helper_method :docs_tree, :page_allowed?, :visible_pages, :visible_tags
+
+    private
+
+    # Editing endpoints: development only, this machine only, plus docs auth.
+    def ensure_editable!
+      head :not_found unless Infodocs.editing_enabled? && request.local?
+    end
+
+    def docs_tree
+      Infodocs.tree
+    end
+
+    # The signed-in user handed to `config.page_authorize` (nil without one).
+    def docs_user
+      auth = Infodocs.config.auth
+      if auth == :devise
+        send(:"current_#{Infodocs.config.devise.fetch(:scope, :user)}")
+      elsif respond_to?(:current_user, true)
+        current_user
+      end
+    end
+
+    def page_allowed?(page)
+      authorize = Infodocs.config.page_authorize
+      authorize.nil? || page.nil? || !!authorize.call(page, docs_user)
+    end
+
+    def visible_pages
+      @visible_pages ||= docs_tree.pages.select { |page| page_allowed?(page) }
+    end
+
+    def visible_tags
+      @visible_tags ||= visible_pages.flat_map(&:tags).tally.sort.to_h
+    end
+
+    def authenticate_docs!
+      auth = Infodocs.config.auth
+
+      if auth.respond_to?(:call)
+        instance_exec(&auth) || head(:forbidden)
+      elsif auth == :basic
+        credentials = Infodocs.config.basic_auth
+        authenticate_or_request_with_http_basic("Docs") do |user, password|
+          ActiveSupport::SecurityUtils.secure_compare(user, credentials[:user].to_s) &
+            ActiveSupport::SecurityUtils.secure_compare(password, credentials[:password].to_s)
+        end
+      elsif auth == :devise
+        authenticate_devise_user!
+      end
+    end
+
+    def authenticate_devise_user!
+      scope = Infodocs.config.devise.fetch(:scope, :user)
+      send(:"authenticate_#{scope}!")
+      user = send(:"current_#{scope}")
+      authorize = Infodocs.config.devise[:authorize]
+      head :forbidden if authorize && !authorize.call(user)
+    end
+  end
+end

data/app/controllers/infodocs/assets_controller.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Infodocs
+  # Images and other files that sit next to the markdown pages.
+  class AssetsController < ApplicationController
+    def show
+      file = docs_tree.asset(params[:path])
+      return head(:not_found) unless file
+
+      # SVG may carry scripts; the sandbox keeps them inert when opened directly.
+      response.set_header("Content-Security-Policy", "sandbox")
+      send_file file, type: Tree::ASSET_TYPES.fetch(file.extname.downcase), disposition: "inline"
+    end
+  end
+end

data/app/controllers/infodocs/editor_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Infodocs
+  # Writes edited Markdown straight to the source file (to be committed by the
+  # developer). Only reachable in development, from this machine, and only for
+  # users who already pass the docs authentication.
+  class EditorController < ApplicationController
+    before_action :ensure_editable!
+    before_action :load_page
+
+    def edit
+      @content = @page.raw
+    end
+
+    def update
+      @page.write(params.require(:content))
+      Infodocs.reload!
+      render json: { saved: true, path: @page.relative_path, title: Infodocs.tree.find(@page.slug)&.title }
+    rescue ActionController::ParameterMissing
+      render json: { saved: false, error: "content missing" }, status: :unprocessable_entity
+    end
+
+    def preview
+      draft = Page.new(file: @page.file, slug: @page.slug, root: @page.root, raw: params[:content].to_s)
+      rendered = Renderer.new(draft, mount_path: root_path).call
+      render html: rendered.html.html_safe, layout: false
+    end
+
+    private
+
+    def load_page
+      @page = docs_tree.find(params[:path].to_s)
+      head(:not_found) unless @page && page_allowed?(@page)
+    end
+  end
+end

data/app/controllers/infodocs/indexes_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Infodocs
+  # Machine-readable indexes: llms.txt (https://llmstxt.org) and sitemap.xml.
+  class IndexesController < ApplicationController
+    def llms
+      lines = ["# #{Infodocs.config.title}", ""]
+      visible_pages.each do |page|
+        note = page.description
+        lines << "- [#{page.title}](#{page_url(page.slug)})#{": #{note}" if note.present?}"
+      end
+      render plain: lines.join("\n") + "\n", content_type: "text/plain"
+    end
+
+    def sitemap
+      urls = visible_pages.map do |page|
+        "  <url><loc>#{ERB::Util.html_escape(page_url(page.slug))}</loc><lastmod>#{page.updated_at.utc.iso8601}</lastmod></url>"
+      end
+      render xml: %(<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n#{urls.join("\n")}\n</urlset>\n)
+    end
+  end
+end

data/app/controllers/infodocs/pages_controller.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Infodocs
+  class PagesController < ApplicationController
+    def show
+      @page = docs_tree.find(params[:path].to_s) || first_page
+      return show_folder if @page.nil?
+      return render_not_found unless page_allowed?(@page)
+
+      @rendered = Infodocs.render(@page, mount_path: root_path)
+      @trail = docs_tree.trail(@page.slug)
+      index = visible_pages.index(@page)
+      @previous = visible_pages[index - 1] if index&.positive?
+      @next = visible_pages[index + 1] if index
+    end
+
+    private
+
+    # A folder without a landing page opens its first page; an empty one says so.
+    def show_folder
+      moved = docs_tree.redirect_for(params[:path].to_s)
+      moved_page = moved && docs_tree.find(moved)
+      return redirect_to(page_path(moved), status: :moved_permanently) if moved_page && page_allowed?(moved_page)
+
+      folder = docs_tree.node(params[:path].to_s)
+      return render_not_found unless folder&.folder?
+
+      first = docs_tree.first_page_under(folder)
+      first = visible_pages.find { |page| page.slug.start_with?("#{folder.slug}/") } unless first.nil? || page_allowed?(first)
+      return redirect_to(page_path(first.slug)) if first
+
+      @folder = folder
+      @trail = docs_tree.trail(folder.slug)
+      render "infodocs/pages/empty_folder"
+    end
+
+    def first_page
+      visible_pages.first if params[:path].blank?
+    end
+
+    # Unknown path: offer pages whose text matches the words in the URL.
+    def render_not_found
+      words = params[:path].to_s.split(/[^\p{L}\p{N}]+/).select { |word| word.length > 2 }.first(5)
+      @suggestions = words.any? ? Infodocs.search.search(words.join(" OR "), limit: 5) : []
+      render "infodocs/pages/not_found", status: :not_found
+    end
+  end
+end

data/app/controllers/infodocs/raws_controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Infodocs
+  # The Markdown source of a page (without frontmatter), for "Copy Markdown".
+  class RawsController < ApplicationController
+    def show
+      page = docs_tree.find(params[:path].to_s) || (docs_tree.pages.first if params[:path].blank?)
+      return head(:not_found) unless page && page_allowed?(page)
+
+      render plain: page.body, content_type: "text/plain"
+    end
+  end
+end

data/app/controllers/infodocs/searches_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Infodocs
+  class SearchesController < ApplicationController
+    def index
+      @query = params[:q].to_s.strip
+      @results = @query.empty? ? [] : Infodocs.search.search(@query, limit: 100).select { |r| page_allowed?(docs_tree.find(r.slug)) }
+      @results = @results.first(request.format.json? ? 8 : 20)
+
+      respond_to do |format|
+        format.html
+        format.json do
+          render json: @results.map { |r| { title: r.title, path: r.slug, url: page_path(r.slug), snippet: r.snippet } }
+        end
+      end
+    end
+  end
+end