markdowndocs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42524ce732ca270ae79839b4d26522b30fab9e088793df8c62e0c20ac0c5b1c3
+  data.tar.gz: c999713e3b504d54838db523a0f708110f9f28a049efd1568dacfbafa3b9d1c6
+SHA512:
+  metadata.gz: 66583f10a3cf8c80eb651a0d3b0cbd99f86604313a36e91713d90569ee1ac1eb4889782969fcac16ad91dbb067a2a3853a20b5f99ddb7a7767529b7a489d7216
+  data.tar.gz: 705f2632e8a1429571b483d6a5ef6285af1a6380f428743b8adb5181342e2854027b327eceb3df001be4a6af3b932f713c2b6e48a5c81870569d6ae2dcfdb1fd

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-20
+
+### Added
+
+- Mountable Rails engine that serves markdown files as a browsable documentation site
+- GitHub Flavored Markdown rendering via Commonmarker (tables, task lists, strikethrough, autolinks, footnotes)
+- Syntax highlighting via Rouge with configurable theme
+- YAML front matter support for per-document title, description, and mode availability
+- Mode-based content filtering using HTML comment blocks
+- Category organization for the index page
+- Auto-generated table of contents from H2/H3 headings with anchor links
+- Breadcrumb navigation and related-documents sidebar
+- File-mtime-based cache invalidation using Rails.cache
+- HTML sanitization via rails-html-sanitizer
+- Directory traversal prevention via slug validation
+- i18n support for all UI strings
+- Install generator (`rails generate markdowndocs:install`)
+
+[0.1.0]: https://github.com/dschmura/markdowndocs/releases/tag/v0.1.0

data/README.md

@@ -0,0 +1,291 @@
+# Markdowndocs
+
+A drop-in mountable Rails engine that turns a folder of markdown files into a browsable documentation site with syntax highlighting, category grouping, and mode-based content filtering.
+
+## Features
+
+- **GitHub Flavored Markdown** — Tables, task lists, strikethrough, footnotes, autolinks, and more via [Commonmarker](https://github.com/gjtorikian/commonmarker)
+- **Syntax highlighting** — Code blocks highlighted with [Rouge](https://github.com/rouge-ruby/rouge) (configurable theme)
+- **Category organization** — Group docs into named categories for the index page
+- **Mode-based content filtering** — Show different content to different audiences (e.g., "User Guide" vs "Developer Guide")
+- **Table of contents** — Auto-generated from H2/H3 headings with anchor links
+- **YAML front matter** — Set title, description, and mode availability per document
+- **Breadcrumb navigation** — Category-aware breadcrumbs on each doc page
+- **Related documents** — Sidebar links to other docs in the same category
+- **Responsive design** — Tailwind CSS with mobile support
+- **Security** — HTML sanitization, slug validation, directory traversal prevention
+- **Caching** — Rendered markdown is cached with file-mtime-based invalidation
+- **i18n support** — All UI strings are translatable
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 7.1
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem "markdowndocs"
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate markdowndocs:install
+```
+
+The generator will:
+
+1. Create `config/initializers/markdowndocs.rb` with default configuration
+2. Create the `app/docs/` directory for your markdown files
+3. Mount the engine at `/docs` in your routes
+
+## Configuration
+
+Edit `config/initializers/markdowndocs.rb` to customize behavior:
+
+```ruby
+Markdowndocs.configure do |config|
+  # Path to markdown files (default: Rails.root.join("app/docs"))
+  # config.docs_path = Rails.root.join("app", "docs")
+
+  # Category → slug mapping
+  config.categories = {
+    "Getting Started" => %w[welcome quickstart],
+    "Guides" => %w[authentication deployment],
+    "Reference" => %w[api-reference configuration]
+  }
+
+  # Available documentation modes (default: %w[guide technical])
+  # config.modes = %w[guide technical]
+
+  # Default mode (default: "guide")
+  # config.default_mode = "guide"
+
+  # Rouge syntax highlighting theme (default: "github")
+  # config.rouge_theme = "github"
+
+  # Cache expiry for rendered markdown (default: 1.hour)
+  # config.cache_expiry = 1.hour
+
+  # Optional: Resolve current user's mode preference from database
+  # config.user_mode_resolver = ->(controller) {
+  #   controller.send(:current_user)&.preferences&.docs_mode
+  # }
+
+  # Optional: Save user's mode preference to database
+  # config.user_mode_saver = ->(controller, mode) {
+  #   controller.send(:current_user)&.preferences&.update!(docs_mode: mode)
+  # }
+end
+```
+
+### Configuration Options
+
+| Option               | Default                        | Description                                                    |
+| -------------------- | ------------------------------ | -------------------------------------------------------------- |
+| `docs_path`          | `Rails.root.join("app/docs")`  | Directory containing your markdown files                       |
+| `categories`         | `{}`                           | Maps category names to arrays of document slugs                |
+| `modes`              | `%w[guide technical]`          | Available viewing modes                                        |
+| `default_mode`       | `"guide"`                      | Mode shown by default                                          |
+| `rouge_theme`        | `"github"`                     | Syntax highlighting color scheme                               |
+| `cache_expiry`       | `1.hour`                       | Cache duration for rendered markdown                           |
+| `user_mode_resolver` | `nil`                          | Lambda to load a user's mode preference from the database      |
+| `user_mode_saver`    | `nil`                          | Lambda to persist a user's mode preference to the database     |
+
+## Writing Documentation
+
+Create markdown files in `app/docs/`. The filename (without `.md`) becomes the URL slug — `app/docs/quickstart.md` is served at `/docs/quickstart`.
+
+### Front Matter
+
+Add optional YAML front matter to set metadata:
+
+```markdown
+---
+title: "Quick Start Guide"
+description: "Get up and running in five minutes"
+modes:
+  - guide
+  - technical
+default_mode: guide
+---
+
+# Quick Start Guide
+
+Your content here...
+```
+
+If front matter is omitted, the title is extracted from the first H1 heading and the description from the first paragraph.
+
+### Mode Blocks
+
+Use HTML comments to show content only in specific modes:
+
+```markdown
+## Setup
+
+This paragraph appears in all modes.
+
+<!-- mode: guide -->
+Follow these steps to get started:
+1. Click the "Install" button
+2. Follow the on-screen prompts
+<!-- /mode -->
+
+<!-- mode: technical -->
+Add the dependency to your Gemfile and run the install generator:
+\`\`\`bash
+bundle add markdowndocs
+rails generate markdowndocs:install
+\`\`\`
+<!-- /mode -->
+```
+
+### Syntax Highlighting
+
+Code blocks are automatically syntax-highlighted. Specify the language after the opening fence:
+
+````markdown
+```ruby
+def hello
+  puts "Hello, world!"
+end
+```
+
+```javascript
+function hello() {
+  console.log("Hello, world!");
+}
+```
+````
+
+Supported languages include Ruby, JavaScript, Python, Bash, YAML, JSON, HTML, CSS, SQL, and [many more](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers).
+
+### Categories
+
+To organize docs on the index page, map category names to slugs in your configuration:
+
+```ruby
+config.categories = {
+  "Getting Started" => %w[welcome quickstart],
+  "Guides" => %w[authentication deployment]
+}
+```
+
+Documents not assigned to a category will appear in an "Uncategorized" group.
+
+## Rendering Pipeline
+
+When a documentation page is requested, the markdown goes through these stages:
+
+1. **File reading** — Load raw markdown from `app/docs/`
+2. **Mode filtering** — Strip content blocks not matching the current viewing mode
+3. **Commonmarker parsing** — Parse with GFM extensions (tables, strikethrough, autolinks, footnotes, task lists)
+4. **Syntax highlighting** — Apply Rouge highlighting to fenced code blocks
+5. **HTML sanitization** — Whitelist-based sanitization strips dangerous tags and attributes
+6. **Heading anchors** — Inject `id` attributes on H2/H3 headings for TOC linking
+7. **Caching** — Store rendered HTML keyed by file path, mtime, and mode
+
+## Caching
+
+Rendered HTML is cached using `Rails.cache` with a composite cache key based on file path, file modification time, and viewing mode. Cache is automatically invalidated when file content changes.
+
+To manually clear documentation caches:
+
+```ruby
+# In Rails console
+Rails.cache.clear
+
+# Or delete matched keys
+Rails.cache.delete_matched("markdown_*")
+```
+
+The default cache expiry is 1 hour, configurable via `config.cache_expiry`.
+
+## Security
+
+### Directory Traversal Prevention
+
+Slugs are validated to contain only alphanumeric characters, hyphens, and underscores. Patterns like `../` and `/` are rejected, ensuring only files within `app/docs/` are accessible.
+
+### HTML Sanitization
+
+All rendered HTML is passed through a whitelist-based sanitizer. Safe tags (headings, paragraphs, code blocks, lists, links, images, tables) are allowed. Script tags, event handlers, and dangerous attributes are stripped.
+
+### YAML Parsing
+
+Front matter is parsed with `YAML.safe_load` to prevent code execution.
+
+## Best Practices
+
+1. **Start with H1** — Every document should have exactly one H1 heading at the top
+2. **Write descriptive first paragraphs** — The first paragraph becomes the card description on the index page
+3. **Use meaningful filenames** — The filename becomes the URL slug; use kebab-case (e.g., `api-reference.md`)
+4. **Include code examples** — Use fenced code blocks with a language specifier for syntax highlighting
+5. **Link between docs** — Reference other docs with relative links: `[See authentication](/docs/authentication)`
+6. **Keep files focused** — Break large topics into multiple documents
+7. **Use sequential headings** — Don't skip levels (e.g., H1 to H3); this ensures proper TOC generation
+
+## Troubleshooting
+
+### Document Not Appearing
+
+1. Check the filename matches the slug in your category mapping
+2. Verify the file has a `.md` extension
+3. Ensure the file is in the `app/docs/` directory
+4. Restart the server if you modified the initializer
+
+### Syntax Highlighting Not Working
+
+1. Verify the code fence has a language specified (e.g., `` ```ruby ``)
+2. Check the Rouge theme is configured in the initializer
+3. Clear the cache: `Rails.cache.clear`
+
+### 404 Errors
+
+1. Verify the slug matches the filename (use kebab-case)
+2. Check the file exists in `app/docs/`
+3. Look for typos in the slug or filename
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run the tests:
+
+```bash
+bundle exec rspec
+```
+
+## Releasing
+
+1. Update `CHANGELOG.md` with a new `## [x.y.z] - YYYY-MM-DD` section and add a comparison link at the bottom.
+
+2. Bump the version in `lib/markdowndocs/version.rb`:
+
+   ```ruby
+   module Markdowndocs
+     VERSION = "x.y.z"
+   end
+   ```
+
+3. Commit and tag the release:
+
+   ```bash
+   git add lib/markdowndocs/version.rb CHANGELOG.md
+   git commit -m "Release vx.y.z"
+   git tag vx.y.z
+   git push origin main --tags
+   ```
+
+   Pushing the tag triggers the GitHub Actions release workflow, which builds and publishes the gem to RubyGems automatically.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [github.com/dschmura/markdowndocs](https://github.com/dschmura/markdowndocs).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/app/assets/javascripts/markdowndocs/controllers/docs_mode_controller.js

@@ -0,0 +1,58 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Documentation Mode Controller
+ *
+ * Handles localStorage persistence for guest users and provides
+ * optimistic UI updates for the documentation mode switcher.
+ *
+ * For authenticated users, the preference is stored in the database
+ * via the PreferencesController. For guests, we use localStorage
+ * as a fallback to persist their preference across sessions.
+ */
+export default class extends Controller {
+  static values = {
+    current: { type: String, default: "guide" }
+  }
+
+  static STORAGE_KEY = "markdowndocs_mode"
+
+  connect() {
+    if (!this.isAuthenticated()) {
+      this.restoreGuestMode()
+    }
+  }
+
+  isAuthenticated() {
+    const meta = document.querySelector('meta[name="user-authenticated"]')
+    return meta?.content === "true"
+  }
+
+  restoreGuestMode() {
+    try {
+      const savedMode = localStorage.getItem(this.constructor.STORAGE_KEY)
+
+      if (savedMode && savedMode !== this.currentValue) {
+        const url = new URL(window.location)
+        url.searchParams.set("mode", savedMode)
+        window.location.replace(url)
+      }
+    } catch (e) {
+      console.debug("localStorage unavailable for docs mode persistence")
+    }
+  }
+
+  saveGuestMode(mode) {
+    try {
+      localStorage.setItem(this.constructor.STORAGE_KEY, mode)
+    } catch (e) {
+      console.debug("localStorage unavailable for docs mode persistence")
+    }
+  }
+
+  currentValueChanged() {
+    if (!this.isAuthenticated()) {
+      this.saveGuestMode(this.currentValue)
+    }
+  }
+}

data/app/controllers/markdowndocs/application_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Markdowndocs
+  class ApplicationController < ::ApplicationController
+    protect_from_forgery with: :exception
+
+    # Make host app route helpers available in engine views
+    # (needed because isolate_namespace blocks host helpers by default)
+    helper Rails.application.routes.url_helpers
+
+    # Support Rails 8 built-in authentication (allow_unauthenticated_access)
+    # without requiring it — works with any auth system or none at all
+    if respond_to?(:allow_unauthenticated_access)
+      allow_unauthenticated_access
+    end
+
+    # Resume session if the host app supports it (Rails 8 auth)
+    before_action :resume_session, if: -> { respond_to?(:resume_session, true) }
+  end
+end

data/app/controllers/markdowndocs/docs_controller.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Markdowndocs
+  class DocsController < ApplicationController
+    before_action :validate_slug, only: :show
+    before_action :set_docs_mode
+    helper Markdowndocs::DocsHelper
+
+    SAFE_SLUG_PATTERN = /\A[a-zA-Z0-9_-]+\z/
+
+    def index
+      @docs_by_category = Documentation.grouped_by_category
+    end
+
+    def show
+      @doc = Documentation.find_by_slug(params[:slug])
+
+      if @doc.nil?
+        render_not_found
+        return
+      end
+
+      rendered_html = MarkdownRenderer.render(
+        @doc.content,
+        cache_key: @doc.cache_key,
+        mode: @docs_mode
+      )
+      @rendered_content = helpers.add_heading_anchors(rendered_html)
+      @related_docs = Documentation.by_category(@doc.category).reject { |d| d.slug == @doc.slug }
+      @available_modes = @doc.available_modes
+      @toc_items = helpers.generate_table_of_contents(@rendered_content)
+    end
+
+    private
+
+    def validate_slug
+      slug = params[:slug].to_s
+
+      unless slug.match?(SAFE_SLUG_PATTERN)
+        render_not_found
+      end
+    end
+
+    def render_not_found
+      file_404 = Rails.public_path.join("404.html")
+      if file_404.exist?
+        render file: file_404, status: :not_found, layout: false
+      else
+        head :not_found
+      end
+    end
+
+    def set_docs_mode
+      @docs_mode = determine_docs_mode
+    end
+
+    def determine_docs_mode
+      mode = params[:mode] ||
+        resolve_user_mode ||
+        cookies[:markdowndocs_mode] ||
+        Markdowndocs.config.default_mode
+
+      valid_modes = Markdowndocs.config.modes
+      valid_modes.include?(mode) ? mode : Markdowndocs.config.default_mode
+    end
+
+    def resolve_user_mode
+      resolver = Markdowndocs.config.user_mode_resolver
+      return nil unless resolver.respond_to?(:call)
+
+      resolver.call(self)
+    rescue
+      nil
+    end
+  end
+end

data/app/controllers/markdowndocs/preferences_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Markdowndocs
+  class PreferencesController < ApplicationController
+    def update
+      mode = params[:mode].to_s
+
+      unless Markdowndocs.config.modes.include?(mode)
+        head :unprocessable_entity
+        return
+      end
+
+      # Save to database via host app's lambda (if configured)
+      saver = Markdowndocs.config.user_mode_saver
+      if saver.respond_to?(:call)
+        begin
+          saver.call(self, mode)
+        rescue => e
+          Rails.logger.warn("Markdowndocs: user_mode_saver failed: #{e.message}")
+        end
+      end
+
+      # Always set cookie as fallback
+      cookies[:markdowndocs_mode] = {
+        value: mode,
+        expires: 1.year.from_now,
+        httponly: true
+      }
+
+      redirect_back(fallback_location: markdowndocs.root_path, status: :see_other)
+    end
+  end
+end

data/app/helpers/markdowndocs/docs_helper.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Markdowndocs
+  module DocsHelper
+    def generate_table_of_contents(html)
+      return [] if html.blank?
+
+      doc = Nokogiri::HTML.fragment(html)
+      toc_items = []
+
+      doc.css("h2, h3").each do |heading|
+        text = heading.text.strip
+        next if text.blank?
+
+        slug = heading["id"].presence || slugify_heading(text)
+
+        toc_items << {
+          text: text,
+          slug: slug,
+          level: heading.name[1].to_i
+        }
+      end
+
+      toc_items
+    end
+
+    def slugify_heading(text)
+      text.to_s
+        .downcase
+        .gsub(/[^\w\s-]/, "")
+        .gsub(/\s+/, "-").squeeze("-")
+        .gsub(/^-|-$/, "")
+    end
+
+    def add_heading_anchors(html)
+      return html if html.blank?
+
+      doc = Nokogiri::HTML.fragment(html)
+
+      doc.css("h2, h3").each do |heading|
+        text = heading.text.strip
+        next if text.blank?
+
+        unless heading["id"].present?
+          slug = slugify_heading(text)
+          heading["id"] = slug
+        end
+      end
+
+      doc.css("a.anchor").each do |anchor|
+        anchor.remove if anchor.text.strip.empty?
+      end
+
+      doc.to_html
+    end
+
+    def markdowndocs_format_breadcrumbs(category, title)
+      [
+        {name: "Docs", path: markdowndocs.root_path, current: false},
+        {name: category, path: nil, current: false},
+        {name: title, path: nil, current: true}
+      ]
+    end
+  end
+end