md_record 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 616c429f1a3a4330fce85c47841213fc47a4cfeb15efc8606af343dc9134e302
+  data.tar.gz: 8f5c9d8ad4354d5d2ddc143ba19d999e11de5a0f40706479472bb3bc3e50f134
+SHA512:
+  metadata.gz: e581cd2950f178ea6806092df5746d9add34d9fe2fd8494a0bd5a9c7ea71d376e71cd86f75533fb43dcf8496403e42723b96f6d9e3f687ee0e73318e72050531
+  data.tar.gz: ddd1bc077f3b20b757a9bc25e8075e88db637340f7413b4077cee31def87ab05894ee6c73342257cfa8bfcde61f3cbb4dfa32f175916c37b3ea613481ea19063

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Benito Serna
+
+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,143 @@
+# MdRecord
+
+File-backed models for Rails. Similar to ActiveRecord but reads from markdown files with YAML frontmatter.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "md_record"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Basic Model
+
+```ruby
+class Post < MdRecord::Base
+end
+```
+
+By default, files are loaded from `app/views/posts/` (based on model name).
+
+```ruby
+Post.all        # All posts
+Post.published  # Only published posts
+Post.find(slug) # Find by slug or raise MdRecord::RecordNotFound
+```
+
+### Custom Path
+
+```ruby
+class Article < MdRecord::Base
+  md_record_path "content/articles"
+end
+```
+
+### Categorized Model
+
+```ruby
+class Guide < MdRecord::Base
+  include MdRecord::Categorizable
+
+  md_record_categories(
+    "getting-started" => { name: "Getting Started", position: 1 },
+    "advanced" => { name: "Advanced", position: 2 }
+  )
+end
+```
+
+Files are organized in subfolders:
+```
+app/views/guides/
+  getting-started/
+    first-steps.md
+  advanced/
+    custom-config.md
+```
+
+```ruby
+Guide.categories  # Returns array of MdRecord::Category objects
+guide.category?("getting-started")  # Check if guide belongs to category
+guide.category_name  # "Getting Started"
+```
+
+## File Format
+
+Markdown files with YAML frontmatter:
+
+```markdown
+---
+title: My Post Title
+description: A short description
+published: true
+published_at: 2024-01-15
+position: 1
+---
+
+# Content here
+
+Your markdown content...
+```
+
+## Attributes
+
+- `slug` - Filename without extension
+- `title` - From frontmatter or titleized slug
+- `description` - From frontmatter
+- `content` - Markdown content
+- `published` - Boolean
+- `published_at` - Date/Time
+- `position` - For ordering
+
+## Methods
+
+### Class Methods
+
+- `all` - Load all records
+- `published` - Published records sorted by `published_at` desc
+- `find(slug)` - Find by slug, raises `RecordNotFound` if not found
+
+### Instance Methods
+
+- `published?` - Is this record published?
+- `to_param` - Returns slug (for URL generation)
+- `to_html` - Renders markdown to HTML
+
+### Categorizable Methods
+
+- `categories` - Array of `MdRecord::Category` objects
+- `category?(category)` - Check if record belongs to category (accepts Category or string)
+- `category_name` - Human-readable category name
+
+## RecordNotFound
+
+`MdRecord::RecordNotFound` is automatically mapped to 404 in Rails (via Railtie).
+
+```ruby
+Post.find("non-existent") # raises MdRecord::RecordNotFound
+# Rails returns 404
+```
+
+## Components
+
+- `MdRecord::Base` - Base class for models
+- `MdRecord::Categorizable` - Concern for categorized models
+- `MdRecord::Category` - Value object for categories
+- `MdRecord::Loader` - Loads files from a directory
+- `MdRecord::CategorizedLoader` - Loads files from category subdirectories
+- `MdRecord::FrontmatterParser` - Parses YAML frontmatter
+- `MdRecord::MarkdownRenderer` - Custom Redcarpet renderer with asset path support
+- `MdRecord::RecordNotFound` - Exception for missing records
+- `MdRecord::Railtie` - Rails integration (auto-loaded)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/md_record/base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module MdRecord
+  class Base
+    include ActiveModel::Model
+
+    attr_accessor :slug, :title, :content, :published,
+                  :published_at, :description, :position
+
+    class << self
+      def md_record_path(path = nil)
+        @md_record_path = path if path
+        @md_record_path || default_path
+      end
+
+      def loader
+        MdRecord::Loader.new(path: resolve_path(md_record_path))
+      end
+
+      def parse(file)
+        parser = MdRecord::FrontmatterParser.new(file).parse!
+
+        new(
+          slug: parser.slug,
+          title: parser.title,
+          content: parser.content,
+          published: parser.published,
+          published_at: parser.frontmatter["published_at"],
+          description: parser.frontmatter["description"],
+          position: parser.frontmatter.fetch("position", 0)
+        )
+      end
+
+      def all
+        loader.load { |file| parse(file) }
+      end
+
+      def published
+        @published ||= all.select(&:published?).sort_by(&:published_at).reverse
+      end
+
+      def find(slug)
+        published.find { |doc| doc.slug == slug } ||
+          raise(RecordNotFound.new(model: name, slug: slug))
+      end
+
+      private
+
+      def default_path
+        "app/views/#{model_name.plural}"
+      end
+
+      def resolve_path(path)
+        if defined?(Rails.root) && Rails.root
+          Rails.root.join(path).to_s
+        else
+          path
+        end
+      end
+    end
+
+    def published?
+      published
+    end
+
+    def to_param
+      slug
+    end
+
+    def to_html
+      options = {
+        autolink: true,
+        tables: true,
+        fenced_code_blocks: true,
+        strikethrough: true,
+        no_intra_emphasis: true
+      }
+
+      renderer = MdRecord::MarkdownRenderer.new(hard_wrap: true)
+      markdown = Redcarpet::Markdown.new(renderer, options)
+      result = markdown.render(content)
+
+      if result.respond_to?(:html_safe)
+        result.html_safe
+      else
+        result
+      end
+    end
+  end
+end

data/lib/md_record/categorizable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module MdRecord
+  module Categorizable
+    extend ActiveSupport::Concern
+
+    included do
+      attr_accessor :category
+    end
+
+    class_methods do
+      def md_record_categories(categories)
+        @md_record_categories = categories
+      end
+
+      def loader
+        MdRecord::CategorizedLoader.new(
+          path: resolve_path(md_record_path),
+          categories: @md_record_categories
+        )
+      end
+
+      def parse(file, category:)
+        super(file).tap { |doc| doc.category = category }
+      end
+
+      def all
+        loader.load { |file, category| parse(file, category: category) }
+      end
+
+      def published
+        @published ||= all.select(&:published?)
+      end
+
+      def categories
+        @md_record_categories.map do |key, config|
+          Category.new(
+            key: key,
+            name: config[:name],
+            position: config[:position]
+          )
+        end.sort_by(&:position)
+      end
+    end
+
+    def category?(other)
+      key = other.is_a?(Category) ? other.key : other
+      category == key
+    end
+
+    def category_name
+      self.class.instance_variable_get(:@md_record_categories).dig(category, :name) || category.to_s.tr("-_", " ").capitalize
+    end
+  end
+end

data/lib/md_record/categorized_loader.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module MdRecord
+  class CategorizedLoader
+    def initialize(path:, categories:)
+      @path = Pathname.new(path).expand_path
+      @categories = categories
+    end
+
+    def load
+      @categories.keys.flat_map do |category|
+        if category_path(category).directory?
+          category_files(category).map { |file| yield file, category }
+        end
+      end
+    end
+
+    private
+
+    def category_files(category)
+      Dir.glob(category_path(category).join("*.md"))
+    end
+
+    def category_path(category)
+      @path.join(category.to_s)
+    end
+  end
+end

data/lib/md_record/category.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module MdRecord
+  class Category
+    attr_reader :key, :name, :position
+
+    def initialize(key:, name:, position:)
+      @key = key
+      @name = name
+      @position = position
+    end
+
+    def to_param
+      key
+    end
+  end
+end

data/lib/md_record/frontmatter_parser.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "date"
+
+module MdRecord
+  class FrontmatterParser
+    attr_reader :file_path, :frontmatter, :markdown_content
+
+    def initialize(file_path)
+      @file_path = file_path
+      @frontmatter = {}
+    end
+
+    def slug
+      File.basename(file_path, ".md")
+    end
+
+    def title
+      frontmatter.fetch("title", slug.titleize)
+    end
+
+    def content
+      markdown_content || raw_content
+    end
+
+    def published
+      frontmatter.fetch("published", false)
+    end
+
+    def parse!
+      parse_frontmatter!
+      self
+    end
+
+    private
+
+    def raw_content
+      @raw_content ||= File.read(file_path)
+    end
+
+    def parse_frontmatter!
+      if raw_content =~ /\A---\s*\n(.*?)\n---\s*\n(.*)\z/m
+        @frontmatter = YAML.safe_load($1, permitted_classes: [Date, Time])
+        @markdown_content = $2
+      end
+    end
+  end
+end

data/lib/md_record/loader.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module MdRecord
+  class Loader
+    def initialize(path:)
+      @path = Pathname.new(path).expand_path
+    end
+
+    def load
+      markdown_files.map { |file| yield file }
+    end
+
+    private
+
+    def markdown_files
+      Dir.glob(@path.join("*.md"))
+    end
+  end
+end

data/lib/md_record/markdown_renderer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module MdRecord
+  class MarkdownRenderer < Redcarpet::Render::HTML
+    def image(src, title, alt_text)
+      if src && !src.start_with?("http://", "https://", "/")
+        src = resolve_asset_path(src)
+      end
+
+      title_attr = title && !title.empty? ? %( title="#{title}") : ""
+      %(<img src="#{src}" alt="#{alt_text}"#{title_attr}>)
+    end
+
+    def block_code(code, language)
+      %(<pre><code>#{ERB::Util.html_escape(code)}</code></pre>)
+    end
+
+    private
+
+    def resolve_asset_path(src)
+      if defined?(ActionController::Base)
+        ActionController::Base.helpers.asset_path(src)
+      else
+        src
+      end
+    end
+  end
+end

data/lib/md_record/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module MdRecord
+  class Railtie < Rails::Railtie
+    initializer "md_record.configure_rescue_responses" do
+      ActionDispatch::ExceptionWrapper.rescue_responses["MdRecord::RecordNotFound"] = :not_found
+    end
+  end
+end

data/lib/md_record/record_not_found.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module MdRecord
+  class RecordNotFound < StandardError
+    attr_reader :model, :slug
+
+    def initialize(message = nil, model: nil, slug: nil)
+      @model = model
+      @slug = slug
+      super(message || default_message)
+    end
+
+    private
+
+    def default_message
+      if model && slug
+        "Couldn't find #{model} with slug '#{slug}'"
+      elsif model
+        "Couldn't find #{model}"
+      else
+        "Record not found"
+      end
+    end
+  end
+end

data/lib/md_record/version.rb

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

data/lib/md_record.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support/concern"
+require "redcarpet"
+require "yaml"
+require "pathname"
+
+require_relative "md_record/version"
+require_relative "md_record/record_not_found"
+require_relative "md_record/frontmatter_parser"
+require_relative "md_record/markdown_renderer"
+require_relative "md_record/loader"
+require_relative "md_record/categorized_loader"
+require_relative "md_record/category"
+require_relative "md_record/base"
+require_relative "md_record/categorizable"
+
+require_relative "md_record/railtie" if defined?(Rails::Railtie)
+
+module MdRecord
+end

data/md_record.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "lib/md_record/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "md_record"
+  spec.version = MdRecord::VERSION
+  spec.authors = ["Benito Serna"]
+  spec.email = ["bhserna@gmail.com"]
+
+  spec.summary = "File-backed models for Rails"
+  spec.description = "ActiveRecord-like interface for markdown files with YAML frontmatter"
+  spec.homepage = "https://github.com/bhserna/md_record"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activemodel", ">= 7.0"
+  spec.add_dependency "activesupport", ">= 7.0"
+  spec.add_dependency "redcarpet", ">= 3.0"
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: md_record
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Benito Serna
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: ActiveRecord-like interface for markdown files with YAML frontmatter
+email:
+- bhserna@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/md_record.rb
+- lib/md_record/base.rb
+- lib/md_record/categorizable.rb
+- lib/md_record/categorized_loader.rb
+- lib/md_record/category.rb
+- lib/md_record/frontmatter_parser.rb
+- lib/md_record/loader.rb
+- lib/md_record/markdown_renderer.rb
+- lib/md_record/railtie.rb
+- lib/md_record/record_not_found.rb
+- lib/md_record/version.rb
+- md_record.gemspec
+homepage: https://github.com/bhserna/md_record
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bhserna/md_record
+  source_code_uri: https://github.com/bhserna/md_record
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: File-backed models for Rails
+test_files: []