Narcoleptic Possum Mob

    blogd

    0.2.5 • Public • Published

    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:

    keydefaultdescription
    host'127.0.0.1'Binded host
    port5555Binded 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

    MethodRouteParamsDescription
    GET/postslimit 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/:tagtag: 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/:slugslug: a post's slugRetrieve a single post
    GET/tags_none_Retrieve the list of available tags
    GET/authors_none_Retrieve the list of authors
    GET/authors/:slugslug: slug or email of an authorRetrieve an author
    GET/authors/:slug/postsslug: slug or email of an authorRetrieve 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": "vincent.bouzeran@elao.com"
    },{
        "name":  "Guewen",
        "slug":  "guewen",
        "email": "guewen.faivre@elao.com"
    }]
    

    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:

    MetaDescription
    _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":"			vincent.bouzeran@elao.com",
        "publish_at":			"2014-07-06"
    }
    

    TODO

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

    Install

    npm i blogd

    DownloadsWeekly Downloads

    4

    Version

    0.2.5

    License

    none

    Last publish

    Collaborators

    • nervo