markdown_record 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5cf70bc7bfe4be124645f86a8182c31f2026a5c8c1736b79852e1ca17981b835
+  data.tar.gz: 7ff16d507f7fec68fcf09ecebfa7012cf5c8e700f4ebe74d73e163b83a02cea4
+SHA512:
+  metadata.gz: 4f28579beda2d8605428020e04db510d9df937513560e5c1c8fb0768767e43573f785584316c7c5748516d9d4881ce0b32db1430a8f658906486af634daf110f
+  data.tar.gz: 5882b40b524c9a121aac21ef9adadc32868e1138c92adc47e8dfbbadc84e71e130526831f3e0a78148f9a04298cdecbae8ac068334542ea788e38d3a0fe16676

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2023 Bryant Morrill
+
+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,225 @@
+# MarkdownRecord
+
+Welcome to MarkdownRecord. This project is still in BETA stage, and as such is subject to rapid change. There are many things that still need improving, so bear that in mind. That said, please feel free to test this project out and provide feedback in the form of GitHub issues! Thank you.
+
+MarkdownRecord is a Rails engine that allows you to write markdown with embedded json like this:
+
+```md
+<!--model
+  { 
+    "type": "markdown_record/demo/section", 
+    "id":   3, 
+    "name": "Content DSL"
+  } 
+-->
+
+# Content DSL
+
+This section describes the Content DSL MarkdownRecord provides to allow you to define application data right alongside your written markdown content.
+
+While writing documentation in your markdown source files, you can define json data using HTML comments which will then be made available to you within your application code...
+
+```
+
+And then interact with your data in your application code like this:
+
+```ruby
+MarkdownRecord::Demo::Section.find(3)
+ => #<MarkdownRecord::Demo::Section filename: "content_dsl", id: 3, name: "Content DSL", subdirectory: "content", type: "markdown_record/demo/section"> 
+```
+
+And render your markdown content as HTML (with full ERB support) like this:
+
+```html
+<h1>Content DSL</h1>
+
+<p>This section describes the Content DSL MarkdownRecord provides to allow you to define application data right alongside your written markdown content.</p>
+
+<p>While writing documentation in your markdown source files, you can define json data using HTML comments which will then be made available to you within your application code...</p>
+```
+
+Or render your markdown content as JSON like this:
+
+```json
+{"markdown_record/demo/section":[{"type":"markdown_record/demo/section","id":3,"name":"Content DSL","subdirectory":"content","filename":"content_dsl"}]}
+```
+
+## All without creating a single controller, writing a single migration, creating a single view, or defining a single route.
+
+In other words, MarkdownRecord allows you to write your website's content and define static data at the same time, in the same markdown source file, and have it immediately available to render from your application. By embedding your static data right inside your markdown, or rather extracting your data from your content, you can cut out the hassle of writing database migrations and building forms just to store data that doesn't need to be updated by end users. This approach also helps to keep your application maintainable and consistent, as there will be less code (always a good thing) and only one source of truth for both your written copy and its associated data.
+
+The MarkdownRecord engine is packed with super useful features, such as content fragments which let you interact with your source files from within your application code, a powerful (and soon to be extensible) markdown Content DSL that lets you extract data out of your written content and interact with it in an object oriented way, and view helpers to make navigating between your rendered HTML content easy.
+
+---
+
+## Why use MarkdownRecord?
+
+MarkdownRecord is a solution for when you need to render written content in your web application, but also need object oriented and relational representations of your written content and the concepts it describes. This is a fairly narrow use case, but there are a few obvious situations where this could come in handy, such as:
+
+- API documentation that is queryable, such that a client could query for available endpoints, required and optional parameters, etc.
+- A website containing a blog or other static written copy where you want to attach meta data to it such as topic, keywords, etc.
+- Hosting the rules for a table top game alongside a character or army building feature which needs to know what options are defined in the rules.
+- Any situation where you have written copy and you want to represent the relationships between pieces of it or the concepts it describes in an your application code.
+
+MarkdownRecord could be described as a *server side content management system*, as opposed to client side systems such as WordPress and other common blogging platforms, where the writing and editing are done in a browser. With MarkdownRecord you can write content locally without having to worry about converting it to HTML, storing it in a database or integrating a text editor into your web application. It gives you an alternative and way to deal with data with very few compromises.
+
+## Why not use MarkdownRecord?
+
+MarkdownRecord should not be used if the code repository the host application lives in cannot be pushed to whenever content changes (unless there is some work around in place to fetch updated content and render it automatically). Without additional automation in place, you must run a command to have the engine pre-render your content locally, then push the results to wherever your application is hosted. As such, content that requires creating or editing from the client side is not something this engine should be used for.
+
+---
+# Usage
+
+## Installation
+
+This section explains how to install MarkdownRecord into a host application.
+
+First, add this line to your application's Gemfile:
+
+```ruby
+gem "markdown_record"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Then, from the root directory of your application run:
+
+```bash
+$ rails g markdown_record --demo
+```
+
+*Note: if you are already familiar with MarkdownRecord and don't want to install the demo content, you can omit the --demo argument.*
+
+The above command will install the engine, resulting in the following output and changes to your application:
+
+```bash
+      create  markdown_record/content
+      create  markdown_record/layouts
+      create  markdown_record/rendered
+       exist  markdown_record/content
+      create  markdown_record/content/controller_helpers.md.erb
+      create  markdown_record/content/configuration.md.erb
+      create  markdown_record/content/sandbox/foo.md
+      create  markdown_record/content/home.md.erb
+      create  markdown_record/content/installation.md.erb
+      create  markdown_record/content/rendering_basics.md.erb
+      create  markdown_record/content/content_dsl.md.erb
+      create  markdown_record/content/routes.md.erb
+      create  markdown_record/content/model_basics.md.erb
+      create  markdown_record/content/content_frags.md.erb
+      create  markdown_record/content/erb_syntax_and_view_helpers.md.erb
+      create  markdown_record/content/custom_models_and_associations.md.erb
+       exist  markdown_record/layouts
+      create  markdown_record/layouts/_concatenated_layout.html.erb
+      create  markdown_record/layouts/_custom_layout.html.erb
+      create  markdown_record/layouts/_file_layout.html.erb
+      create  markdown_record/layouts/_global_layout.html.erb
+       exist  app/assets/images
+      create  app/assets/images/ruby-logo.png
+      create  config/initializers/markdown_record.rb
+      create  Thorfile
+      create  lib/tasks/render_content.thor
+        gsub  config/routes.rb
+```
+
+The files and folders inside `markdown_record/content` are for demo purposes only, and can be deleted once you are ready to create your own content.
+
+By default, MarkdownRecord will look in the `markdown_record/content` directory for all your content, and all rendered content will be saved to the `markdown_record/rendered` directory.
+
+The engine will be mounted in `config/routes.rb` under the `mdr` path by default.
+
+An initializer will be created for you, where you will be able to configure the engine to use different directories and change other default settings. A later section of this guide will provide more details on configuration options.
+
+A `Thorfile` and some thor tasks will also be added to your application. These tasks are used to render your content to HTML and JSON.
+
+The final step in the installation process is to render the demo content that was installed in `markdown_record/content`. To do so, run this Thor task in your application's root directory:
+
+```bash
+thor render_content:all -s
+```
+
+You should see the following output:
+
+```bash
+---------------------------------------------------------------
+rendering html and json content with options {:concat=>true, :deep=>true, :save=>true, :layout=>"_concatenated_layout.html.erb", :render_content_fragment_json=>true} ...
+---------------------------------------------------------------
+rendered: /markdown_record/rendered/content_fragments.json
+rendered: /markdown_record/rendered/content.json
+rendered: /markdown_record/rendered/content/custom_models_and_associations_fragments.json
+rendered: /markdown_record/rendered/content/custom_models_and_associations.json
+rendered: /markdown_record/rendered/content/erb_syntax_and_view_helpers_fragments.json
+rendered: /markdown_record/rendered/content/erb_syntax_and_view_helpers.json
+rendered: /markdown_record/rendered/content/content_frags_fragments.json
+rendered: /markdown_record/rendered/content/content_frags.json
+rendered: /markdown_record/rendered/content/model_basics_fragments.json
+rendered: /markdown_record/rendered/content/model_basics.json
+rendered: /markdown_record/rendered/content/routes_fragments.json
+rendered: /markdown_record/rendered/content/routes.json
+rendered: /markdown_record/rendered/content/content_dsl_fragments.json
+rendered: /markdown_record/rendered/content/content_dsl.json
+rendered: /markdown_record/rendered/content/rendering_basics_fragments.json
+rendered: /markdown_record/rendered/content/rendering_basics.json
+rendered: /markdown_record/rendered/content/installation_fragments.json
+rendered: /markdown_record/rendered/content/installation.json
+rendered: /markdown_record/rendered/content/home_fragments.json
+rendered: /markdown_record/rendered/content/home.json
+rendered: /markdown_record/rendered/content/sandbox_fragments.json
+rendered: /markdown_record/rendered/content/sandbox.json
+rendered: /markdown_record/rendered/content/sandbox/foo_fragments.json
+rendered: /markdown_record/rendered/content/sandbox/foo.json
+rendered: /markdown_record/rendered/content/configuration_fragments.json
+rendered: /markdown_record/rendered/content/configuration.json
+rendered: /markdown_record/rendered/content/controller_helpers_fragments.json
+rendered: /markdown_record/rendered/content/controller_helpers.json
+rendered: /markdown_record/rendered/content.html
+rendered: /markdown_record/rendered/content/custom_models_and_associations.html
+rendered: /markdown_record/rendered/content/erb_syntax_and_view_helpers.html
+rendered: /markdown_record/rendered/content/content_frags.html
+rendered: /markdown_record/rendered/content/model_basics.html
+rendered: /markdown_record/rendered/content/routes.html
+rendered: /markdown_record/rendered/content/content_dsl.html
+rendered: /markdown_record/rendered/content/rendering_basics.html
+rendered: /markdown_record/rendered/content/installation.html
+rendered: /markdown_record/rendered/content/home.html
+rendered: /markdown_record/rendered/content/sandbox.html
+rendered: /markdown_record/rendered/content/sandbox/foo.html
+rendered: /markdown_record/rendered/content/configuration.html
+rendered: /markdown_record/rendered/content/controller_helpers.html
+---------------------------------------------------------------
+42 files rendered.
+42 files saved.
+```
+
+Congratulations! You have installed MarkdownRecord. If you are not viewing this from the host application already, go ahead and start your Rails server and navigate to http://localhost:3000/mdr/content/home to continue following this guide.
+
+## Contributing
+
+Contributions to this project are welcome. Please simply fork the project and open MRs into the main repo if you have something you would like to add or fix. Opening issues for any bugs or improvements you want to be considered is also appreciated.
+
+While working within this code base, use `rake spec` to run tests. You can pass `SPEC=<path to spec file>` to run a specific spec file, and you make append `:<line number>` to run a specific example.
+
+Things that need doing:
+
+- Backfill pending tests
+- Backfill missing tests
+- Reorganize the `lib` folder to not be such a mess
+- Write RDoc docs throughout
+
+To test a local version of this gem in a local app, simply add the `path` parameter in your gemfile like so:
+
+```
+ gem "markdown_record", path: "../markdown_record"
+```
+
+## Roadmap
+
+- Make the Content DSL extensible
+- Add support for raw JSON files as source content
+
+## 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,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/assets/config/markdown_cms_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/markdown_record .css

data/app/assets/stylesheets/markdown_cms/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/markdown_record/application_controller.rb

@@ -0,0 +1,11 @@
+module MarkdownRecord
+  class ApplicationController < ActionController::Base
+    include ::MarkdownRecord::ControllerHelpers
+
+    before_action :render_not_found
+
+    def render_not_found
+      head :not_found unless content_fragment
+    end
+  end
+end

data/app/controllers/markdown_record/content_controller.rb

@@ -0,0 +1,19 @@
+module MarkdownRecord
+  class ContentController < ApplicationController
+    def show
+      respond_to do |format|
+        format.html do |html|
+          render_html
+        end
+        format.json { render_json }
+      end
+    end
+
+    def download
+      respond_to do |format|
+        format.html { download_html }
+        format.json { download_json }
+      end
+    end
+  end
+end

data/app/controllers/markdown_record/html_controller.rb

@@ -0,0 +1,11 @@
+module MarkdownRecord
+  class HtmlController < ApplicationController
+    def show
+      render_html
+    end
+
+    def download
+      download_html
+    end
+  end
+end

data/app/controllers/markdown_record/json_controller.rb

@@ -0,0 +1,11 @@
+module MarkdownRecord
+  class JsonController < ApplicationController
+    def show
+      render_json
+    end
+
+    def download
+      download_json
+    end
+  end
+end

data/app/helpers/markdown_record/application_helper.rb

@@ -0,0 +1,4 @@
+module MarkdownRecord
+  module ApplicationHelper
+  end
+end

data/app/helpers/markdown_record/controller_helpers.rb

@@ -0,0 +1,39 @@
+module MarkdownRecord
+  module ControllerHelpers
+    def render_html(fragment = content_fragment, layout = MarkdownRecord.config.public_layout)
+      if fragment.html_exists?
+        render file: fragment.html_path, layout: layout
+      else
+        head :not_found
+      end
+    end
+
+    def render_json(fragment = content_fragment)
+      if fragment.json_exists?
+        render file: fragment.json_path, layout: nil
+      else
+        head :not_found
+      end
+    end
+
+    def download_html(fragment = content_fragment, layout = MarkdownRecord.config.public_layout)
+      if fragment.html_exists?
+        send_file fragment.html_path, layout: layout
+      else
+        head :not_found
+      end
+    end
+
+    def download_json(fragment = content_fragment)
+      if fragment.json_exists?
+        send_file fragment.json_path, layout: nil
+      else
+        head :not_found
+      end
+    end
+
+    def content_fragment(content_path = params[:content_path])
+      ::MarkdownRecord::ContentFragment.find(content_path)
+    end
+  end
+end

data/app/helpers/markdown_record/view_helpers.rb

@@ -0,0 +1,84 @@
+module MarkdownRecord
+  module ViewHelpers
+    def link_to_markdown_record(model, name = nil, html_options = nil, &block)
+      return nil if model.nil?
+
+      path = path_to_markdown_record(model, "")
+      name ||= model.name if model.respond_to?(:name)
+
+      block_given? ? link_to(path, html_options, nil, &block) : link_to(name, path, html_options, &block)
+    end
+
+    def link_to_markdown_record_html(model, name = nil, html_options = nil, &block)
+      return nil if model.nil?
+
+      path = path_to_markdown_record_html(model)
+      name ||= model.name if model.respond_to?(:name)
+
+      block_given? ? link_to(path, html_options, nil, &block) : link_to(name, path, html_options, &block)
+    end
+
+    def link_to_download_markdown_record_html(model, name = nil, html_options = nil, &block)
+      return nil if model.nil?
+
+      path = path_to_markdown_record_html(model, true)
+      name ||= model.name if model.respond_to?(:name)
+
+      block_given? ? link_to("/#{path}", html_options, nil, &block) : link_to(name, path, html_options, &block)
+    end
+
+    def path_to_markdown_record_html(model, download = false)
+      path_to_markdown_record(model, "html", download)
+    end
+
+    def url_for_markdown_record_html(model, download = false)
+      path = path_to_markdown_record_html(model, download)
+
+      "#{root_url}/#{path}"
+    end
+
+    def link_to_markdown_record_json(model, name = nil, html_options = nil, &block)
+      return nil if model.nil?
+
+      path = path_to_markdown_record_json(model)
+      name ||= model.name if model.respond_to?(:name)
+
+      block_given? ? link_to(path, html_options, nil, &block) : link_to(name, path, html_options, &block)
+    end
+
+    def link_to_download_markdown_record_json(model, name = nil, html_options = nil, &block)
+      return nil if model.nil?
+      
+      path = path_to_markdown_record_json(model, true)
+      name ||= model.name if model.respond_to?(:name)
+
+      block_given? ? link_to("/#{path}", html_options, nil, &block) : link_to(name, path, html_options, &block)
+    end
+    
+    def path_to_markdown_record_json(model, download = false)
+      path_to_markdown_record(model, "json", download)
+    end
+
+    def url_for_markdown_record_html(model, download = false)
+      path = path_to_markdown_record_json(model, download)
+
+      "#{root_url}/#{path}"
+    end
+
+    def path_to_markdown_record(model, ext, download = false)
+      raise ArgumentError.new("A MarkdownRecord model must be provided.") unless model&.is_a?(::MarkdownRecord::Base)
+
+      subdirectory = model.fragment_id
+
+      path = Pathname.new(MarkdownRecord.config.mount_path).join(ext)
+      path = path.join("download") if download
+      path = path.join(subdirectory).to_s
+
+      "/#{path}"
+    end
+
+    def render_html_example(example)
+      CGI.escapeHTML(example)
+    end
+  end
+end

data/app/models/markdown_record/demo/dsl_command.rb

@@ -0,0 +1,10 @@
+module MarkdownRecord
+  module Demo
+    class DslCommand < ::MarkdownRecord::Base
+      attribute :name
+      attribute :description
+
+      belongs_to_content :section
+    end
+  end
+end

data/app/models/markdown_record/demo/section.rb

@@ -0,0 +1,9 @@
+module MarkdownRecord
+  module Demo
+    class Section < ::MarkdownRecord::Base
+      attribute :name
+      
+      has_many_content :dsl_commands
+    end
+  end
+end

data/app/models/markdown_record/tests/child_model.rb

@@ -0,0 +1,15 @@
+module MarkdownRecord
+  module Tests
+    class ChildModel < ::MarkdownRecord::Base
+      attribute :string_field
+      attribute :int_field
+      attribute :float_field
+      attribute :bool_field
+      attribute :date_field
+      attribute :maybe_field
+      attribute :hash_field
+      
+      belongs_to_content :model
+    end
+  end
+end

data/app/models/markdown_record/tests/fake_active_record_model.rb

@@ -0,0 +1,13 @@
+module MarkdownRecord
+  module Tests
+    class FakeActiveRecordModel
+      include ::ActiveAttr::Model
+      include ::MarkdownRecord::ContentAssociations
+      attribute :model_ids
+      attribute :child_model_id
+      
+      has_many_content :models
+      belongs_to_content :child_model
+    end
+  end
+end

data/app/models/markdown_record/tests/model.rb

@@ -0,0 +1,15 @@
+module MarkdownRecord
+  module Tests
+    class Model < ::MarkdownRecord::Base
+      attribute :string_field
+      attribute :int_field
+      attribute :float_field
+      attribute :bool_field
+      attribute :date_field
+      attribute :maybe_field
+      attribute :hash_field
+      
+      has_many_content :child_models
+    end
+  end
+end

data/app/models/markdown_record/tests/other_child_model.rb

@@ -0,0 +1,15 @@
+module MarkdownRecord
+  module Tests
+    class OtherChildModel < ::MarkdownRecord::Base
+      attribute :string_field
+      attribute :int_field
+      attribute :float_field
+      attribute :bool_field
+      attribute :date_field
+      attribute :maybe_field
+      attribute :hash_field
+      
+      belongs_to_content :model
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,13 @@
+::MarkdownRecord::Engine.routes.draw do
+  routing_config = ::MarkdownRecord.config.routing
+
+  get "html/download/*content_path", to: "html#download" if routing_config[:html].include?(:download)
+  get "html/*content_path", to: "html#show" if routing_config[:html].include?(:show)
+
+  get "json/download/*content_path", to: "json#download" if routing_config[:json].include?(:download)
+  get "json/*content_path", to: "json#show" if routing_config[:json].include?(:show)
+
+  get "download/*content_path", to: "content#download" if routing_config[:content].include?(:download)
+  get "/*content_path", to: "content#show" if routing_config[:content].include?(:show)
+
+end

data/lib/generators/markdown_record_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+require "rails/generators"
+
+class MarkdownRecordGenerator < Rails::Generators::Base
+  source_root File.expand_path("../../templates", __dir__)
+  class_option :demo, type: :boolean, aliases: :d
+
+  desc "This generator creates the default directories required for markdown_record and copies the default layout into the default location."
+  def create_directories
+    empty_directory "markdown_record/content"
+    empty_directory "markdown_record/layouts"
+    empty_directory "markdown_record/rendered"
+  end
+
+  def copy_demo_or_base
+    if options[:demo]
+      directory "demo/content", "markdown_record/content"
+      directory "demo/layouts", "markdown_record/layouts"
+      directory "demo/assets/images", "app/assets/images"
+    else
+      directory "base/content", "markdown_record/content"
+      directory "base/layouts", "markdown_record/layouts"
+    end
+  end
+
+  def copy_initializer
+    copy_file "markdown_record_initializer.rb", "config/initializers/markdown_record.rb"
+  end
+
+  def copy_thorfile
+    copy_file "Thorfile", "Thorfile"
+  end
+
+  def copy_thor_tasks
+    copy_file "render_content.thor", "lib/tasks/render_content.thor"
+  end
+
+  def mount_engine
+    gsub_file "config/routes.rb", "\n  # Do not change this mount path here! Instead change it in the MarkdownRecord initializer.\n  mount MarkdownRecord::Engine, at: MarkdownRecord.config.mount_path, as: \"markdown_record\"", ""
+    gsub_file "config/routes.rb", /Rails.application.routes.draw do/, "Rails.application.routes.draw do\n  # Do not change this mount path here! Instead change it in the MarkdownRecord initializer.\n  mount MarkdownRecord::Engine, at: MarkdownRecord.config.mount_path, as: \"markdown_record\""
+  end
+end
+
+