"Camel" is a blogging platform written in Node.js. It is designed to be fast, simple, and lean.

Design Goals

More specifically, the design goals were:

Easy posting using Markdown
Basic metadata, stored in each file
Basic templating, with a site header/footer and post header stored separately from content
Extremely quick performance, by caching rendered HTML output
Support for two RSS feeds:
- The default one, where link posts open on the target website
- The alternate feed, where link posts open on this website
Optional automatic posts to Twitter

Approach

Camel is neither a static blogging platform nor a truly dynamic one. It is a little from column A, and a little from column B. The first time a post is loaded, it is rendered by converting from Markdown to HTML, and then postprocessed by adding headers & footer, as well as making metadata replacements. Upon a completed render, the resultant HTML is stored and used from that point forward.

Usage

Installation

Install Node & npm
Clone the repository
Get all the dependencies using NPM: npm install
node ./camel.js or using npm start

Configuration

There's a group of "statics" near the top of the file
The RSS parameters in the generateRss function will need to be modified.
The headers/footers:
- header.html - site header; shown at the top of every page
- footer.html - site footer; shown at the bottom of every page
- defaultTags.html - default metadata; merged with page metadata (page wins)
- postHeader.html - post header; shown at the top of every post not marked with @@ HideHeader=true. See below.
- rssFooter.html - RSS footer; intended to only show anything on the bottom of link posts in RSS, but is appended to all RSS entries.
It's worth noting there are some Handlebars templates in use:
- index.md
  - @@ DayTemplate - used to render a day
  - @@ ArticlePartial – used to render a single article in a day
  - @@ FooterTemplate - used to render pagination
- postHeader.html - placed on every post between the site header and post content
- rssFooter.html - placed on the bottom of every RSS item
If you'd like to have Camel post to Twitter, set four environment variables (see below)
If you'd like to support endpoints that require basic auth, set two environment variables (see below).

Environment Variables

You can define ENV variables used by Camel in one of the following ways:

Heroku admin panel
export function in bash/zsh shells.
.env file - use .env.example as a starting point

Files

To use Camel, the following files are required:

Root
+-- camel.js
|   Application entry point
+-- package.json
|   Node package file
+-- templates/
|     +-- defaultTags.html
|     |   Site-level default tags, such as the site title
|     +-- header.html
|     |   Site header (top of every page)
|     +-- footer.html
|     |   Site footer (bottom of every page)
|     +-- postHeader.html
|     |   Post header (top of every post, after the site header. Handlebars template.)
|     `-- rssFooter.html
|         RSS footer (at the end of every RSS item)
+-- public/
|     `-- Any static files, such as images/css/javascript/etc.
`-- posts/
    All the pages & posts are here. Pages in the root, posts ordered by day. For example:
    +-- index.md
    |   Root file; note that DayTemplate, ArticlePartial, and FooterTemplate are
    |   all Handlebars templates
    +-- about.md
    |   Sample about page
    +-- 2014/
    |   Year
    |     +-- 4/
    |     |   Month
    |     |   +-- 29/
    |     |   |   Day
    |     |   |    `-- some-blog-post.md
    |     |   `-- 30/
    |     |        +-- some-other-post.md
    |     |        `-- yet-another-post.md
    |     `-- 5/
    |         +-- 1/
    |         |   `-- newest-blog-post.md
    |         `-- 5/
    |             `-- some-cool-website.redirect
    `-- etc.

For each post, metadata is specified at the top, and can be leveraged in the body. For example:

@@ Title=Test Post
@@ Date=2014-05 17:50
@@ Description=This is a short description used in Twitter cards and Facebook Open Graph.
@@ Image=http://somehost.com/someimage.png

This is a *test post* entitled "@@Title@@".

The title and date are required. Any other metadata, such as Description and Image, is optional.

As of version 1.5.3, you can optionally use MultiMarkdown-style metadata. If you choose to use that style, the above would be:

Title: Test Post
Date: 2014-05 17:50
Description: This is a short description used in Twitter cards and Facebook Open Graph.
Image: http://somehost.com/someimage.png

This is a *test post* entitled "@@Title@@".

Note, however, that MultiMarkdown's support for multiline metadata is not supported. Each metadata item must be wholly contained on its own line.

Link Posts

As of version 1.3, link posts are supported. To create a link post, simply add a Link metadata item:

@@ Title=Sample Link Post
@@ Date=2015-02-06 12:00
@@ Link=http://www.vt.edu/

This is a sample *link* post.

The presence of a Link metadata item indicates this is a link post. The formatting for link and non-link post headers is controlled by the postHeader.html template.

In the RSS feed, the link for a link post is the external link. Thus, rssFooter.html is used to add a permalink to the Camel site at the bottom of each link post. It is important to note that this footer is shown on every post; it is up to the footer to decide whether or not to show anything for the post in question. The example included in this repo behaves as intended.

Redirects

As of version 1.1, redirects are supported. To do so, a specially formed file is placed in the posts/ tree. The file should have two lines; the first should be the status code of the redirect (301 or 302). The second line should be the target URL.

Suppose you wanted to redirect /2014/12/10/source to /2014/12/10/destination. You will add the file /posts/2014/12/10/source.redirect; it will contain the following:

302
/2014/12/10/destination

Redirects to both internal and external URLs are supported. Providing an invalid status code will result in that status code being used blindly, so tread carefully.

Automatic tweets

As of version 1.4, Camel can automatically tweet when a new post is discovered. This requires a custom app to be set up for your blog; you can set this up at Twitter. To enable, specify four environment variables to correspond to those Twitter issues:

TWITTER_CONSUMER_KEY
TWITTER_CONSUMER_SECRET
TWITTER_ACCESS_TOKEN
TWITTER_TOKEN_SECRET

Additionally, a couple of variables up at the top of the file need to be set:

twitterUsername - the username of the Twitter account that will be tweeted from.
twitterClientNeedle - a portion of the client's name

Upon startup, and when the caches are cleaned, Camel will look at the most recent tweets by the account in question by the app with a name that contains twitterClientNeedle. It will look to see the most recent URL tweeted. If the URL does not match the most recent post's URL, then a tweet is fired off.

Authentication

As of version 1.5.0, basic authentication is supported. It is selectively used on individual routes in order to provide a small barrier for entry for administrative tasks, most specifically, rendering a draft post. Naturally, basic auth is an inherently insecure protection mechanism; it is provided simply to prevent drive-bys.

To enable basic authentication, two environment variables are required:

AUTH_USER_NAME
AUTH_PASSWORD

By default, the /render-draft endpoint requires basic auth to actually render a draft post.

Quirks

There are a couple of quirks, which don't bother me, but may bother you.

Adding a Post

When a new post is created, if you want an instant refresh, you'll want to restart the app in order to clear the caches. There is a commented out route /tosscache that will also do this job, if you choose to enable it.

Otherwise, the internal caches will reset every 30 minutes.

Additionally, there is no mechanism within Camel for transporting a post to the posts/ directory. It is assumed that delivery will happen by way of a git push or equivalent. That is, for example, how it would work when run on Heroku.

Note that as of 19 November 2014, Heroku now supports integration with Dropbox, which makes it much easier to post to Camel while mobile.

Pagination

Camel uses a semi-peculiar pagination model which is being referred to as "loose pagination". Partly due to laziness, and partly because it seems better, pagination isn't strict. Rather than always cutting off a page after N posts, instead, pagination is handled differently.

Starting with the most recent day's posts, all the posts in that day are added to a logical page. Once that page contains N or more posts, that page is considered complete. The next page is then started.

Therefore, all the posts in a single day will always be on the same page. That, in turns, means that pages will have at least N posts, but possibly more. In fact, a single page could have quite a few more than N posts if, say, on one lucrative day there are 1.5N or 2N posts.

Pagination is only necessary on the homepage, and page numbers are 1-based. Pages greater than 1 are loaded by passing the query string parameter p. For example, hostname/page/3 for page 3.

Status

Camel is functional, and is presently running www.caseyliss.com. There are lots of features that probably could be added, but none that I'm actively planning.

Branches

There is a branch, postuploads, that allows for posts to be uploaded via the same mechanism as making a draft. This isn't useful for www.caseyliss.com, due to the way that Camel is hosted, but may be useful for others.

License

Camel is MIT-Licensed.

While by no means neccessary, I'd very much appreciate it if you provided a link back to either this repository, or my website, on any sites that run Camel.

Change Log

1.5.7 Fix bug wherein RSS caching could get confused if multiple hostnames are used to access the site.
1.5.6 Fix bug wherein a Description that contains a " would not be escaped, and thus would prematurely truncate twitter:description and og:descripton tags.
1.5.5 Fix bug in /render-draft where each line had a double carriage return. This caused metadata to not be picked up properly, and thus the post not render properly. In turn, that defeated most of the purpose of draft support in the first place.
1.5.4 Fix bug wherein a MultiMarkdown-style metadata line that contained a URL with a query string caused a crash.
1.5.3 Adds support for MultiMarkdown-style metadata. Previous-style metadata (prefix with @@) is still supported.
1.5.2 Prevent display of posts dated in the future.
1.5.1 Add ability to define ENV variables using a .env file.
1.5.0 Add /render-draft route with basic authentication.
1.4.8 Fix broken auto-tweeter.
1.4.7 Tweak postRegex to allow for posts that have trailing + in their name, such as this one
1.4.6 Change deep homepage pages to /page/N instead of /?p=N. Maintains support for original, query string based URLs. Upgrade to latest version of packages.
1.4.5 Fix auto-tweeter not considering too-long titles (issue #21)
1.4.4 Add support for Facebook Open Graph.
1.4.3 Add support for Twitter cards; thanks to @tofias for the help.
1.4.2 Now provides for /rss-alternate, which points link posts to internal links instead of external ones.
1.4.1 Refactored to satisfy JSLint. Fixed issue where a day that only had a redirect in it caused duplicate day breaks to show on the homepage.
1.4.0 Added support for auto-tweeting.
1.3.1 Updated RSS feed such that link posts open the external link, and have a "Permalink" to the site is shown at the bottom of the post.
1.3.0 Added link posts.
1.2.1 Significant cleanup/restructuring. Now less embarrassing! Removal of lots of similar-sounding functions and more liberal use of data that we've already collected in allPostsSortedAndGrouped().
1.2.0 Changes from marked to markdown-it, adds support for footnotes.
1.1.0 Fix post regex issue, adds support for redirects, adds /count route, prevents year responses for unreasonable years
1.0.1 Adds x-powered-by header, upgrades to packages
1.0.0 Initial release

jwindmuller / camel