A Github/Asciidoc Powered Blog Engine for Rails 4
Ruby AGS Script CSS JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
app
config
db/migrate
lib
script
spec
.gitignore
.rspec
.ruby-gemset
.ruby-version
Gemfile
MIT-LICENSE
README.asc
Rakefile
blogdiggity.gemspec

README.asc

Blogdiggity - A Rails Blog Engine Powered by GIT and Asciidoc

Blogdiggity - GIT and Asciidoc Powered Rails Blog Engine

Blogdiggity is a minimalist Rails Blog powered by Git (Github in particular) and Asciidoc. The premise behind Blogdiggity is that you should never have redeploy your app to add, modify or delete blog entries. We (the Integrallis Team) are sick of dealing with database-driven blog engines. In most cases they are slow and bloated and try to become mini-application frameworks which ends up feeling pretty invasive. Blogdiggity deals with one format and one format only; AsciiDoc (http://www.methods.co.nz/asciidoc/). When you add, remove or make changes to an article on the repo, those changes are automatically reflected on your site using the magic of Github post receive hooks (https://help.github.com/articles/post-receive-hooks). Articles are never stored on your app’s db. They are read directly from the repo, rendered into HTML using AsciiDoctor (https://github.com/asciidoctor/asciidoctor) and cached until a post receive hook invalidates the cache, making page loads very fast!

Status

Codeship Status for integrallis/blogdiggity Code Climate

1. AsciiDoc (Markdown on Steroids)

"AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user."

2. Installation

2.1. Register a Github Developer Application

2.2. Set Github environment variables (alternatives provided)

2.2.1. Set Environment using Figaro

(https://github.com/laserlemon/figaro) Add /config/application.yml with the following contents:

GITHUB_KEY: xxxxxxxxxxx
GITHUB_SECRET: xxxxxxxxxx

2.2.2. Configure Foreman Environment (if using foreman)

  • Create a Foreman .env file at the root of the project with you Github Credentials to be able to use OAuth

GITHUB_KEY=xxxxx
GITHUB_SECRET=xxxxx

2.2.3. (Alternative) Configure the environment variables on Heroku:

/>heroku config:add GITHUB_KEY='xxxxx'
/>heroku config:add GITHUB_SECRET='xxxxx'

2.3. Add the blogdiggity gem to your Gemfile & bundle:

gem 'blogdiggity', '~> 0.1.0'

2.4. Install the migrations:

/>rake blogdiggity:install:migrations

2.5. Install Blogdiggity as an mountable engine

on your Rails application by modifying your routes file:

Rails.application.routes.draw do
  mount Blogdiggity::Engine => "/blog", as: "blog"
end

2.6. Engine Asset Precompilation (needed for Heroku)

To successfully precompile assets (this is also needed if you’re deploying in Heroku) add:

config.assets.precompile += ['blogdiggity/blogdiggity.css', 'blogdiggity/blogdiggity.js']

to config/application.rb

3. Adding Article Repos

Blogdiggity provides a few admin views that you will use to configure which repositories contain articles to be published.

3.1. /contributors

This admin page allows an author to register as a contributor to the blog.

  • Select "Join As Contributor w/ Github" Join As a Contributor

  • After the OAuth song and dance you should see your Github repositories Contributor Repositories

  • Find repositories containing AsciiDoc articles and click the "Add" button Adding a Repository

Sample repos (that can be forked for testing) are available at:

3.2. /pages

  • Browse the available articles at /pages Browsing a Repository

  • A link is provided to navigate to each article Viewing an Article

Warning
These administrative views are not protected, it is up to you to apply authentication/authorization by whatever means your app provides.

4. Viewing Articles

<% Blogdiggity::Page.each do |page| %>
<tr>
  <td><%= page.title %></td>
  <td><%= link_to "/#{page.slug}", page.slug %></td>
</tr>
<% end %>

5. Article Listings by Date

5.1. /:year ⇒ /pages/2013

List all articles for the given year

5.2. /:year/:month ⇒ /pages/2013/03

List all articles for the given year and month

5.3. /:year/:month/:page ⇒ /pages/2013/03/my-article

Display article :page for the given month and year

6. Sitemap

  • Automatically available at /pages.xml

  • Consistent with the Sitemap 0.9 (http://www.sitemaps.org/) protocol specification

7. Other Assets

Coming soon! Other assets relative to the page (images / pdfs / etc) are extracted and cached on Amazon S3. The same cache invalidation mechanism is used to refresh the external S3 assets

8. Testing Webhooks

I’ve used proxylocal (https://proxylocal.com) to expose local application to the outside world.

$ proxylocal 3000
Local server on port 3000 is now publicly available via:
http://fp9k.t.proxylocal.com/