markdown_record 0.1.3

data/templates/demo/content/10_custom_models_and_associations.md.erb

@@ -0,0 +1,78 @@
+<!--fragment { "author": "Bryant Morrill", "parent_id": "content/home", "name": "Custom Models and Associations" } -->
+<!---model { "type": "markdown_record/demo/section", "id":   8, "name": "Custom Models and Associations" } -->
+
+# Custom Models and Associations
+
+This sectional will discuss how to create MarkdownContent models and defines associations on them, as well as how to define associations between MarkdownContent and ActiveRecord models.
+
+To make a MarkdownContent, it only needs to inherit from `MarkdownContent::Base`. Once you have done that, you can define attributes and associations on it to other MarkdownContent models.
+
+## Attributes
+
+`MarkdownContent::Base` includes `ActiveAttr::Model` to provide attribute functionality. Please see how to use the ActiveAttr gem's interface <%= link_to("here", "https://github.com/cgriego/active_attr") %>.
+
+## Asscociations
+
+You can define custom associations on your model using the `belongs_to_content`, `has_one_content` and `has_many_content` methods like so:
+
+```ruby
+module MarkdownRecord
+  module Demo
+    class Section < ::MarkdownRecord::Base
+      attribute :name
+      
+      has_many_content :dsl_commands
+    end
+  end
+end
+```
+
+```ruby
+module MarkdownRecord
+  module Demo
+    class DslCommand < ::MarkdownRecord::Base
+      attribute :name
+      attribute :description
+
+      belongs_to_content :section
+    end
+  end
+end
+```
+
+Once the associations are defined, you will want to make sure your JSON objects in your markdown have the required fields. For the example above, the DslCommand model will automatically be given a `section_id` field that will need to be populated in your markdown like so:
+
+```html
+<!---model { "type": "markdown_record/demo/dsl_command", "id": 6, "name": "directory_fragment", "section_id": 1 } -->
+```
+
+Then you can use the association in your code just like ActiveRecord associations:
+
+```ruby
+MarkdownRecord::Demo::Section.find(3).dsl_commands.all
+ => 
+[#<MarkdownRecord::Demo::DslCommand section_id: 1, description: "...", ...>, ...]
+```
+
+```ruby
+MarkdownRecord::Demo::DslCommand.find(1).section
+ => #<MarkdownRecord::Demo::Section filename: "content_dsl", id: 3, name: "Content DSL", subdirectory: "content", type: "markdown_record/demo/section">
+```
+
+`has_many_content` will define a method that returns an `MarkdownRecord::Association` object, which you can then chain queries onto. `belongs_to_content`  and `has_one_content` will define methods that returns a single MarkdownContent model.
+
+### Associations on ActiveRecord Models
+
+You can easily integrate MarkdownRecord and ActiveRecord models together using the `MarkdownRecord::ContentAssociations` module. Just include it in your ActiveRecord model like so:
+
+```ruby
+class Product < ActiveRecord::Base
+  include MarkdownRecord::ContentAssociations
+
+  has_one_content :user_manual
+  has_many_content :research_notes
+end
+````
+
+You can define the same associations as described for MarkdownRecord models for ActiveRecord models. An important difference between the two cases, however, is that there are no foreign keys on the MarkdownRecord models that point to ActiveRecord models. Instead, MarkdownRecord expects to find an attribute on the ActiveRecord model that can be used for querying the MarkdownRecord models. For example, the `Product` model above should have a `user_manual_id` column or attribute. This effectively makes `has_one_content` and `belongs_to_content` aliases for each other. In the case of `has_many_content`, the model should have an attribute that is a JSON array of ids that point to the related MarkdownRecord models. In the example above, it would be called `research_note_ids`.
+

data/templates/demo/content/11_controller_helpers.md.erb

@@ -0,0 +1,20 @@
+<!--fragment { "author": "Bryant Morrill", "parent_id": "content/home", "name": "Controller Helpers" } -->
+<!---model { "type": "markdown_record/demo/section", "id":   9, "name": "Controller Helpers" } -->
+
+# Controller Helpers
+
+This section describes the controller helpers provided by MarkdownRecord to help interact with MarkdownRecord.
+
+To use controller helpers in a controller, simply include the `MarkdownRecord::ControllerHelpers` module like so:
+
+```ruby
+include ::MarkdownRecord::ControllerHelpers
+```
+
+When the module is included, you will be able to call the following methods in your controller:
+
+- `content_fragment`: finds a content fragment based on a passed id. If no id is passed it looks for `params[:content_path]` instead.
+- `render_html`: takes an optional content fragment and an optional layout, then renders the fragment as HTML. If no fragment is provided, it calls `content_fragment` to get it using `params[:content_path]`. If no layout is provided, it uses the public_layout configured for MarkdownRecord (by default this is the application layout).
+- `render_json`: takes an optional content fragment and renders it as JSON. If no fragment is provided, it calls `content_fragment` to get it using `params[:content_path]`.
+- `download_html`: same a `render_html` but renders a file for download.
+- `download_json`: same a `render_json` but renders a file for download.

data/templates/demo/content/12_configuration.md.erb

@@ -0,0 +1,26 @@
+<!--fragment { "author": "Bryant Morrill", "parent_id": "content/home", "name": "Configuration" } -->
+<!---model { "type": "markdown_record/demo/section", "id":   9, "name": "Configuration" } -->
+
+# Configuration
+
+Much of MarkdownRecord's behavior is configurable. This section covers what can be configured.
+
+You can configure `MarkdownRecord` in the initializer that is generated upon installation. The config attributes available are:
+
+- `content_root`: the path to the directory containing your markdown source files. This is `markdown_record/content` inside your application root by default.
+- `rendered_content_root`: the path to the directory where rendered content will be saves. This is `markdown_record/rendered` inside your application root by default.
+- `layout_directory`: the path to the directory containing the layouts used during rendering. This is `markdown_record/layouts` inside your application root by default.
+- `concatenated_layout_path`: the relative path (from `layout_directory`) to the layout that should be used for files rendered from the concatenated contents of a directory.
+- `file_layout_path`: the relative path (from `layout_directory`) to the layout that should be used for files rendered from a single markdown source file.
+- `global_layout_path`: the relative path (from `layout_directory`) to the layout that should be used for all rendered files.
+- `markdown_extensions`: MarkdownRecord uses the `Redcarpet` gem under the hood to process markdown. This value is the configuration that gets passed to `::Redcarpet::Markdown`. The default value is `{:fenced_code_blocks => true, :disable_indented_code_blocks => true, :no_intra_emphasis => true}`. Please see <%= link_to("Redcarpet's documentation", "https://github.com/vmg/redcarpet") %> for more details.
+- `html_render_options`: the `render_options` that get passed to Redcarpet's `Redcarpet::Render::HTML` class. The default value is an empty Hash. Please see <%= link_to("Redcarpet's documentation", "https://github.com/vmg/redcarpet") %> for more details.
+- `public_layout`: the path to the layout (from the application root) that should be used when the controllers provided by MarkdownRecord render HTML. The default value is "layouts/application".
+- `render_strategy`: the render strategy that should be use when running the `render_content` Thor task. The default value is `:full` but it can be changed to `:directory` of `:file`. If the `:file` strategy is used then MarkdownRecord will render your markdown content each time MarkdownRecord models queries are executed.
+- `html_routes`: the routes that are generated to render only HTML. This value is an array of symbols that can include `:show` and `:download`. By default the value is `[:show]`.
+- `json_routes`: the routes that are generated to render only JSON. This value is an array of symbols that can include `:show` and `:download`. By default the value is `[:show]`.
+- `content_routes`: the routes that are generated to render either HTML or JSON depending on the request. This value is an array of symbols that can include `:show` and `:download`. By default the value is `[:show]`.
+- `mount_path`: the path where the MarkdownRecord engine is mounted inside the host application. It is `mdr` by default.
+- `render_content_fragment_json`: a boolean value that determines whether MarkdownRecord renders content fragments and saves them to the `rendered_content_root` in JSON files with the `_fragments` suffix. If this is set to `false`, then MarkdownRecord will render your markdown content each time MarkdownRecord models queries are executed. This is set to `true` by default.
+- `render_controller`: the controller used to render ERB content during the rendering process. If this isn't set, then the host application's `ApplicationController` will be used. By default this is `nil`.
+- `ignore_numeric_prefix`: configures whether or not MarkdownRecord ignores the numeric prefixes of filenames. The default value is `true`. When it is set to `false`, the numeric prefixes will be included in the `filename` attribute of models, the `id` attribute of content fragments, and the `content_path` parameter of requests to the routes for rendered content.

data/templates/demo/content/13_sandbox/1_foo.md

@@ -0,0 +1,12 @@
+<!--directory_fragment { "author": "You", "name": "Sandbox", "parent_id": "content/home" } -->
+<!--use_layout:_custom_layout.html.erb-->
+
+Feel free to use this directory as a sandbox to experiment with the things you learn from the guide, without fear of messing up the guide itself. The things defined here are used for automated tests only, so feel free to  delete/alter anything you want here.
+
+When you are done experimenting and want to start creating for real, feel free to delete the entire guide and use the online hosted version for reference going forward.
+
+*Note: you will need to add the .erb extension to this file to use ERB syntax in it.*
+
+<!--model { "id": 1, "type": "markdown_record/tests/model", "string_field": "foo", "int_field": 100, "float_field": 95.5, "bool_field": true, "date_field": "03/13/2023", "maybe_field": null, "hash_field": {} }-->
+
+<!--model { "id": 2, "type": "markdown_record/tests/model", "string_field": "bar", "int_field": 42, "float_field": 99.9, "bool_field": false, "date_field": "12/25/2020", "maybe_field": 50, "hash_field": { "some_data": { "some_field": 999 }}  }-->

data/templates/demo/content/13_sandbox/2_sandbox_nested/1_bar.md

@@ -0,0 +1,18 @@
+<!--directory_fragment { "author": "You", "name": "Sandbox", "parent_id": "content/sandbox/foo" } -->
+<!--use_layout:_custom_layout.html.erb-->
+
+Feel free to use this directory as a sandbox to experiment with the things you learn from the guide, without fear of messing up the guide itself. The things defined here are used for automated tests only, so feel free to  delete/alter anything you want here.
+
+When you are done experimenting and want to start creating for real, feel free to delete the entire guide and use the online hosted version for reference going forward.
+
+*Note: you will need to add the .erb extension to this file to use ERB syntax in it.*
+
+<!--model { "id": 1, "type": "markdown_record/tests/child_model", "model_id": 1, "string_field": "hey", "int_field": 100, "float_field": 95.5, "bool_field": true, "date_field": "03/13/2023", "maybe_field": null, "hash_field": {} }-->
+
+<!--model { "id": 2, "type": "markdown_record/tests/child_model", "model_id": 1, "string_field": "asdf", "int_field": 333, "float_field": 10.5, "bool_field": false, "date_field": "01/01/2000", "maybe_field": 7, "hash_field": {} }-->
+
+<!--model { "id": 3, "type": "markdown_record/tests/child_model", "model_id": 2, "string_field": "qwert", "int_field": 42, "float_field": 1776, "bool_field": true, "date_field": "09/11/2001", "maybe_field": null, "hash_field": { "some_data": { "some_field": 555 }}  }-->
+
+<!--model { "id": 4, "type": "markdown_record/tests/child_model", "model_id": 2, "string_field": "ho", "int_field": 42, "float_field": 99.9, "bool_field": false, "date_field": "12/25/2020", "maybe_field": 50, "hash_field": { "some_data": { "some_field": 999 }}  }-->
+
+<!--model { "id": 1, "type": "markdown_record/tests/other_child_model", "model_id": 2, "string_field": "ho", "int_field": 42, "float_field": 99.9, "bool_field": false, "date_field": "12/25/2020", "maybe_field": 50, "hash_field": { "some_data": { "some_field": 999 }}  }-->

data/templates/demo/content/1_home.md.erb

@@ -0,0 +1,40 @@
+<!--directory_fragment { "name": "Demo", "author": "Bryant Morrill" } -->
+<!--fragment { "name": "Home", "author": "Bryant Morrill" } -->
+
+# MarkdownRecord
+
+Welcome to MarkdownRecord!
+
+This document will walk you through the many powerful features of MarkdownRecord, and is created with MarkdownRecord itself. Hopefully, you are rendering this page locally from your own application, and will be able to get a peak under the hood to see how it all works by looking directly at the source markdown files.
+
+If you haven't installed it locally yet, you can find instructions <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/installation"), "here") %>.
+
+After following the installation guide, you should see a `markdown_record` folder inside your application root. This folder contains three subdirectories: `content`, `layouts` and `rendered`.
+
+Feel free to poke around and explore the files in the directories mentioned above as you go through this guide. They will serve as a great reference to help make sense of the features and concepts described here.
+
+## Workflow
+
+The general workflow while using MarkdownRecord, once installed in your application, is as follows:
+
+1. Write markdown content, using the Content DSL to define data within your markdown content.
+2. Run the provided Thor task to render your markdown content into HTML and JSON.
+3. Use the built in `MarkdownRecord::ContentFragment` model to directly reference your rendered content inside your application. 
+4. Use the provided view helpers to link to the rendered content in your application's views, relying only on the controllers provided by the engine for serving the content if you wish.
+5. Use model classes inheriting from `MarkdownRecord::Base` to interact with your html and json rendered content, taking advantage of the associations you can define manually as well a the automatic associations they have based on content location.
+
+The next step is to read through the <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/rendering_basics"), "Rendering Basics") %> section to understand the basic rendering process of markdown source content into HTML and JSON.
+
+The following links will take you to other sections of this guide. Each section builds upon the last, so it is recommended to read through them in order if you are new to MarkdownRecord.
+
+- <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/content_dsl"))%> 
+- <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/routes")) %>
+- <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/model_basics")) %>
+- <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/content_frags")) %>
+- <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/erb_syntax_and_view_helpers")) %>
+- <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/layouts")) %>
+- <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/custom_models_and_associations")) %>
+- <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/controller_helpers")) %>
+- <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/configuration")) %>
+- <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/sandbox")) %>
+

data/templates/demo/content/2_installation.md.erb

@@ -0,0 +1,129 @@
+<!--fragment { "author": "Bryant Morrill", "name": "Installation", "parent_id": "content/home" } -->
+<!--model { "type": "markdown_record/demo/section", "id":   1, "name": "Installation" } -->
+
+# 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
+      create  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 your <%= link_to("local host demo", "http://localhost:3000/mdr/content/home") %> to continue following this guide.

data/templates/demo/content/3_rendering_basics.md.erb

@@ -0,0 +1,71 @@
+<!--fragment { "author": "Bryant Morrill", "name": "Rendering Basics", "parent_id": "content/home" } -->
+<!--model { "type": "markdown_record/demo/section", "id":   2, "name": "Rendering Basics" } -->
+
+# Rendering Basics
+
+This section will cover the basic concepts of MarkdownRecord.
+
+## Important Directories
+
+MarkdownRecord expects to find a `markdown_record` directory in your project's root folder, and by default looks for the following subdirectories inside it:
+
+- `content`: this is where all your original source files will go. When you write a new markdown file, it will live in here.
+- `layouts`: this is where the layouts used when rendering your markdown source files to HTML should go. This folder should already have a some layouts that you can customize to your liking.
+- `rendered`: this is where all the rendered JSON and HTML files go. You should never have to edit any of the files in here. However, you may want to delete this folder and re-render everything (the folder will be generated again) at certain times, such as when you delete a source file and want to remove the corresponding rendered files and data from your application.
+
+## Rendering Output
+
+By default, MarkdownRecord renders each markdown file in `content` as both a JSON file and an HTML file in the `rendered` directory. It also renders each directory into concatenated JSON and an HTML files containing the rendered content of all their contents. The organization and naming of the rendered files should mirror the organization of the source files and directories in `content`, with the concatenated files at the same level of their respective directories.
+
+In addition, MarkdownRecord also renders and extra JSON file with the `_fragments` suffix. This file contains the auto generated data required to populate `::MarkdownRecord::ContentFragment` models, and is kept separate to keep them from getting mixed in with the JSON rendered from the content files you create.
+
+*IMPORTANT: because of the special meaning of the `_fragments` suffix, the markdown content files that you create should not have `_fragments` in their name to avoid unexpected problems.*
+
+## Numeric Prefixes
+
+You will notice that each file and directory for this demo in the `content` directory has a numeric prefix. These prefixes are how MarkdownRecord determines the order of content in the concatenated files. By using a numeric prefix, the exact order can be specified leading to predictable results.
+
+By default, MarkdownRecord ignores these numeric prefixes for all other purposes. This means that they should not be included in id values for content fragments or in the `content_path` parameter when loading rendered content in the browser (more on both these topics will be discussed later in this guide.). Because of this, it is important that the portion of each filename that comes after the numeric prefix be unique within a subdirectory. If two filename only differ in their numeric prefix, there will be a conflict.
+
+MarkdownRecord can render content using three different strategies: `file`, `directory` and `full`. The default strategy is `full` and will render all files and directories. The `file` strategy will render only files and will not concatenate source content for each directory. The `directory` strategy will only render the concatenated files for each directory.
+
+## File Extensions
+
+MarkdownRecord supports ERB syntax in markdown files that have a `.md.erb` extension. If you don't want MarkdownRecord to process your files as ERB templates, they should have the `.md` extension instead.
+
+## Thor tasks
+
+The MarkdownRecord rendering process is executed via Thor tasks, just like the one used in the installation instructions. The one there looks like this:
+
+```bash
+thor render_content:all -s
+```
+Note the `all` part of that command, which indicates that both JSON and HTML will be rendered. You could use `json` or `html` there to only render one type of content.
+
+The `-s` argument indicates that the rendered content should be saved. If that argument is omitted, you will see the output of the rendering but it will only do a dry run without saving anything.
+
+You can see more options for the Thor task by running: 
+
+```bash
+thor render_content -h 
+```
+
+```bash
+Commands:
+  thor render_content:all             # renders html and json content
+  thor render_content:help [COMMAND]  # Describe available commands or one specific command
+  thor render_content:html            # renders html content
+  thor render_content:json            # renders json content
+
+Options:
+  d, [--subdirectory=SUBDIRECTORY]  
+  s, [--save], [--no-save]          
+  r, [--strat=STRAT]                
+  f, [--frag], [--no-frag]   
+```
+
+### Validation
+
+MarkdownRecord validates your filenames and JSON data before rendering. If it finds any problems, it will output a message to the terminal and nothing will be rendered.
+
+

data/templates/demo/content/4_content_dsl.md.erb

@@ -0,0 +1,104 @@
+<!--fragment { "author": "Bryant Morrill", "parent_id": "content/home", "name": "Content DSL" } -->
+<!--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 (if you define matching models), or directly served via built in routes.
+
+To do this, simply write an HTML comment like this in your markdown files:
+
+```html
+<!---model 
+  { 
+    "type": "markdown_record/demo/dsl_command",
+    "id": 1, 
+    "name": "model",
+    "example_id": 1
+  } 
+-->
+```
+
+*Note: you can write these JSON object inline as well to be more concise.*
+
+As you can see, all that is required is a JSON object inside a special comment that defines your data. The `model` part of the comment is a DSL command that tells MarkdownRecord how to process the comment, and in this case it will take your JSON object and include it in its final rendered JSON output, which will automatically make it available via the provided routes and controllers. If this part is missing or unrecognized, then the comment will be treated as a plain HTML comment and nothing will be done with its contents.
+
+There are several different DSL commands that you can use to define application data within your markdown source documents. They are as follows:
+
+<!--model { "type": "markdown_record/demo/dsl_command", "id": 1, "name": "model", "section_id": 3 } -->
+<!--attribute:description:string-->
+- `model` is the main command that tells MarkdownRecord that you want to define a model or JSON object. The only attribute required in the json object you provide is the `type` attribute, which is used as an index in the final JSON output (each index points to an array of objects of that type). The type can be whatever you want if you don't plan on using corresponding Ruby models. If you *do* plan to use corresponding Ruby models, then the `type` attribute should match the fully qualified class name of the model in underscore form (i.e. `Foo::BarBaz` would be `foo/bar_baz`). 
+    
+    MarkdownRecord puts each model in a stack structure during rendering, and remembers the order in which models are defined within a single markdown file. This is important, as the next command in this list allows you to add additional attributes where the values are taken from your markdown content itself. The model that attributes get assigned to in this way is always the model at the top of the stack.
+    <!--end_attribute-->
+
+    See the example above.
+    <!--end_model-->
+    
+<!--model { "type": "markdown_record/demo/dsl_command", "id": 2, "name": "attribute", "section_id": 3 } -->
+<!--attribute:description:string--> 
+- `attribute:<attribute_name>:<type>` tells MarkdownRecord that any text that follows should be assigned to the top model on the stack as the value of the given attribute, until it sees the `end_attribute` command.
+  
+    The `type` part of this command can be `html`, `md`, `int`, `float`, `string`, or omitted. MarkdownRecord will process the final value of the attribute differently based on this value. If the type is `html`, it will be rendered into an html string. If it is `md`, then it will be left as is and slightly cleaned up to remove leading and trailing white space. If it is `int` or `float`, it will be parsed accordingly into an numeric value, and if it is `string`, it will be stripped of any markdown syntax and all leading and trailing whitespace will be removed. The `string` option will also cause multiple newlines to be reduced to a single newline. If the type option is omitted, MarkdownRecord will not process the attribute value and it will contain the raw content read from the markdown file.
+    <!--end_attribute-->
+
+    Example:
+
+    ```html
+    <!---attribute:description:string-->
+    ```
+    <!--end_model-->
+<!--model { "type": "markdown_record/demo/dsl_command", "id": 3, "name": "end_attribute", "section_id": 3 } -->
+<!--attribute:description:string-->
+- `end_attribute` tells MarkdownRecord to stop assigning text as an attribute value to the top model on the stack. If the top most model is popped before this command is given or the end of the source file is reached, then it implicitly stops assigning text to it.
+<!--end_attribute-->
+
+    Example:
+
+    ```html
+    <!---end_attribute-->
+    ```
+    <!--end_model-->
+<!--model { "type": "markdown_record/demo/dsl_command", "id": 4, "name": "end_model", "section_id": 3 } -->
+<!--attribute:description:string-->
+- `end_model` tells MarkdownRecord to pop the top model of the stack. This command isn't necessary unless you are defining models in a way that requires you to assign attributes to a model that is no longer the top model on the stack.
+<!--end_attribute-->
+
+    Example:
+
+    ```html
+    <!---end_model-->
+    ```
+    <!--end_model-->
+<!--model { "type": "markdown_record/demo/dsl_command", "id": 5, "name": "fragment", "section_id": 3 } -->
+<!--attribute:description:string-->
+- `fragment` is similar to `model` in that it expects a JSON object, but the object is assigned to the `meta` attribute of the `ContentFragment` corresponding to the current markdown file. As such, this command should only be used once in each file. This command provides a way of attaching custom data to ContentFragments, such as a layout you want to use for rendering from a controller, details about the content's author, or perhaps who should be able to access it, etc. You can then interact this data in your application code.
+
+    Since content is not just rendered for each individual file, but is also concatenated into rendered files for each directory, the ContentFragments representing these concatenated files will have each file's fragment meta data as a nested object, indexed by the respective file's path.
+    <!--end_attribute-->
+
+    Example:
+
+    ```html
+    <!---fragment { "author": "Bryant Morrill" } -->
+    ```
+    <!--end_model-->
+<!--model { "type": "markdown_record/demo/dsl_command", "id": 6, "name": "directory_fragment", "section_id": 3 } -->
+<!--attribute:description:string-->
+- `directory_fragment` is used exactly the same way as `fragment` but defines the `meta` attribute of the `ContentFragment` for the current directory. As such, this should only be used once per directory level, otherwise subsequently defined data might overwrite preceding data.
+<!--end_attribute-->
+<!--end_model-->
+<!--model { "type": "markdown_record/demo/dsl_command", "id": 7, "name": "use_layout", "section_id": 3 } -->
+<!--attribute:description:string-->
+- `use_layout:<path>` simply specifies a layout by its relative file path to use when rendering the current markdown file to HTML. This is useful for when you have specific markdown files that you want to render using a different layout than the layout configured for use with all other files.
+<!--end_attribute-->
+
+    Example:
+    
+    ```html
+    <!--use_layout:_custom_layout.html.erb-->
+    ```
+    <!--end_model-->
+
+You can view this document's source files in `markdown_record/content` to see some of the above DSL commands in use.

data/templates/demo/content/5_routes.md.erb

@@ -0,0 +1,43 @@
+<!--fragment { "author": "Bryant Morrill", "parent_id": "content/home", "name": "Routes" } -->
+<!--model { "type": "markdown_record/demo/section", "id":   4, "name": "Routes" } -->
+
+# Routes
+
+This section discusses the automatically available routes you can use to render markdown content as HTML or JSON.
+
+If you are reading this document in a browser by rendering it from your application, then you will have already ran the Thor command necessary to render the demo content as HTML and JSON. You can also see the HTML and JSON files in the `rendered` directory. In fact, the content you are viewing right now as you read this is one of those files, served to you via the built in routes that come with MarkdownRecord.
+
+All of the following routes should now resolve successfully:
+
+- `<application root path>/mdr/html/<content_path>`
+- `<application root path>/mdr/json/<content_path>`
+- `<application root path>/<content_path>`
+
+
+`content_path` in the above routes is the path to a rendered file or directory (relative to the `rendered` folder). When you navigate to a path that points to a directory, you will see the concatenated contents of everything that is in that directory.
+
+The `html` routes only return HTML, while the `json` routes only return JSON. The generic route returns either HTML or JSON depending on the ACCEPT header of your request or the extension of the url you are accessing (for example, appending `.json` at the end of the current url will load all the JSON models defined in this this document's markdown source files using the Content DSL commands described above).
+
+In addition to the above routes, routes for downloading content are provided as well. They are:
+
+- `<application root path>/mdr/html/download/<content_path>`
+- `<application root path>/mdr/json/download/<content_path>`
+- `<application root path>/download/<content_path>`
+
+The download routes are not enabled by default, but can be enabled if you want to be able to download your rendered content.
+
+Here is a complete list of links to all the rendered HTML files of this demo (each item has a JSON and an HTML version), all of which use the routes described above:
+
+<% ::MarkdownRecord::ContentFragment.all.each do |frag| %>
+- <%= link_to_markdown_record(frag, frag.id) %><br>
+<% end %>
+
+<% ::MarkdownRecord::ContentFragment.all.each do |frag| %>
+- <%= link_to_markdown_record_html(frag, frag.html_route) %><br>
+<% end %>
+
+<% ::MarkdownRecord::ContentFragment.all.each do |frag| %>
+- <%= link_to_markdown_record_json(frag, frag.json_route) %><br>
+<% end %>
+
+Some of the above routes are the rendered versions of individual files, and some are the concatenated and rendered contents of an entire directory.