README.asc
Blogdiggity - A Rails Blog Engine Powered by GIT and Asciidoc
=============================================================
Brian Sam-Bodden <bsbodden@integrallis.com>
v1.0, 3-2013
:source-highlighter: pygments
:numbered!:
:showcomments:
[abstract]
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
------
image:https://codeship.io/projects/a6872b20-0aac-0132-e493-4e10f3c475e5/status["Codeship Status for integrallis/blogdiggity", link="https://codeship.io/projects/31832"]
image:https://codeclimate.com/github/integrallis/blogdiggity/badges/gpa.svg["Code Climate",link="https://codeclimate.com/github/integrallis/blogdiggity"]
:numbered:
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."
Installation
------------
Register a Github Developer Application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Visit https://github.com/settings/applications to register your application. Select "Register new application"
* Set "Callback URL" to http://<your-site>/auth/github/callback
Set Github environment variables (alternatives provided)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set Environment using Figaro
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(https://github.com/laserlemon/figaro)
Add /config/application.yml with the following contents:
[source,ruby]
-------------------------------------------
GITHUB_KEY: xxxxxxxxxxx
GITHUB_SECRET: xxxxxxxxxx
-------------------------------------------
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
[source,shell]
-------------------------------------------
GITHUB_KEY=xxxxx
GITHUB_SECRET=xxxxx
-------------------------------------------
(Alternative) Configure the environment variables on Heroku:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[source,shell]
-------------------------------------------
/>heroku config:add GITHUB_KEY='xxxxx'
/>heroku config:add GITHUB_SECRET='xxxxx'
-------------------------------------------
Add the blogdiggity gem to your Gemfile & bundle:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[source,ruby]
-------------------------------------------
gem 'blogdiggity', '~> 0.1.0'
-------------------------------------------
Install the migrations:
~~~~~~~~~~~~~~~~~~~~~~~
[source,shell]
-------------------------------------------
/>rake blogdiggity:install:migrations
-------------------------------------------
Install Blogdiggity as an mountable engine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
on your Rails application by modifying your routes file:
[source,ruby]
-------------------------------------------
Rails.application.routes.draw do
mount Blogdiggity::Engine => "/blog", as: "blog"
end
-------------------------------------------
Engine Asset Precompilation (needed for Heroku)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To successfully precompile assets (this is also needed if you're deploying in Heroku) add:
[source,ruby]
-------------------------------------------
config.assets.precompile += ['blogdiggity/blogdiggity.css', 'blogdiggity/blogdiggity.js']
-------------------------------------------
to config/application.rb
Adding Article Repos
--------------------
Blogdiggity provides a few admin views that you will use to configure which repositories contain articles to be published.
/contributors
~~~~~~~~~~~~~
This admin page allows an author to register as a contributor to the blog.
* Select "Join As Contributor w/ Github"
image:https://blogdiggity-wiki.s3.amazonaws.com/blogdiggity-04.png[width=640,alt="Join As a Contributor",border-width=1]
* After the OAuth song and dance you should see your Github repositories
image:https://blogdiggity-wiki.s3.amazonaws.com/blogdiggity-05.png[width=640,alt="Contributor Repositories",border-width=1]
* Find repositories containing AsciiDoc articles and click the "Add" button
image:https://blogdiggity-wiki.s3.amazonaws.com/blogdiggity-06.png[width=640,alt="Adding a Repository",border-width=1]
Sample repos (that can be forked for testing) are available at:
- https://github.com/bsbodden/another-asciidoc-blog
- https://github.com/bsbodden/sample-blog
/pages
~~~~~~
* Browse the available articles at /pages
image:https://blogdiggity-wiki.s3.amazonaws.com/blogdiggity-08.png[width=640,alt="Browsing a Repository",border-width=1]
* A link is provided to navigate to each article
image:https://blogdiggity-wiki.s3.amazonaws.com/blogdiggity-09.png[width=640,alt="Viewing an Article",border-width=1]
WARNING: These administrative views are not protected, it is up to you to apply authentication/authorization by whatever means your app provides.
Viewing Articles
----------------
// We need view helpers
[source,ruby]
-------------------------------------------
<% Blogdiggity::Page.each do |page| %>
<tr>
<td><%= page.title %></td>
<td><%= link_to "/#{page.slug}", page.slug %></td>
</tr>
<% end %>
-------------------------------------------
Article Listings by Date
------------------------
/:year => /pages/2013
~~~~~~~~~~~~~~~~~~~~~
List all articles for the given year
/:year/:month => /pages/2013/03
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
List all articles for the given year and month
/:year/:month/:page => /pages/2013/03/my-article
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Display article :page for the given month and year
// we will need to deal with name collisions
Sitemap
-------
* Automatically available at /pages.xml
* Consistent with the Sitemap 0.9 (http://www.sitemaps.org/) protocol specification
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
Testing Webhooks
----------------
I've used proxylocal (https://proxylocal.com) to expose local application to the outside world.
[source,console]
--------------------------------------------------------
$ proxylocal 3000
Local server on port 3000 is now publicly available via:
http://fp9k.t.proxylocal.com/
--------------------------------------------------------