markdown_record 0.1.3

data/templates/demo/content/6_model_basics.md.erb

@@ -0,0 +1,105 @@
+<!--fragment { "author": "Bryant Morrill", "parent_id": "content/home", "name": "Model Basics" } -->
+<!--model { "type": "markdown_record/demo/section", "id":   5, "name": "Model Basics" } -->
+
+# MarkdownRecord Models
+
+The `::MarkdownRecord::Base` model is the base class for all models used for interacting with the JSON content that is rendered by MarkdownRecord. It has the following attributes:
+
+- `id`
+- `type<String>`
+- `subdirectory<String>`
+- `filename<String>`
+
+The `id` attribute doesn't have a type, but for `::MarkdownRecord::ContentFragment` models it will always be a string value equal to the relative path of the file the model represents. You can set it to any value for the models you define, but each model should have an id that is unique among models of the same type.
+
+The `type` attribute is the fully qualified class name of the model in underscore form (i.e. `::MarkdownRecord::ContentFragment` would be `markdown_record/content_fragment`).
+
+`subdirectory` and `filename` always match the relative path of the file the model was defined in, or in the case of content fragments, the file the model represents. These attributes are auto-populated during the rendering process.
+
+## Query Methods
+
+`::MarkdownRecord::Base` provides several query methods to it's child classes. They are:
+
+- `find`
+- `all`
+- `where`
+
+These methods all work similarly to ActiveRecord by design. For example, if we use the models defined in the previously in this guide, then we could do this:
+
+```ruby
+::MarkdownRecord::Demo::DslCommand.find(4)
+ => #<MarkdownRecord::Demo::DslCommand description: "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.", filename: "content_dsl", id: 4, name: "end_model", subdirectory: "content/api_docs", type: "markdown_record/demo/dsl_command">
+
+```
+
+*or*
+
+```ruby
+::MarkdownRecord::Demo::DslCommand.all
+ => 
+[#<MarkdownRecord::Demo::DslCommand description: "...", name: "model", ...>,
+ #<MarkdownRecord::Demo::DslCommand description: "...", name: "attribute", ...>
+ ...
+]
+```
+
+The `where` query method takes an optional hash of filters and returns a `MarkdownRecord::Association` object, which you can chain additional methods onto. The methods you can chain onto this object are:
+
+- `where`: subsequent calls to this query method will merge the passed filters into the previously provided filter hash.
+- `not`: this method takes a hash of filters that is negated, so it will only return models that don't pass filters.
+- `fragmentize`: this method turns the association into a fragment association, meaning it will filter and return `MarkdownRecord::ContentFragment` models only.
+- `to_fragments`: this method queries for MarkdownRecord models but returns their corresponding content fragments instead. This will often result in duplicates due to models being defined in the same file.
+- `all`: this method simply returns an Array of models, filtered according to whatever filters have been provided to the association object.
+
+`MarkdownRecord::Association` also supports the `to_a`, `each`, `map`, `count`, `any?`, `empty?`, `first`, `last`, `second`, `third` and `fourth` methods which get executed on the backing Array after loading the data with the most recent filters. For additional functionality, you may call `all` or `to_a` to work with the backing Array directly.
+
+## Filters
+
+MarkdownRecord supports various types of filter values. Those types and what they mean are as follows:
+
+- `Array`: the attribute value must be included in the array.
+- `Hash`: the attribute value must be a Hash which the filter value (a Hash of nested filters) will be applied against.
+- `nil`: the attribute value must be nil/null.
+- `Regexp`: the attribute value must match the Regex expression.
+- `:not_null`: the attribute value must not be nil/null.
+- `:null`: the attribute value must be nil/null.
+- Any other valid JSON type, in which case the attribute value must equal the filter value.
+
+In addition, you can pass `:__and__` or `:__or__` as filter keys that point to arrays of filter hashes. In the former case, all filter hashes must pass, and in the later case, only one of the filter hashes must pass.
+
+Finally, you can pass `:__not__` as a filter key as well, which should point to a filter hash where all the filters must not pass.
+
+Examples:
+
+```ruby
+# querying with a string value
+MarkdownRecord::Demo::DslCommand.where(:name => "model").all
+ => [#<MarkdownRecord::Demo::DslCommand ...>]
+```
+
+```ruby
+# querying for models that don't have "fragment" in the name.
+MarkdownRecord::Demo::DslCommand.where(__not__: { :name => /fragment/}).map(&:name)
+ => ["model", "attribute", "end_attribute", "end_model", "use_layout"]
+```
+
+```ruby
+MarkdownRecord::Demo::DslCommand.where(__or__: [{ :name => /fragment/}, {:name => :null}]).map(&:name)
+ => ["model", "fragment", "directory_fragment"]
+```
+
+```ruby
+MarkdownRecord::ContentFragment.where(:meta => {:author => "Bryant Morrill"}).first
+ => #<MarkdownRecord::ContentFragment ...>
+```
+
+## Automatic Associations
+
+`::MarkdownRecord::Base` provides several associations automatically to its child classes, which are all based on their relative relative location to each other. These associations are:
+
+- `siblings`: all models generated from files in the same directory and at the same level as the current model.
+- `class_siblings`: same as `siblings` but only models of the same type.
+- `children`: all models generated from files in nested directories within the directory the current model is defined in.
+- `fragment`: the `MarkdownRecord::ContentFragment` instance representing the file where the model was defined.
+
+`siblings`, `class_siblings` and `children` are all methods that return a `MarkdownRecord::Association` object. The `fragment` method returns a `MarkdownRecord::ContentFragment` instance.

data/templates/demo/content/7_content_frags.md.erb

@@ -0,0 +1,78 @@
+<!--fragment { "author": "Bryant Morrill", "parent_id": "content/home", "name": "Content Fragments" } -->
+<!---model { "type": "markdown_record/demo/section", "id":   6, "name": "Content Fragments" } -->
+
+# Content Fragments
+
+This section describes how to use the `::MarkdownRecord::ContentFragment` model to easily interact with your written markdown content from your application code.
+
+Each file and directory in the `content` directory that gets rendered as either HTML or JSON will have a content fragment JSON object created for it that represents that source file. These JSON objects get stored in the corresponding file with a `_fragments` suffix.
+
+In your application code, you can interact with content fragment JSON objects via the `::MarkdownRecord::ContentFragment` model. This model is a child class of `::MarkdownRecord::Base` and adds the following attributes:
+
+- `meta<Hash>`
+- `concatenated<Boolean>`
+
+The `meta` attribute contains a `Hash` populated with any data you that you defined using the `fragment` or `directory_fragment` content DSL methods.
+
+`concatentated` will be auto-populated during rendering and will be true for fragments representing a directory, and false for those representing files.
+
+### Querying Content Fragments
+
+You can query content fragments just like you query other MarkdownRecord models, but these queries will only return content fragments. Using filter values that are Hashes, however, will allow you to query and filter content fragments based on their `meta` attributes.
+
+## Associations
+
+Content fragments also have a few extra associations, which are:
+
+- `ancestors`: the content fragments above the current fragment in the content structure.
+- `ancestors_from`: the content fragments above the current fragment in the content structure, starting with a content fragment or content fragment id that is passed in.
+- `parent`: the content fragment directly above the current fragment in the content structure.
+
+Each of the above associations use the file tree structure, meaning that they will only return content fragments representing directories.
+
+The `parent` method, however, can have its behavior overridden by setting a `parent_id` field in the `meta` hash of the content fragment to the id of another content fragment using the Content DSL.
+
+For example, the file that this text is written in is at `content/blog/content_frags.md`, meaning that the parent of the directory level content fragment with `id = "content/blog"` would normally be the directory level content fragment with `id = "content"`.
+
+In code, this would look like:
+
+```ruby
+MarkdownRecord::ContentFragment.find("content/content_frags").parent
+ => #<MarkdownRecord::ContentFragment concatenated: true, filename: "content", id: "content", meta: {"name"=>"Demo", ...}, subdirectory: "", type: "markdown_record/content_fragment"> 
+```
+
+But one of the files in in `content/blog` uses the Content DSL to define meta data for the directory content fragment, like so:
+
+```html
+<!---directory_fragment { "name": "Example: Blog", "parent_id": "content/home" } -->
+```
+
+The `parent_id` in the `meta` hash overrides the default behavior, which changes what fragment is returned from `parent`:
+
+```ruby
+MarkdownRecord::ContentFragment.find("content/content_frags").parent
+ => #<MarkdownRecord::ContentFragment concatenated: false, filename: "home", id: "content/home", meta: {"name"=>"Home", ...}, subdirectory: "content", type: "markdown_record/content_fragment">
+```
+
+The ability to override the natural `parent` of a content fragment is useful for constructing a list or hierarchy of content that is not strictly based on file structure. The `parents_from` method is useful in doing this, as it builds a hierarchy but respect any `parent_id` of the content fragments it comes across instead of assuming the containing directory is the parent. This is useful for constructing breadcrumbs and navigation in your views.
+
+Exampe:
+
+```ruby
+MarkdownRecord::ContentFragment.find("content/sandbox/foo")
+  .parents_from("content/home")
+  .map(&:id)
+ => ["content/home", "content/sandbox"]
+```
+
+## Instance Methods
+
+`MarkdownRecord::ContentFragment` has the following instance methods:
+
+- `exists?`: returns `true`` or `false`` depending on whether a JSON or HTML file corresponding to the content fragment can be found. This should always return `true` unless something has gone wrong with the rendering process.
+- `json_exists?`: returns `true` if a corresponding JSON files can be found.
+- `html_exists?`: returns `true` if a corresponding HTML files can be found.
+- `read_json`: reads the corresponding JSON file.
+- `read_html`: reads the corresponding HTML file.
+- `json_path`: returns the path to the corresponding JSON file.
+- `html_path`: returns the path to the corresponding HTML file.

data/templates/demo/content/8_erb_syntax_and_view_helpers.md.erb

@@ -0,0 +1,88 @@
+<!--fragment { "author": "Bryant Morrill", "parent_id": "content/home", "name": "ERB Syntax and View Helpers" } -->
+<!---model { "type": "markdown_record/demo/section", "id":   7, "name": "ERB Syntax and View Helpers" } -->
+
+# ERB Syntax and View Helpers
+
+This section describes how to use ERB syntax and view helpers in your markdown files and ERB views in conjunction with MarkdownRecord models to make navigating across all your rendered content easy.
+
+## ERB Syntax
+
+MarkdownRecord supports the use of ERB syntax in your markdown source files. It also provides the following local variables for use in your ERB code:
+
+- `filename`: the name of the file being rendered.
+- `subdirectory`: the subdirectory of the file being rendered.
+- `frag_id`: the id of the fragment corresponding to the file being rendered.
+- `fragment`: the content fragment model instance corresponding to the file being rendered.
+
+## Rails View Helpers
+
+All the standard view helpers that come with Rails should be accessible within your markdown source files when rendered as ERB files, such as tag helpers and path helpers.
+
+For example, the image below is rendered using the `image_tag` tag helper:
+
+<%= image_tag("ruby-logo") %>
+
+## View Helpers
+
+MarkdownRecord provides the following view helpers to use in your ERB views as well as in your markdown content source files:
+
+- `link_to_markdown_record`: generates a link to the content fragment you pass in, or else the content fragment corresponding to the MarkdownRecord model you pass in.
+
+    For example, for a content fragment such as:
+
+    ```ruby
+    fragment
+    => #<MarkdownRecord::ContentFragment filename: "content", id: "content/erb_syntax_and_view_helpers", meta: {"name"=>"ERB Syntax and View Helpers", ...}, ...> 
+    ```
+
+    When you pass it into the view helper like so:
+    
+    ```html
+    <%%%= link_to_markdown_record(fragment)%>
+    ```
+
+    The result would be the following markup:
+
+    ```html
+    <a href="/mdr/content/erb_syntax_and_view_helpers">ERB Syntax and View Helpers</a>
+    ```
+
+    Notice how the text in the link is the name value found in the content fragment meta attribute. This is because MarkdownRecord checks to see if the model passed in responds to `name`, and `MarkdownRecord::ContentFragment` has a `name` method that returns the `name` field, if present, from its meta hash.
+
+    A fragment without a name will be rendered like this:
+
+    ```html
+    <a href="/mdr/content/erb_syntax_and_view_helpers">/mdr/content/blog/view_helpers</a>
+    ```
+
+    Unless you pass in a name explicitly:
+
+    ```html
+    <%%%= link_to_markdown_record(fragment, "Click Here!") %>
+    ```
+
+    Which will produce:
+
+    ```html
+    <a href="/mdr/content/erb_syntax_and_view_helpers">Click Here!</a>
+    ```
+
+    You may have noticed that this view helper works almost identically to the standard Rails `link_to` method, and in fact this helper simply wraps `link_to`. As such, it has the same API that accepts `html_options` and a `block` as well. The only difference is that you have to pass in a `MarkdownRecord` model as the first parameter.
+
+- `link_to_markdown_record_html`: this view helper works identically to `link_to_markdown_record`, but adds the `html` prefix to the route so that it can only return HTML.
+- `link_to_download_markdown_record_html`: same as `link_to_markdown_record_html` but downloads a file instead.
+- `link_to_markdown_record_json`: this view helper works identically to `link_to_markdown_record`, but adds the `json` prefix to the route so that it can only return HTML.
+- `link_to_download_markdown_record_html`: same as `link_to_markdown_record_json` but downloads a file instead.
+
+### Breadcrumbs
+
+Using the view helpers in conjunction with content fragments, you can easily build navigation that automatically updates when you rerender your content. This guide uses this technique and you can find the following code in the `_global_layout.html.erb` layout:
+
+```html
+<%%% fragment.parents_from("content/home").each_with_index do |frag, index| %>
+    <%%% unless index == 0%>
+        <span class="breadcrumb_divider">/</span>
+    <%%% end %>
+    <li><%%%= link_to_markdown_record(frag)%>
+<%%% end %>
+```

data/templates/demo/content/9_layouts.md.erb

@@ -0,0 +1,15 @@
+<!--fragment { "author": "Bryant Morrill", "parent_id": "content/home", "name": "Layouts" } -->
+<!---model { "type": "markdown_record/demo/section", "id":   8, "name": "Layouts" } -->
+
+# Layouts
+
+When MarkdownRecord renders markdown source files, it looks for three different ERB layouts that it can use as templates. These layouts are each passed the same local variables as a markdown file when rendered as ERB (as discussed in the previous section), as well as an `html` variable that is the rendered html produced from the markdown content.
+
+The layouts that MarkdownRecord uses by default are added to your application at the time of install in the `markdown_record/layouts` directory. They are:
+
+- `_file_layout.html.erb`: this is the layout used for individual files. Concatenated files will show this layout multiple times, each with a different file rendered in it. The red border of this guide is part of this layout.
+- `_concatenated_layout.html.erb`: this is the layout used only for concatenated files. It will only be rendered once per file, but not for files that don't contain the concatenated contents of a directory. Some of the pages of this guide have a blue border, which is a style defined only in this layout.
+- `_global_layout.html.erb`: this is the layout that is used for every rendered file, regardless of whether it is a concatenated file or not. This is the recommended layout to use for global styles, etc.
+
+In addition to the above, there is also a `_custom_layout.html.erb` which is used for the contents of the <%= link_to_markdown_record(::MarkdownRecord::ContentFragment.find("content/sandbox"), "sandbox") %> part of this guide. This demonstrates how you can override the layout used for a specific file using the `user_layout` Content DSL command.
+

data/templates/demo/layouts/_concatenated_layout.html.erb

@@ -0,0 +1,12 @@
+<style>
+  .concatenated{
+    border: 1px solid #a5d6ff;
+    padding: 10px;
+  }
+</style>
+
+<div class="concatenated">
+  <%= raw(html) %>
+  <%= raw("<!--#{subdirectory}/#{filename}-->") %>
+  <p class="rendered_at"><em>The above content was rendered from source files at: <%= link_to_markdown_record(fragment, fragment.id) %></em></p>
+</div>

data/templates/demo/layouts/_custom_layout.html.erb

@@ -0,0 +1,14 @@
+<style>
+  .custom_layout_file {
+    padding: 10px;
+    border: 1px solid pink;
+    margin-bottom: 10px;
+  }
+</style>
+
+<div class="custom_layout_file">
+  <h3>Rendered Using a Custom Layout</h3>
+  <%= raw(html) %>
+  <%= raw("<!--#{subdirectory}/#{filename}-->") %>
+  <p class="rendered_at"><em>The above content was rendered from source files at: <%= link_to_markdown_record(fragment, fragment.id) %></em></p>
+</div>

data/templates/demo/layouts/_file_layout.html.erb

@@ -0,0 +1,15 @@
+<style>
+
+  .file {
+    padding: 10px;
+    border: 1px solid #cc4400;
+    margin-bottom: 10px;
+  }
+
+</style>
+
+<div class="file">
+  <%= raw(html) %>
+  <%= raw("<!--#{subdirectory}/#{filename}-->") %>
+  <p class="rendered_at"><em>The above content was rendered from source files at: <%= link_to_markdown_record(fragment, fragment.id) %></em></p>
+</div>

data/templates/demo/layouts/_global_layout.html.erb

@@ -0,0 +1,108 @@
+<style>
+  body{
+    background-color: black;
+    padding: 10px;
+  }
+
+  code{
+    padding: 0.2em 0.4em;
+    margin: 0;
+    font-size: 85%;
+    white-space: break-spaces;
+    background-color: rgb(110 118 129 / 40%);
+    border-radius: 6px;
+  }
+
+  pre{
+    padding: 16px;
+    overflow: auto;
+    font-size: 85%;
+    line-height: 1.45;
+    color: #f2f2f2;
+    background-color: #161b22;
+    border-radius: 6px;
+    font-family: andale mono, monaco, monospace;
+    word-wrap: normal;
+  }
+
+  pre code{
+    color: inherit;
+    background-color: inherit;
+    font-family: inherit;
+    padding: 0px;
+    margin: 0;
+    font-size: inherit;
+    white-space: inherit;
+    background-color: inherit;
+    border-radius: 0px;
+  }
+
+  h1{
+    color: #6699ff;
+  }
+
+  h2{
+    color: #b3ccff;
+  }
+
+  h3{
+    color: #b3ccff;
+  }
+
+  h4{
+    color: #b3ccff;
+  }
+
+  a{
+    color: #33ffcc;
+  }
+
+  .container {
+    margin-bottom: 10px;
+    padding: 10px;
+    color: #f2f2f2;
+    background-color: #0d1117;
+    font-family: trebuchet ms;
+    font-size: 16px;
+    line-height: 1.5;
+  }
+
+  .rendered_at{
+    font-size: 12px;
+  }
+
+  .navigation ul{
+    padding: 0px;
+  }
+
+  .navigation li{
+    display: inline;
+  }
+</style>
+
+<div class="container">
+  <div class="navigation">
+    <ul>
+      <li>Breadcrumbs: </li>
+      <% fragment.parents_from("content/home").each_with_index do |frag, index| %>
+        <% unless index == 0%>
+          <span class="breadcrumb_divider">/</span>
+        <% end %>
+        <li><%= link_to_markdown_record(frag)%></li>
+      <% end %>
+    </ul>
+  </div>
+  <%= raw(html) %>
+  <%= raw("<!--#{subdirectory}/#{filename}-->") %>
+  <div class="navigation">
+    <ul>
+      <li>Breadcrumbs: </li>
+      <% fragment.parents_from("content/home").each_with_index do |frag, index| %>
+        <% unless index == 0%>
+          <span class="breadcrumb_divider">/</span>
+        <% end %>
+        <li><%= link_to_markdown_record(frag)%></li>
+      <% end %>
+    </ul>
+  </div>
+</div>

data/templates/markdown_record_initializer.rb

@@ -0,0 +1,3 @@
+::MarkdownRecord.configure do |config|
+  # configure MarkdownRecord here
+end

data/templates/render_content.thor

@@ -0,0 +1,57 @@
+require "thor"
+
+class RenderContent < Thor
+  include MarkdownRecord::Rendering
+  
+  class_option :subdirectory, required: false, type: :string, aliases: :d, default: ""
+  class_option :save, type: :boolean, aliases: :s, default: false
+  class_option :strat, type: :string, aliases: :r
+  class_option :frag, type: :boolean, aliases: :f
+
+  desc "html", "renders html content"
+  def html
+    return unless validate
+    lines = []
+    strategy_options = generate_render_strategy_options(options)
+    report_start(lines, strategy_options, "html")
+
+    file_saver = ::MarkdownRecord::FileSaver.new
+    ::MarkdownRecord::HtmlRenderer.new(file_saver: file_saver)
+      .render_html_for_subdirectory(subdirectory: options[:subdirectory], **strategy_options)
+    
+    report_rendered_files(lines, file_saver)
+  end
+
+  desc "json", "renders json content"
+  def json
+    return unless validate
+    lines = []
+    strategy_options = generate_render_strategy_options(options)
+    report_start(lines, strategy_options, "json")
+
+    file_saver = ::MarkdownRecord::FileSaver.new
+    ::MarkdownRecord::JsonRenderer.new(file_saver: file_saver)
+      .render_models_for_subdirectory(subdirectory: options[:subdirectory], **strategy_options)
+    
+    report_rendered_files(lines, file_saver)
+  end
+
+  desc "all", "renders html and json content"
+  def all
+    return unless validate
+    lines = []
+    strategy_options = generate_render_strategy_options(options)
+    report_start(lines, strategy_options, "html and json")
+
+    
+    file_saver = ::MarkdownRecord::FileSaver.new
+    ::MarkdownRecord::JsonRenderer.new(file_saver: file_saver)
+      .render_models_for_subdirectory(subdirectory: options[:subdirectory], **strategy_options)
+    
+    ::MarkdownRecord::HtmlRenderer.new(file_saver: file_saver)
+      .render_html_for_subdirectory(subdirectory: options[:subdirectory], **strategy_options)
+
+    
+    report_rendered_files(lines, file_saver)
+  end
+end