blogd

Blogd

Blogd allow you to retrieve blog's posts and meta from a folder, a git repository or a remote zip and expose them via an API. It's useful when you want to manage a collaborative blog with github for example. Blogd is maintained by http://www.elao.com and is use at http://www.elao.com/blog. The content repository of the blog is located at http://www.github.com/elao/tech-blog.

Configuration

Add a config.js file (copy / past the config.js.dist for example). Or you can also define a blogd config key in your package.json file (or in ../../package.json file).

Example of config.js file

'use strict';

exports.port          = process.env.PORT || 5555;
exports.host 		 = '127.0.0.1';
exports.store         = 'memory'; // or memory
exports.outputFolder  = __dirname + "/content";
exports.backupFile    = __dirname + "/current.json";
exports.assetsToCopy  = [{
    from: exports.outputFolder + "/posts/images/",
    to:   __dirname + "/public/images",
    url: "/images/"
}];

exports.security = {
    rules: {
        guest:  {},
        admin:  {}
    },
    basic: {
        realm:    'Blogd Private Api',
        user:     'admin',
        password: 'private'
    }
};

exports.source = {
    type:        'zip',
    url:         'https://github.com/Elao/tech-blog/archive/master.zip'
}

Available configuration options:

key	default	description
host	'127.0.0.1'	Binded host
port	5555	Binded port
store	'memory'	The store to use to store the blog data (only 'memory' is supported now)
outputFolder	'./content'	The folder where to dump the grabbed content
backupFile	'./current.json'	Path of the file where consolidated json data should be backed up
assetsToCopy	[]	array of folder to copy and/or map. The object should contains: __from__ : The folder to copy (*required*) __to__ : The destination folder (*required*) __url__ : The absolute url to bind the folder (if none, it'll not be mapped)
source	no default.	Where to find the content. __type__ : The type of source (folder, git, zip) __url__ : The url of the zip file (for the *type zip*) __folder__ : The folder to get data from (for the *type folder*) __repository__ : The url of the git repository (for the *type git*)

API

Method	Route	Params	Description
GET	/posts	limit The number of posts to retrieve offset The offset status Filter by post status	Retrieve list of blog's post ordered by publish date desc
GET	/posts/:tag	tag: a tag limit The number of posts to retrieve offset The offset status Filter by post status	Retrive list of blog's post by tag
GET	/post/:slug	slug: a post's slug	Retrieve a single post
GET	/tags	_none_	Retrieve the list of available tags
GET	/authors	_none_	Retrieve the list of authors
GET	/authors/:slug	slug: slug or email of an author	Retrieve an author
GET	/authors/:slug/posts	slug: slug or email of an author	Retrieve list of posts from given author
GET	/status	_none_	Retrieve the content status (last update, number of tags, posts, authors, ...)
GET	/refresh	_none_	Force the refresh of the data by retrieving the remote data from the source

Assets mapping

In your config, you can define mapped directories from your source, to a folder and an url. For example:

exports.assetsToCopy  = [{
    from: exports.outputFolder + "/posts/images/",
    to:   __dirname + "/public/images",
    url: "/images/"
}];

Blogd will copy the content of /posts/images/ from your repository, to the Blogd local directory /public/images and then map the /public/images/ folder to the url /images/ For example, if you have a file /posts/images/myimage.png in your repository, you'll be able to access the file to http://localhost:5555/images/myimage.png

Content structure

The content of the source must be structured this way (you can find an example at https://github.com/Elao/tech-blog)

##Users file: Must be at the root of the repo and named users.json

Example of users.json file:

[{
    "name":  "Vincent",
    "slug":  "vincent",
    "email": "[e-mail]"
},{
    "name":  "Guewen",
    "slug":  "guewen",
    "email": "[e-mail]"
}]

##Tags file: Must be at the root of the repo and be named tags.json It contains the allowed tags used in posts. If a post use a tag not referenced in these file, the tag will be ignored. Properties label and slug on tag objets are mandatory, but you can add other metas and you'll get them back through the API.

Example of tags.json file:

[
    {"label": "Symfony", "slug": "symfony"},
    {"label": "HTML/CSS", "slug": "html-css"},
    {"label": "Webdesign", "slug": "webdesign"},
    {"label": "Framework", "slug": "framework"},
    {"label": "Translation", "slug": "translation"},
    {"label": "Form", "slug": "form"},
    {"label": "Theming", "slug": "theming"},
    {"label": "Linux", "slug": "linux"},
    {"label": "Tips", "slug": "tips"},
    {"label": "Talk", "slug": "talk"},
    {"label": "PHP", "slug": "php"}
]

##Posts file: The post files must be placed in the /posts folder. Each post must have two files: a markdown file and a meta file.

For each post, you need to have 2 files in the /posts folder

• The .md file that should contains the markdown content of the post
• The .meta file that should contains the meta data for the article.

The two files must have the same name except the extension.

Example:

If your post is named "mysuperblogpost", you must have these two files in the /posts folder:

• mysuperblogpost.md (hold the markdown content of the post)
• mysuperblogpost.meta (hold the metas of the post)

##Post meta file The post meta file contains information about the associated blog post.

The metas are like this:

Meta	Description
_slug_ \*	The post's slug (used to identify the post. Must be unique among all posts)
_title_ \*	The post's title
_tags_	List of post's tag (must be reference by slug or label of tags contains in the tags's file)
_status_ \*	The post's status ("published", "draft")
_publish_by_ \*	The publisher of the post (must be the reference of a user contains in the users's file either by email or slug)
_publish_at_ \*	A date (any format supported by Moment.js)
_meta_title_	The html meta title of the post
_meta_description_	The html meta description of the post

* indicate required metas

Additional metas will be exposed by the blogd api.

Example of a post meta file:

{
    "tags":	           		["Symfony2", "Toto", "Titi"],
    "title":				"My super post from a nice repository",
    "slug":					"my-super-post-from-a-nice-repository",
    "status":				"published",
    "meta_title":			"Imported post from a repository",
    "meta_description":		"A super amazing post about everything",
    "publish_by":"			[e-mail]",
    "publish_at":			"2014-07-06"
}

TODO

• Add more checks on data
• Add pagination on /posts/:tag & /authors
• Add a redis store