faqmarkdown 0.0.1

data/lib/generators/faqmarkdown/install_generator.rb

@@ -0,0 +1,19 @@
+module Faqmarkdown
+  class InstallGenerator < Rails::Generators::Base
+    desc File.read(File.expand_path('../usage/install.txt', __FILE__)).gsub('{{CURRENT_DATE}}', Time.zone.now.strftime('%Y-%m-%d'))
+    source_root File.expand_path('../templates', __FILE__)
+    class_option :skip_example, :type => :boolean, :group => :runtime, :desc => 'Skip generating an example faq'
+
+    def create_directory
+      empty_directory 'app/faqs'
+    end
+
+    def generate_example_faq
+      generate 'faqmarkdown:faq', 'example-faq' unless options.skip_example?
+    end
+
+    def add_routes
+      insert_into_file 'config/routes.rb', "  faqmarkdown :as => :faqs\n\n", :after => "::Application.routes.draw do\n"
+    end
+  end
+end

data/lib/generators/faqmarkdown/override_generator.rb

@@ -0,0 +1,48 @@
+module Faqmarkdown
+  class OverrideGenerator < Rails::Generators::Base
+    desc File.read(File.expand_path('../usage/override.txt', __FILE__))
+    source_root File.expand_path('../../../../app', __FILE__)
+
+    class_option :all,        :type => :boolean, :group => :override, :desc => 'Override all of the things'
+    class_option :views,      :type => :boolean, :group => :override, :desc => 'Override the Faq views'
+    class_option :model,      :type => :boolean, :group => :override, :desc => 'Override the Faq model'
+    class_option :controller, :type => :boolean, :group => :override, :desc => 'Override the Faqs controller'
+    class_option :theme,      :type => :boolean, :group => :override, :desc => 'Override the layout and stylesheet'
+
+    def check_class_options
+      if options.blank?
+        exec 'rails g faqmarkdown:override --help'
+        exit
+      end
+    end
+
+    def override_views
+      if options.views || options.all
+        directory 'views/faqs', 'app/views/faqs'
+      end
+    end
+
+    def override_model
+      if options.model || options.all
+        copy_file 'models/faq.rb', 'app/models/faq.rb'
+      end
+    end
+
+    def override_controller
+      if options.controller || options.all
+        copy_file 'controllers/faqs_controller.rb', 'app/controllers/faqs_controller.rb'
+      end
+    end
+
+    def override_theme
+      if options.theme || options.all
+        directory 'views/layouts', 'app/views/layouts'
+        if Rails.application.config.respond_to?(:assets) && Rails.application.config.assets.enabled
+          directory '../vendor/assets/stylesheets', 'app/assets/stylesheets'
+        else
+          directory '../vendor/assets/stylesheets', 'public/stylesheets'
+        end
+      end
+    end
+  end
+end

data/lib/generators/faqmarkdown/templates/example-faq.markdown

@@ -0,0 +1,67 @@
+---
+title: <%= slug.gsub('-',' ').capitalize %>
+<%- if author = Faqmarkdown::Util.git_config('user.name') -%>
+author: <%= author %>
+<%- end -%>
+<%- if email = Faqmarkdown::Util.git_config('user.email') -%>
+email: <%= email %>
+<%- end -%>
+---
+
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+# Markdown Formatting
+
+[Reference](http://daringfireball.net/projects/markdown/syntax)
+
+---
+
+# Headers
+
+## Header 2
+
+### Header 3
+
+---
+
+# Emphasis
+
+*italic* **bold**
+_italic_ __bold__
+
+---
+
+# Links and Images
+
+An [example](http://url.com/ "Title") Reference-style labels (titles are optional):
+
+![Placeholder Kitten](http://placekitten.com/200/300)
+
+---
+
+# Lists
+
+1. Foo
+2. Bar
+
+Unordered, with nesting:
+
+* Abacus
+  * answer
+* Bubbles
+  1. bunk
+  2. bupkis
+    * BELITTLER
+  3. burper
+* Cunning
+
+---
+
+# Preformatted Code Blocks
+
+Indent every line of a code block by at least 4 spaces or 1 tab.
+
+    This is a preformatted
+    code block.

data/lib/generators/faqmarkdown/usage/faq.txt

@@ -0,0 +1,14 @@
+Description:
+  This generator will produce a new faq by creating a markdown file in the `app/faqs/` directory. The filename for the new file will be generated using the slug and publish date specified.
+
+Example 1:
+  $ rails generate faqmarkdown:faq example-1
+
+  This will:
+    - Generate a new faq using the slug specified and today's date: `app/faqs/{{CURRENT_DATE}}-example-1.markdown`.
+
+Example 2:
+  $ rails generate faqmarkdown:faq example-2 --date=2012-04-10
+
+  This will:
+    - Generate a new faq using the slug and publish date specified: `app/posts/2012-04-10-example-2.markdown`.

data/lib/generators/faqmarkdown/usage/install.txt

@@ -0,0 +1,10 @@
+Description:
+  This generator will create the directory structure and routes required by Faqmarkdown. As an added bonus, it will create an example Faq for the current date.
+
+Example:
+  $ rails generate faqmarkdown:install
+
+  This will:
+    - Create the directory `app/faqs/`.
+    - Generate an example Faq using today's date: `app/faqs/{{CURRENT_DATE}}-example-faq.markdown`.
+    - Add default routes.

data/lib/generators/faqmarkdown/usage/override.txt

@@ -0,0 +1,9 @@
+Description:
+  This generator will override either the Faq model, controller or views.
+
+Examples:
+  $ rails generate faqmarkdown:override --all        # overrides all of the things
+  $ rails generate faqmarkdown:override --controller # overrides file `app/controllers/faqs_controller.rb`
+  $ rails generate faqmarkdown:override --model      # overrides file `app/models/faq.rb`
+  $ rails generate faqmarkdown:override --views      # overrides all files in directory `app/views/faqs/`
+  $ rails generate faqmarkdown:override --theme      # overrides the layout and stylesheet

data/readme.md

@@ -0,0 +1,191 @@
+# Faqmarkdown
+
+A simple Rails FAQ engine powered by Markdown.
+
+Faqmarkdown is compatible with Rails 3 only and the gem is hosted on [RubyGems.org](http://rubygems.org/gems/faqmarkdown).
+
+## Features
+
+* Markdown files for faq
+* No database
+* RSS Feed
+* Customizable Routes
+* Built-in minimal theme (optional)
+* HTML5
+* Rails engine (so you can override models, views, controllers, etc)
+* Easily customized
+
+## Installation
+
+Simply add Faqmarkdown to your Gemfile and bundle it up:
+
+    gem 'faqmarkdown'
+
+Then, run the generator to setup Faqmarkdown for your application:
+
+    $ rails generate faqmarkdown:install
+
+The above command performs the following actions:
+
+* Create the directory `app/faqs/`. This directory is where your markdown files will live.
+* Generate an example faq using today's date, eg. `app/faqs/2011-01-01-example-faq.markdown`.
+* Add some routes. By default the routes are setup underneath the path `/faqs/*`, to customize these routes check out the Customizing Routes section below.
+
+## Usage
+
+### Generate a new Faq
+
+Here's an example of how to generate a new faq using a slug and publish date:
+
+    $ rails generate faqmarkdown:faq test-faq --date=2011-01-01
+
+The above command will create the file `app/faqs/2011-01-01-test-faq.markdown`, which you can edit and add content to.
+
+### Creating a brief summary
+
+In their markdown, place the tag below, and everything above it will appear at the summary of your faq.
+
+Tag:
+
+    <!--more-->
+
+### Faq to categories
+
+To put your faq in some categories, use:
+
+    categories:
+       - foo
+       - bar
+
+This is an Array of their categories in the faq.
+
+To list all categories, use:
+
+    faq.categories_all
+
+This will return:
+
+    ["foo", "bar"]
+
+To do a search for a particular category, do:
+
+    faq.find_by_category ('foo')
+
+This will return your faqs that have a category named `foo`.
+
+### View the faq
+
+Open `http://localhost:3000/faqs` in your browser and you should be able to navigate to your new faq. The URL for your new faq is `http://localhost:3000/faqs/2011/01/01/test-faq`.
+
+## Overriding Files
+
+The easiest way to customize the Faqmarkdown functionality or appearance is by using the override generator. This generator can copy files from the Faqmarkdown core and place them into your Rails app. For example:
+
+    $ rails generate faqmarkdown:override --all        # overrides all of the things
+    $ rails generate faqmarkdown:override --controller # overrides `app/controllers/faqs_controller.rb`
+    $ rails generate faqmarkdown:override --model      # overrides `app/models/faq.rb`
+    $ rails generate faqmarkdown:override --views      # overrides all files in directory `app/views/faqs/`
+    $ rails generate faqmarkdown:override --theme      # overrides the layout and stylesheet
+
+## RSS Feed
+
+Faqmarkdown comes prepared with a fully functional RSS feed.
+
+You can take advantage of the built-in feed by adding the feed link to your HTML head tag. For example, simply add the following to your default layout:
+
+    <head>
+      <!-- include your stylesheets and javascript here... -->
+      <%= yield :head %>
+    </head>
+
+To customize the feed title, add the following to an initializer (`config/initializers/faqmarkdown.rb`):
+
+    Faqmarkdown::Config.options[:feed_title] = 'Custom Faq Title Goes Here'
+
+To link to the feed in your app, simply use the route helper: `<%= link_to 'RSS Feed', faqs_feed_path %>`
+
+## Customizing the layout
+
+By default, Faqmarkdown will use your application's default layout, but if you wish to use a specific custom layout, you can set the following configuration in an initializer (`config/initializers/faqmarkdown.rb`):
+
+    Faqmarkdown::Config.options[:layout] = 'layout_name'
+
+### Built-in Theme
+
+Faqmarkdown comes with minimal built-in theme for your convenience.
+
+    Faqmarkdown::Config.options[:layout] = 'faqmarkdown'
+
+## Customizing Routes
+
+By default Faqmarkdown will setup all routes to go through the `/faqs/*` path. For example:
+
+    http://example.com/faqs                      # lists all faqs
+    http://example.com/faqs/2011                 # lists all faqs from 2011
+    http://example.com/faqs/2011/01              # lists all faqs from January 2011
+    http://example.com/faqs/2011/01/01           # lists all faqs from the 1st of January 2011
+    http://example.com/faqs/2011/01/01/test-faq # show the specified faq
+
+You can change the default route path by modifying the 'faqmarkdown' line in `routes.rb`. For example:
+
+    faqmarkdown :as => :faq
+
+This will produce the following routes:
+
+    http://example.com/faq                      # lists all faqs
+    http://example.com/faq/2011                 # lists all faqs from 2011
+    http://example.com/faq/2011/01              # lists all faqs from January 2011
+    http://example.com/faq/2011/01/01           # lists all faqs from the 1st of January 2011
+    http://example.com/faq/2011/01/01/test-faq # show the specified faq
+
+You can also customize the `faqs#show` route via the `:permalink_format` option:
+
+    faqmarkdown :as => :faq, :permalink_format => :day   # URL: http://example.com/faq/2011/01/01/test-faq
+    faqmarkdown :as => :faq, :permalink_format => :month # URL: http://example.com/faq/2011/01/test-faq
+    faqmarkdown :as => :faq, :permalink_format => :year  # URL: http://example.com/faq/2011/test-faq
+    faqmarkdown :as => :faq, :permalink_format => :slug  # URL: http://example.com/faq/test-faq
+
+What about mapping Faqmarkdown to root? We got you covered:
+
+    faqmarkdown :as => ''
+    root :to => 'faqs#index'
+
+## Example Directory Structure
+
+    ├── app
+    │   ├── controllers
+    │   ├── helpers
+    │   ├── mailers
+    │   ├── models
+    │   ├── faqs (where your markdown files live)
+    │   │   ├── 2011-04-01-example-1.markdown
+    │   │   ├── 2011-04-02-example-2.markdown
+    │   │   ├── 2011-04-03-example-3.markdown
+    │   │   ├── 2011-04-04-example-4.markdown
+    │   └── views
+    │       └── faqs (overridable)
+    │           ├── _feed_link.html.haml
+    │           ├── _faq.html.haml
+    │           ├── feed.xml.builder
+    │           ├── index.html.haml
+    │           └── show.html.haml
+
+## TODO
+
+* Syntax highlighting for code blocks
+* Generated routes should show example usage
+* Support more file formats, eg. textile
+* Built-in theme should have a link to the RSS Feed
+* Generator tests
+
+## Development
+
+```
+bundle
+rake appraisal:install
+rake # run the tests
+```
+
+## License
+
+MIT License. Copyright 2011 Ennova.

data/spec/helpers/faq_helper_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+
+describe FaqHelper do
+  def test_faq(file_name)
+    Faq.new(File.dirname(__FILE__) + "/../support/data/faqs/#{file_name}")
+  end
+
+  let(:summary_html) { helper.faq_summary_html(faq) }
+  let(:content_html) { helper.faq_content_html(faq) }
+
+  context 'with first faq' do
+    let(:faq) { test_faq '2011-04-01-first-faq.markdown' }
+
+    it 'renders HTML content' do
+      content_html.should be_html_safe
+      content_html.should =~ /^<p>Lorem ipsum/
+      content_html.should =~ /^<p>Duis aute irure dolor/
+    end
+
+    it 'renders HTML summary' do
+      summary_html.should be_html_safe
+      summary_html.should =~ /^<p>Lorem ipsum/
+      summary_html.should_not =~ /^<p>Duis aute irure dolor/
+    end
+  end
+
+  context 'with image faq' do
+    let(:faq) { test_faq '2011-04-28-image.markdown' }
+
+    it 'renders HTML summary' do
+      summary_html.should be_html_safe
+      summary_html.should =~ /^<p><img src=\"example.png\">/
+    end
+
+    it 'renders HTML content' do
+      content_html.should be_html_safe
+      content_html.should =~ /^<p><img src="example.png" \/>/
+    end
+  end
+
+  context 'with custom summary faq' do
+    let(:faq) { test_faq '2011-04-28-summary.markdown' }
+
+    it 'renders HTML summary' do
+      summary_html.should be_html_safe
+      summary_html.should eq '<p>This is a custom &amp; test summary.</p>'
+    end
+  end
+end

data/spec/integrations/faqs_spec.rb

@@ -0,0 +1,209 @@
+require 'spec_helper'
+
+describe 'Faq views', :type => :request do
+  before do
+    time_travel_to '2011-05-01'
+    Faq.reset!
+  end
+
+  after { back_to_the_present }
+
+  context 'Faqs#index' do
+    context 'default index' do
+      before { visit faqs_path }
+
+      it 'should show published faqs' do
+        # 2011-05-01-full-metadata (published today)
+        page.should have_content('Faq with full metadata')                # title
+        page.should have_content('Posted on 1 May 2011')                   # publish date
+        page.should have_content('by John Smith')                          # author
+        page.should have_content('This is another custom & test summary.') # summary
+
+        # 2011-04-28-summary
+        page.should have_content('A Test Faq')                      # title
+        page.should have_content('Posted on 28 April 2011')          # publish date
+        page.should have_content('This is a custom & test summary.') # summary
+
+        # 2011-04-28-image
+        page.should have_content('Image')                   # title
+        page.should have_content('Posted on 28 April 2011') # publish date
+
+        # 2011-04-01-first-post
+        page.should have_content('First Faq')                 # title
+        page.should have_content('Posted on 1 April 2011')     # publish date
+        page.should have_content('Lorem ipsum dolor sit amet') # part of summary
+      end
+
+      it 'should not show unpublished faqs' do
+        # 2015-02-13-custom-title (not published yet)
+        page.should_not have_content('This is a custom title') # title
+        page.should_not have_content('Content goes here.')     # summary
+      end
+
+      it 'should have the correct number of faqs' do
+        all('section#faqs article.faq').size.should == 4
+      end
+    end
+
+    describe 'pagination' do
+      def article_titles
+        all('article header h1').map(&:text)
+      end
+
+      before do
+        visit faqs_path(:count => 2)
+      end
+
+      it 'returns the latest faqs on the first page' do
+        article_titles.should eq [
+          'Faq with full metadata',
+          'A Test Faq',
+        ]
+      end
+
+      it 'returns earlier faqs on the second page' do
+        click_link 'Next'
+        article_titles.should eq [
+          'Image',
+          'First Faq',
+        ]
+      end
+    end
+  end
+
+  context 'Faqs#index with no faqs' do
+    it 'should show a message' do
+      time_travel_to '2010-05-01'
+      visit faqs_path
+
+      page.should have_content('No faqs found.')
+      page.should_not have_content('First Faq')
+    end
+  end
+
+  context 'Faqs#index with year' do
+    before { visit faqs_path(:year => '2011') }
+
+    it 'should show faqs inside the date range' do
+      page.should have_content('Faq with full metadata')
+      page.should have_content('A Test Faq')
+      page.should have_content('Image')
+      page.should have_content('First Faq')
+    end
+  end
+
+  context 'Faqs#index with year and month' do
+    before { visit faqs_path(:year => '2011', :month => '04') }
+
+    it 'should show faqs inside the date range' do
+      page.should have_content('A Test Faq')
+      page.should have_content('Image')
+      page.should have_content('First Faq')
+    end
+
+    it 'should not show posts outside the date range' do
+      page.should_not have_content('Faq with full metadata')
+    end
+  end
+
+  context 'Faqs#index with year, month and day' do
+    before { visit faqs_path(:year => '2011', :month => '04', :day => '01') }
+
+    it 'should show faqs inside the date range' do
+      page.should have_content('First Faq')
+    end
+
+    it 'should not show faqs outside the date range' do
+      page.should_not have_content('A Test Faq')
+      page.should_not have_content('Image')
+      page.should_not have_content('Faq with full metadata')
+    end
+  end
+
+  context 'Faqs#show' do
+    before { visit faq_path('2011/05/01/full-metadata') }
+
+    it 'should have content' do
+      page.should have_content('Faq with full metadata') # title
+      page.should have_content('Posted on 1 May 2011')    # publish date
+      page.should have_content('by John Smith')           # author
+
+      # body
+      page.should have_content('First paragraph of content.')
+      page.should have_content('Second paragraph of content.')
+    end
+
+    it 'should not show the summary' do
+      page.should_not have_content('This is another custom & test summary.')
+    end
+
+    it 'should preserve whitespace on code blocks' do
+      page.source.should match '<pre><code>First line of code.&#x000A;  Second line of code.&#x000A;</code></pre>'
+    end
+
+    it 'should allow calling Rails helpers via ERB tags' do
+      page.source.should match('<p>Paragraph created by Rails helper</p>')
+    end
+  end
+
+  context 'Faqs#feed' do
+    before { visit faqs_feed_path }
+
+    it 'should be xml format type' do
+      page.response_headers['Content-Type'].should == 'application/atom+xml; charset=utf-8'
+    end
+
+    it 'should be valid xml' do
+      lambda do
+        Nokogiri::XML::Reader(page.source)
+      end.should_not raise_error
+    end
+
+    it 'should contain the correct number of entries' do
+       Nokogiri::XML(page.source).search('entry').size.should == 4
+    end
+
+    it 'should contain an entry that is properly constructed' do
+      entry = Nokogiri::XML(page.source).search('entry').first
+
+      entry.search('title').text.should == 'Faq with full metadata'
+      entry.search('author').first.search('name').text.should == 'John Smith'
+      entry.search('author').first.search('email').text.should == 'john.smith@example.com'
+      entry.search('published').text.should == '2011-05-01T00:00:00Z'
+      entry.search('content').text == "\n      <p>First paragraph of content.</p>\n\n<p>Second paragraph of content.</p>\n\n    "
+    end
+  end
+
+  context 'Faqs#show with invalid slug' do
+    it 'should raise an not found exception' do
+      lambda do
+        visit faq_path('2011/05/01/invalid')
+      end.should raise_error(ActiveRecord::RecordNotFound)
+    end
+  end
+
+  context 'theme' do
+    before { @original_layout = Faqmarkdown::Config.options[:layout] }
+    after { Faqmarkdown::Config.options[:layout] = @original_layout }
+
+    it 'should use the application layout by default' do
+      visit faqs_path
+      page.should_not have_content('A faqmarkdown faq')
+    end
+
+    it 'should use the Faqmarkdown layout when using theme' do
+      ActiveSupport::Deprecation.silence do
+        Faqmarkdown::Config.options[:use_theme] = true
+        visit faqs_path
+        page.should have_content('A faqmarkdown faq')
+        Faqmarkdown::Config.options[:use_theme] = false
+      end
+    end
+
+    it 'should use the built-in layout when the global option is set to true' do
+      Faqmarkdown::Config.options[:layout] = 'custom_layout'
+      visit faqs_path
+      page.should have_content('A custom layout')
+    end
+  end
+end

data/spec/internal/.gitignore

@@ -0,0 +1,2 @@
+db/*.sqlite3
+log/*.log

data/spec/internal/app/faqs/2011-04-01-first-faq.markdown

@@ -0,0 +1,5 @@
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+
+<!--more-->
+
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

data/spec/internal/app/faqs/2011-04-28-image.markdown

@@ -0,0 +1,5 @@
+<img src="example.png" />
+
+<!--more-->
+
+Image description.

data/spec/internal/app/faqs/2011-04-28-summary.markdown

@@ -0,0 +1,10 @@
+---
+title: A Test Faq
+summary: This is a custom & test summary.
+---
+
+First paragraph of content.
+
+<!--more-->
+
+Second paragraph of content.

data/spec/internal/app/faqs/2011-05-01-full-metadata.markdown

@@ -0,0 +1,20 @@
+---
+title: Faq with full metadata
+author: John Smith
+email: john.smith@example.com
+summary: This is another custom & test summary.
+categories:
+  - full
+  - metadata
+---
+
+First paragraph of content.
+
+<!--more-->
+
+Second paragraph of content.
+
+    First line of code.
+      Second line of code.
+
+<%= content_tag :p, "Paragraph created by Rails helper" %>

data/spec/internal/app/faqs/2015-02-13-custom-title.markdown

@@ -0,0 +1,5 @@
+---
+title: This is a custom title
+---
+
+Content goes here.