flora 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84a83e09611588abf3ede492aa734a168aa8d611eb7b33e503243df4bbe13d89
-  data.tar.gz: 5aeb14cbae18ad40c725c8fcf88c814daf150a48491ff3594708b843cb80f200
+  metadata.gz: c1025da710c673e347a8e739d8d378b986386040ec9bdbe97e92ea5639d4a792
+  data.tar.gz: 5aa256a0a55e2b4d345af8e63e6cb19f3627f723d24706091505f54d58bdafb0
 SHA512:
-  metadata.gz: 14084b4863fe3223d99ac2da8f3b1281ad6649f23501f150a13b73add8b451112a8f15607734b2750dd872214e40f579c51e46bf7aff2ba22f91a11e1db24c77
-  data.tar.gz: 155da839cd37104784aea6da12760c8d342b6d25c8b4eda9f6dfb2a5d192a76f9e29c0dd4f5c8f6470ee9ba3eb8bdccd9f16189a3f20e5a9bf74ca90aa5649a2
+  metadata.gz: b261bf5ab0e0d8c5203de5950792d5f272a7a7fb7da9055ea06a543018387534d7964f6d5dfc4550ed0cbcb6e529240176466c66f720d62445adfd09d87fb168
+  data.tar.gz: e275dad3c3090f5aa53a5df129ea0fc3f2a3921ea3c4a35bf335764ae34c902cb3a07f4987dd8f8163f7f02654ad94c922d521a8f515c268293fbd2827afcc38

data/README.md

@@ -25,3 +25,24 @@ end
 ```
 
 Install everything with `bundle install`, and then run `bundle exec flora serve` and open up http://localhost:3000!
+
+
+## The Flora way
+
+Flora is an opinionated static site generator, and you should generally follow those opinions when making a site in Flora.
+
+### Static only
+
+Flora will only ever generate static websites. If you need dynamic content, look elsewhere! (I'd suggest Rails!)
+
+### A Ruby-first approach
+
+Flora prefers Ruby and you should too. Configuration and HTML-generation code is in Ruby. Not everything makes sense as Ruby (you should write content-heavy pages in Markdown, for example), but it's the default option for solving problems in a Flora project.
+
+### File-based routing
+
+Flora doesn't have a routes file. Instead, requests are routed by convention based on your file's path. While this is the default, some things--like the Redirector plugin--can subvert this opinion when needed.
+
+### Unopinionated but pluggable
+
+Flora is a generic static site generator and doesn't favor any particular use case. Making Flora do specific things better is achieved using plugins. Flora ships with a few plugins for common use cases like blogs and handling static files.

data/lib/flora/config.rb

@@ -1,3 +1,4 @@
+# This is the user-visible configuration class. It lives in ROOT/_config.rb.
 class Flora::Config
 
   def initialize(file, flora)

data/lib/flora/factory.rb

@@ -1,20 +1,20 @@
+# Factories assemble Projects into Websites.
 class Flora::Factory
 
-  def initialize(blueprint, config)
-    @blueprint = blueprint
+  def initialize(project, config)
+    @project = project
     @config = config
   end
 
 
-  # Assemble a blueprint and put it into a directory.
+  # Assemble the Project into a Website, and put it into out_dir.
   def assemble(out_dir)
     out_dir.mkdir unless out_dir.exist?
 
-    @blueprint.each_page do |page|
-      relative_path = page.file.relative_path_from(@blueprint.dir)
-      out_filename = out_dir.join(relative_path).sub_ext('.html')
+    @project.blueprints.each do |blueprint|
+      out_filename = out_dir.join(blueprint.page_name)
       out_filename.dirname.mkdir unless out_filename.dirname.exist?
-      out_filename.write(page.render)
+      out_filename.write(blueprint.render)
     end
   end
 

data/lib/flora/plugins/blog.rb

@@ -1,6 +1,6 @@
 module Flora::Plugins::Blog
 
-  module BlueprintMethods
+  module ProjectMethods
 
     def posts
       @dir.glob('posts/**').map { Post.new(it, @dir) }
@@ -9,10 +9,10 @@ module Flora::Plugins::Blog
   end
 
 
-  module PageMethods
+  module BlueprintMethods
 
     def posts
-      @blueprint.posts
+      @project.posts
     end
 
   end

data/lib/flora/plugins/static_files.rb

@@ -1,33 +1,19 @@
 module Flora::Plugins::StaticFiles
 
-  class Copier
+  class StaticFile < Flora::Project::Blueprint
 
-    def initialize(dir)
-      @dir = dir
+    def self.recognize(file, config)
+      file.fnmatch?(config.static_files_dir + '/**')
     end
 
 
-    def copy_to(out)
-      @dir.find do |public_file|
-        next if public_file.directory?
-
-        out_filename = out.join(Pathname.new(public_file).relative_path_from(@dir))
-        out_filename.dirname.mkdir unless out_filename.dirname.exist?
-        out_filename.write(File.read(public_file))
-      end
+    def render
+      @file.read
     end
 
-  end
-
-
-  module FactoryMethods
-
-    def assemble(out_dir)
-      super
 
-      base = @config.static_files_dir || 'public'
-      copier = Copier.new(@blueprint.dir.join(base))
-      copier.copy_to(out_dir.join(base))
+    def page_name
+      @file.relative_path_from(@project.dir).to_s
     end
 
   end

data/lib/flora/{blueprint/page → project/blueprint}/html.rb

@@ -1,4 +1,4 @@
-module Flora::Blueprint::Page::Html
+module Flora::Project::Blueprint::Html
 
   TAGS = %i[
     a abbr address area article aside audio

data/lib/flora/{blueprint/page/markdown_page.rb → project/blueprint/markdown.rb}

@@ -1,4 +1,12 @@
-class Flora::Blueprint::Page::MarkdownPage < Flora::Blueprint::Page
+class Flora::Project::Blueprint::Markdown < Flora::Project::Blueprint
+
+  include Flora::Project::Blueprint::Nestable
+
+
+  def self.recognize(file, config)
+    file.extname == '.md'
+  end
+
 
   private
 

data/lib/flora/project/blueprint/nestable.rb

@@ -0,0 +1,46 @@
+# A Blueprint that includes Nestable is something that can best nested into
+# Flora's HTML DSL layouts.
+module Flora::Project::Blueprint::Nestable
+
+  def render
+    # The Html DSL uses a global variable internally that needs to be reset every time.
+    $flora_added = []
+
+    layouts = find_layouts
+    tree = render_internal(layouts, layouts.size) do
+      render_tree
+    end
+
+    Flora::Project::Blueprint::Html.to_html(tree)
+  end
+
+
+  private
+
+    def find_layouts
+      layouts = []
+
+      @file.ascend do |dir|
+        maybe_layout = dir.join('_layout.rb')
+        layouts << maybe_layout if maybe_layout.exist?
+      end
+
+      layouts
+    end
+
+
+    def render_internal(layouts, i, &block)
+      if i <= 0
+        return block.call
+      end
+
+      cont = -> { render_internal(layouts, i-1, &block) }
+      eval_with_block(layouts[i-1].read, &cont)
+    end
+
+
+    def eval_with_block(str, &block)
+      eval(str)
+    end
+
+end

data/lib/flora/project/blueprint/ruby_html.rb

@@ -0,0 +1,17 @@
+class Flora::Project::Blueprint::RubyHtml < Flora::Project::Blueprint
+
+  include Flora::Project::Blueprint::Nestable
+
+
+  def self.recognize(file, config)
+    file.extname == '.rb'
+  end
+
+
+  private
+
+    def render_tree
+      instance_eval(@file.read)
+    end
+
+end

data/lib/flora/project/blueprint.rb

@@ -0,0 +1,44 @@
+# A Blueprint is something can be rendered into a File. Sometimes a Blueprint
+# looks very different than the File it renders into, but other times (like for
+# static files), nothing changes.
+class Flora::Project::Blueprint
+
+  attr_reader(:file)
+
+
+  # :nodoc:
+  def self.types
+    ObjectSpace.each_object(Class).select { it < self }
+  end
+
+
+  # Returns true if this Blueprint is appropriate for the file.
+  #
+  # TODO: should this be an instance method somewhere instead?
+  def self.recognize(file, config)
+    # Override in subclasses!
+
+    false
+  end
+
+
+  def initialize(file, project)
+    @file = file
+    @project = project
+  end
+
+
+  # The name of the Page this Blueprint makes. By default this is just the
+  # filename, but .html, but subclasses can override this.
+  def page_name
+    @file.relative_path_from(@project.dir).sub_ext('.html').to_s
+  end
+
+
+  # Render a Blueprint into a Page for a Website. This is the String contents
+  # of whatever the Page in the final Website looks like.
+  def render
+    # Override in subclasses!
+  end
+
+end

data/lib/flora/project.rb

@@ -0,0 +1,61 @@
+# A Project is a template for a website made in Flora.
+#
+# Projects live in a directory and have:
+#  1) Blueprints, files that can be transformed into another file type (like HTML).
+#  2) Supporting Code, Ruby code that lives in lib/ that Blueprints can depend on.
+class Flora::Project
+
+  attr_reader(:dir, :blueprints)
+
+  IGNORES = ['.git/*', 'lib/**', '**_*.rb']
+
+
+  def initialize(dir, config)
+    @dir = dir
+    @config = config
+
+    @blueprints = find_blueprints
+
+    @loader = Zeitwerk::Loader.new
+    if has_supporting_code?
+      @loader.push_dir(@dir.join('lib').to_s)
+    end
+    @loader.enable_reloading
+    @loader.setup
+    @loader.eager_load
+  end
+
+
+  def reload
+    @loader.reload
+    @blueprints = find_blueprints
+  end
+
+
+  private
+
+    def find_blueprints
+      blueprints = []
+
+      @dir.find do |file|
+        next if IGNORES.any? { file.fnmatch((@dir / it).to_s) }
+        next if file.directory?
+
+        klass = Blueprint.types.find {
+          it.recognize(file.relative_path_from(@dir), @config)
+        }
+
+        next unless klass
+
+        blueprints << klass.new(file, self)
+      end
+
+      blueprints
+    end
+
+
+    def has_supporting_code?
+      @dir.join('lib').exist?
+    end
+
+end

data/lib/flora/version.rb

@@ -1,3 +1,3 @@
 class Flora
-  VERSION = '0.6.2'
+  VERSION = '0.7.0'
 end

data/lib/flora.rb

@@ -14,21 +14,18 @@ class Flora
     # instance_eval isn't enough because they'll be missing in lib/ code.
     #
     # TODO: is there a less disruptive way to do this?
-    Kernel.prepend(Flora::Blueprint::Page::Html)
+    Kernel.prepend(Flora::Project::Blueprint::Html)
 
     # The classes that are pluggable get their own instances to avoid conflicting
     # with other instances of Flora in the same process. This is mostly for the
     # unit tests. Maybe one day we can use Ruby::Box or something here instead.
     @config_class = Class.new(Config)
-    @blueprint_class = Class.new(Blueprint)
+    @project_class = Class.new(Project)
     @factory_class = Class.new(Factory)
 
-    # Page plugins get mixed in directly to the page instances by Blueprint.
-    @page_modules = []
-
     @config = @config_class.new(dir.join('_config.rb'), self)
-    @blueprint = @blueprint_class.new(dir, @config, @page_modules)
-    @factory = @factory_class.new(@blueprint, @config)
+    @project = @project_class.new(dir, @config)
+    @factory = @factory_class.new(@project, @config)
   end
 
 
@@ -37,18 +34,24 @@ class Flora
   end
 
 
-  def reload_blueprint
-    @blueprint.reload
+  def reload_project
+    @project.reload
   end
 
 
   # TODO: it would be nice if this wasn't exposed here. It's just for Config#plugin.
   def load_plugin(mod)
     @config_class.include(mod::Config) if defined?(mod::Config)
-    @blueprint_class.include(mod::BlueprintMethods) if defined?(mod::BlueprintMethods)
+    @project_class.include(mod::ProjectMethods) if defined?(mod::ProjectMethods)
     @factory_class.include(mod::FactoryMethods) if defined?(mod::FactoryMethods)
 
-    @page_modules << mod::PageMethods if defined?(mod::PageMethods)
+    # TODO: make this a little more resilient (like the other classes).
+    Flora::Project::Blueprint.include(mod::BlueprintMethods) if defined?(mod::BlueprintMethods)
   end
 
 end
+
+# Built-in Blueprints need to be explicitly loaded or else they won't show up
+# in Blueprint.types.
+loader.load_file("#{__dir__}/flora/project/blueprint/ruby_html.rb")
+loader.load_file("#{__dir__}/flora/project/blueprint/markdown.rb")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flora
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Nick Vladimiroff
@@ -106,12 +106,6 @@ files:
 - exe/flora
 - lib/flora.rb
 - lib/flora/app.rb
-- lib/flora/blueprint.rb
-- lib/flora/blueprint/page.rb
-- lib/flora/blueprint/page/html.rb
-- lib/flora/blueprint/page/layout.rb
-- lib/flora/blueprint/page/markdown_page.rb
-- lib/flora/blueprint/page/ruby_page.rb
 - lib/flora/cli.rb
 - lib/flora/config.rb
 - lib/flora/factory.rb
@@ -119,6 +113,12 @@ files:
 - lib/flora/plugins/blog/post.rb
 - lib/flora/plugins/redirector.rb
 - lib/flora/plugins/static_files.rb
+- lib/flora/project.rb
+- lib/flora/project/blueprint.rb
+- lib/flora/project/blueprint/html.rb
+- lib/flora/project/blueprint/markdown.rb
+- lib/flora/project/blueprint/nestable.rb
+- lib/flora/project/blueprint/ruby_html.rb
 - lib/flora/version.rb
 - tmp/.keep
 homepage: https://code.kat5.dev/nick/flora
@@ -141,7 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.0.dev
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A static site generator.
 test_files: []

data/lib/flora/blueprint/page/layout.rb

@@ -1,29 +0,0 @@
-class Flora::Blueprint::Page::Layout
-
-  def initialize(layouts)
-    @layouts = layouts
-  end
-
-
-  def render(&block)
-    render_internal(@layouts.size - 1, &block)
-  end
-
-
-  private
-
-    def render_internal(i, &block)
-      if i <= 0
-        return block.call
-      end
-
-      cont = -> { render_internal(i-1, &block) }
-      eval_with_block(@layouts[i].read, &cont)
-    end
-
-
-    def eval_with_block(str, &block)
-      eval(str)
-    end
-
-end

data/lib/flora/blueprint/page/ruby_page.rb

@@ -1,9 +0,0 @@
-class Flora::Blueprint::Page::RubyPage < Flora::Blueprint::Page
-
-  private
-
-    def render_tree
-      instance_eval(@file.read)
-    end
-
-end

data/lib/flora/blueprint/page.rb

@@ -1,52 +0,0 @@
-# A page is something can be turned into an HTML file.
-class Flora::Blueprint::Page
-
-  attr_reader(:file)
-
-
-  def self.for(file)
-    # TODO: make this a little more extensible so plugins can implement new page
-    # types.
-    case file.extname
-    when '.rb'
-      RubyPage
-    when '.md'
-      MarkdownPage
-    end
-  end
-
-
-  def initialize(file, blueprint)
-    @file = file
-    @blueprint = blueprint
-
-    @layout = find_layouts
-  end
-
-
-  def render
-    # The Html DSL uses a global variable internally that needs to be reset every time.
-    $flora_added = []
-
-    tree = @layout.render do
-      render_tree
-    end
-
-    Html.to_html(tree)
-  end
-
-
-  private
-
-    def find_layouts
-      layouts = []
-
-      @file.ascend do |dir|
-        maybe_layout = dir.join('_layout.rb')
-        layouts << maybe_layout if maybe_layout.exist?
-      end
-
-      Layout.new(layouts)
-    end
-
-end

data/lib/flora/blueprint.rb

@@ -1,64 +0,0 @@
-class Flora::Blueprint
-
-  attr_reader(:dir)
-
-  IGNORES = ['.git/*', 'lib/*', '**_layout.rb', '_config.rb']
-
-
-  def initialize(dir, config, page_modules)
-    @dir = dir
-    @config = config
-    @page_modules = page_modules
-
-    @pages = load_pages
-
-    @loader = Zeitwerk::Loader.new
-    if has_supporting_code?
-      @loader.push_dir(@dir.join('lib').to_s)
-    end
-    @loader.enable_reloading
-    @loader.setup
-  end
-
-
-  def each_page(&block)
-    @pages.each(&block)
-  end
-
-
-  def reload
-    @loader.reload
-    @pages = load_pages
-  end
-
-
-  private
-
-    def load_pages
-      pages = []
-
-      @dir.find do |file|
-        next if IGNORES.any? { file.fnmatch((@dir / it).to_s) }
-        next if file.directory?
-        next unless supported_file_type?(file)
-
-        page = Page.for(file).new(file, self)
-        @page_modules.each { |mod| page.extend(mod) }
-        pages << page
-      end
-
-      pages
-    end
-
-
-    # TODO: this is duplicating logic from Page::for.
-    def supported_file_type?(file)
-      file.extname == '.rb' || file.extname == '.md'
-    end
-
-
-    def has_supporting_code?
-      @dir.join('lib').exist?
-    end
-
-end