hbs-blog

Handlebarsjs helper to create a static blog

Install

The best way to install this module is by npm:
npm install hbs-blog

hbs-blog on npm

Handlebarsjs helper

Article list

The article list helper gives you the possibility to render a list from documents, within a given folder. Documents which should be listed needs a FrontMatter header.
The helper reads and provides the following data:

• index
• headline
• subline
• author
• date
• dateCode
• tags
• lang
• intro (read from a html with id intro-text)
• link (this is the link to the document)
• sticky (is used for position of the article within the article list)
• previewImage

If the helper has parameter for respect sticky set to true it will put the articles, which have set the property sticky: true within Front-Matter data, to the beginning of the list.

Example

    {{#articleList '[base folder like ./src/]' '[folder of blog posts like posts/]' [respect sticky:true|false]}}
      <div>
        {{headline}}
        {{author}}
        ...
      </div>
    {{/articleList}}

Sticky list (see Article list)

The sticky list is a wrapper for the article list, which gives back only sticky articles (articles which have sticky: true property within Front-Matter header).

Example

    {{#stickyList '[base folder like ./src/]' '[folder of blog posts like posts/]'}}
      <div>
        {{headline}}
        {{author}}
        ...
      </div>
    {{/stickyList}}

Tag navigation

The tag navigation helper walks through all files given in defined folder and reads the tags property from FrontMatter to generate a list of all available tags.

• title (title of the tag)

Example

<h3>Filter blog posts by tags:</h3>
<ul class="tags">
    {{#tagNavigation blog.post.folder}}
    <li class="tags__item"><a href="#{{title}}">{{title}}</a></li>
    {{/tagNavigation}}
</ul>

Markdown

The Markdown helper uses Remarkable to format markdown code to html. Yet not settings are added and be aware that, if there is a newline at the beginning of you text, the output will be messed up. Therefore, start your first line directly after the helper placeholder.

Example

{{#markdown}}#your markdown text{{/markdown}}

Format tags

The Format Tags helper takes a comma separated list of tags and render them with the given html code.

• tag (tagname)

Example

<ul class="tags">
    {{#formatTags tags}}
    <li class="tags__item">{{tag}}</li>
    {{/formatTags}}
</ul>

Format time (uses moment.js)

The Format time helper transform a date into a user-friendly format. It uses the moment.js library.

The date and format parameters are documented respectively here and here.

Example 1

{{formatTime date format}}

Example 2

<time datetime="{{formatTime date "YYYY-MM-DD"}}">{{formatTime date "DD.MM.YYYY"}}</time>

Document Data Module (uses FrontMatter)

The document data module extends the data object with useful information which you can directly use as handlebarsjs variables. The main purpose is to push the FrontMatter properties into the data object but it also has system properties.

System properties:

• relativePath (provides the path to the file)

Reading FrontMatter data from a document

In order to read data from a document use lib/read-document-data. It takes the document content as string and, if wanted, the data property name, which should be returned. If you don't pass the property name it will return all FrontMatter attributes, which can be read from the document.

Gulp usage of document data

To read FrontMatter data from the document in the pipe, use gulp/load-document-data. It will read the data and pass it into the object file.data which can be accessed with handlebar placeholders. After processing with handlebars you should trigger remove-document-data what will remove the FrontMatter data from the output.

Example:

gulp.task('hbs', function () {
  return gulp.src('./src/**/*.html')
    .pipe(loadDocumentData())
    .pipe(handlebars(pageConfig, options))
    .pipe(removeDocumentData())
    .pipe(gulp.dest('web'))
})