filepress 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e04385f62b93b0ae73ed1a5406e9ffabfa0e3b9347a320362426e07daf9f2a1f
-  data.tar.gz: c2ab7c42b0a8d13ad530a406a734aeea8806abf4ac4fb601e0fd376ebd8c611a
+  metadata.gz: 745a5e3486f737ba398c1d8418299aafe2aafdee92593ab4ddc97ee5860db0d7
+  data.tar.gz: f6cf79cf496608719ff2cd65531d9240645f6953b65ecf72c494e41261e84810
 SHA512:
-  metadata.gz: 18c23fdf881720757082d8f16d8789a2c973ffb20350057265c3a59007a4f94d627a20e0116e211984b2456b901c985de8ab12ea4268c17079bd7816101dcf68
-  data.tar.gz: 64d52cc8d248fef1d014f8040891613e39eb823a1998c4156c23d982900fcdd60ef96b6249296b67dffce32b849120c7e7a8b82af04bbb2c67e81896ea3ef4fd
+  metadata.gz: 4c0e44caf392542ea428f53d2db17366028ad5944f6436a87c8cdc728fe09052159c176d7638a7804a8230573392985d7540ab4ca6c91b11e1348fe240e98b6f
+  data.tar.gz: 04f98d47ed32028b8b233abeaf1597d81d6a03959fb1bc235b9face53334627036aa846b5c52551330025c57fc4b4ea5b00fda169be87691cce12b05b8ee8b9b

data/README.md

@@ -1,32 +1,25 @@
 # Filepress
 
-Filepress is a minimal Rails plugin that offers the best of both worlds for content management:
-- Write and version control your content in Markdown (or a similar format)
-- Sync it seamlessly to ActiveRecord models so you can harness the full power of a Rails backend.
+Filepress is a minimal Rails plugin that syncs content from flat files to ActiveRecord models. Write your posts in Markdown, version control them with git, and query them with ActiveRecord.
 
-Ideal for blogs, documentation, or any content-driven Rails app where you want the flexibility of flat files and the structure of a database.
+## Build a blog with Filepress
 
-## Getting Started
-
-1. Install the gem
-
-Add it to your Gemfile:
+### 1. Install the gem
 
 ```ruby
 gem "filepress"
 ```
 
-2. Create a model to represent your content
+### 2. Generate a Post model
 
-Be sure to include a field that can serve as a unique identifier (e.g. `slug`):
+Include a `slug` field to serve as the unique identifier (derived from the filename) and a `body` field for the content:
 
 ```bash
-rails g model Post title:string slug:string body:text
+bin/rails generate model Post title:string slug:string:uniq body:text published:boolean
+bin/rails db:migrate
 ```
 
-3. Enable Filepress for your model
-
-Use the `filepress` method in your model class:
+### 3. Enable Filepress
 
 ```ruby
 class Post < ApplicationRecord
@@ -34,26 +27,100 @@ class Post < ApplicationRecord
 end
 ```
 
-4. Add some content
+### 4. Write a post
 
-Create Markdown files in `app/content/posts`. The filename becomes the slug, and YAML frontmatter maps to your model's attributes:
+Create a Markdown file at `app/content/posts/hello-world.md`. The filename becomes the slug, and YAML frontmatter maps to model attributes:
 
 ```markdown
 ---
-title: My First Post
+title: Hello World
 published: true
 ---
 
-Hello, this is my first post!
+This is my first post!
+```
+
+Filepress syncs your content to the database automatically — on boot, on deploy, and whenever files change in development.
+
+### 5. Add a controller and routes
+
+```ruby
+# config/routes.rb
+resources :posts, only: [:index, :show]
+```
+
+```ruby
+# app/controllers/posts_controller.rb
+class PostsController < ApplicationController
+  def index
+    @posts = Post.all
+  end
+
+  def show
+    @post = Post.find_by!(slug: params[:id])
+  end
+end
+```
+
+Override `to_param` so Rails generates URLs using the slug:
+
+```ruby
+class Post < ApplicationRecord
+  filepress
+
+  def to_param
+    slug
+  end
+end
+```
+
+### 6. Add views
+
+```erb
+<%# app/views/posts/index.html.erb %>
+<% @posts.each do |post| %>
+  <h2><%= link_to post.title, post %></h2>
+<% end %>
+```
+
+```erb
+<%# app/views/posts/show.html.erb %>
+<h1><%= @post.title %></h1>
+<%= @post.body.html_safe %>
+```
+
+### 7. Render Markdown as HTML
+
+Filepress stores the raw file content. To render Markdown to HTML at sync time, add a gem like [Kramdown](https://kramdown.gettalong.org) and a `before_save` callback:
+
+```ruby
+gem "kramdown"
+gem "kramdown-parser-gfm"
 ```
 
-That's it! Filepress syncs your content to the database automatically — on boot, on deploy, and whenever files change in development. No rake tasks, no deploy hooks.
+```ruby
+class Post < ApplicationRecord
+  filepress
+
+  before_save :render_body, if: :body_changed?
+
+  def to_param
+    slug
+  end
+
+  private
+
+  def render_body
+    self.body = Kramdown::Document.new(body, input: "GFM").to_html
+  end
+end
+```
 
-You're free to query your content via ActiveRecord like any other model. Filepress doesn't dictate how you render the body — use a Markdown parser like Kramdown, Redcarpet, or similar.
+The body is converted once on sync, not on every request. Any Markdown library works — Redcarpet, CommonMarker, etc.
 
 ## How it works
 
-Filepress reads your content files, extracts YAML frontmatter, and uses the values to populate or update model attributes. The rest of the file becomes the value of the body attribute (or another field, if configured).
+Filepress reads your content files, extracts YAML frontmatter, and uses the values to populate or update model attributes. The rest of the file becomes the body.
 
 - Syncs are wrapped in a transaction — if any file fails, nothing changes
 - Unknown frontmatter keys (that don't match a column) are silently ignored
@@ -61,54 +128,36 @@ Filepress reads your content files, extracts YAML frontmatter, and uses the valu
 
 ## Configuration
 
-You can customize how Filepress behaves by passing options to `filepress`:
+Customise Filepress by passing options to `filepress`:
 
-### `from:` — Set a custom content directory
+### `from:` — Custom content directory
 
 ```ruby
-class Post < ApplicationRecord
-  filepress from: "app/my_custom_content_folder"
-end
+filepress from: "app/my_custom_content_folder"
 ```
 
-### `extensions:` — Use filetypes besides Markdown
+### `extensions:` — File types besides Markdown
 
 ```ruby
-class Post < ApplicationRecord
-  filepress extensions: ["html", "txt"]
-end
+filepress extensions: ["html", "txt"]
 ```
 
-### `key:` — Use a unique identifier other than `slug`
+### `key:` — Unique identifier other than `slug`
 
 ```ruby
-class Post < ApplicationRecord
-  filepress key: :name
-end
+filepress key: :name
 ```
 
-### `body:` — Set which attribute stores the main content
+### `body:` — Attribute that stores the main content
 
 ```ruby
-class Post < ApplicationRecord
-  filepress body: :content
-end
+filepress body: :content
 ```
 
-### `destroy_stale:` — Prevent deletion of records when files are removed
+### `destroy_stale:` — Keep records when files are removed
 
-By default, Filepress deletes records when the corresponding file is removed. Disable this behaviour with:
+By default, Filepress deletes records when the corresponding file is removed. Disable this with:
 
 ```ruby
-class Post < ApplicationRecord
-  filepress destroy_stale: false
-end
+filepress destroy_stale: false
 ```
-
-## Why Filepress?
-
-Filepress is for you if:
-
-- You prefer writing content in files
-- You want the convenience of version control for content
-- And you still want powerful querying, associations, validations and all the other Rails goodness

data/lib/filepress/engine.rb

@@ -7,16 +7,7 @@ module Filepress
     end
 
     initializer "filepress.file_watcher" do |app|
-      content_path = app.root.join("app", "content")
-
-      app.config.after_initialize do
-        if content_path.exist?
-          extensions = Filepress.watched_extensions
-          app.reloaders << app.config.file_watcher.new([], { content_path.to_s => extensions }) do
-            Filepress.sync
-          end
-        end
-      end
+      Filepress.app = app
     end
   end
 end

data/lib/filepress/version.rb

@@ -1,3 +1,3 @@
 module Filepress
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/lib/filepress.rb

@@ -6,6 +6,8 @@ require "filepress/sync"
 
 module Filepress
   class << self
+    attr_accessor :app
+
     def registry
       @registry ||= {}
     end
@@ -14,6 +16,8 @@ module Filepress
       config = options.merge(model_class: model_class)
       registry[model_class.name] = config
 
+      watch(config[:from], config[:extensions])
+
       trace = TracePoint.new(:end) do |tp|
         if tp.self == model_class
           trace.disable
@@ -23,9 +27,10 @@ module Filepress
       trace.enable
     end
 
-    def watched_extensions
-      exts = registry.values.flat_map { |config| config[:extensions] }.uniq
-      exts.empty? ? ["md"] : exts
+    def watch(dir, extensions)
+      return unless watched.add?(dir)
+
+      app.reloaders << app.config.file_watcher.new([], { dir => extensions }) { sync }
     end
 
     def sync
@@ -33,5 +38,11 @@ module Filepress
         Sync.new(config).perform
       end
     end
+
+    private
+
+    def watched
+      @watched ||= Set.new
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: filepress
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Carl Dawson