beulogue

beulogue [\bøloɡ\]: french for blog.

An almost configuration-less static blog generator.

• Install
• Features
  • Files organization
  • Markdown
  • Tags
  • Templating
  • RSS
  • Sitemap
• References
• Last things
• Versioning
• License

Install

Requires node >= 6 ! (ES6 inside !).

npm install -g beulogue

You can also

yarn global add beulogue

You can now run beulogue. Enjoy !

The available command-line flags are:

• base: set the remote host (http://whatever.com) for sitemap.xml generation
• rss-title: set the title for the rss feed
• rss-description: set the description for the rss feed
• help: to get some help about the commands
• uninstall: remove beulogue :'(
• version: to get beulogue version

Features

A few things:

• HTML templates are compiled using ejs.
• Sitemap will not be generated if the base command line option is absent

Files organization

This is the structure used to generate your site:

my-site/
  posts/ (your posts)
    assets/ (your images...)
      shy-blatter-cat.jpg
    2015-10-27-foo.md
    2015-11-02-first.md
    2015-11-03-shit-happens.md
    about-me.md
  templates/
    base.ejs (the base template)
    home.ejs (the home page template)
    post.ejs (the template for the body)

• Assets:
  • In the posts/assets folder
• Home:
  • The template must be templates/home.html.
• Posts:
  • In markdown format
  • In the posts folder
  • The template must be templates/post.html.

So from the folder my-site, run:

beulogue

The site will be in the output folder.

Markdown

Learn about markdown here.

beulogue uses front-matter. All front-matter data is available in the templates under the attributes variable. It allows you to add, for example:

• a title
• an author
• a date

Please note that these value are not mandatory ! For example, the title will be, in order:

• the value from the front-matter
• the value extracted from the markdown
• the filename

There are more options !

You can use the following options:

• draft: true to tell beulogue that a page is a draft.
• static: true to tell beulogue that a page is a static page.
• urlpath: my simple title: if your title is too long, you can use this to create a nicer url

draft and static currently have the same effect (the html is rendered but not added to the navigation).

Tags

beulogue now comes with tag support.

Use your markdown front matter to add them:

---
title: Wow, much tags !
date: 2015-12-21
tags: news, release
---

# Release 3.4.0

- Add tags support !

And beulogue will generate the following pages:

• news.html
• release.html

With the link to related posts.

Don't forget to create the tag.html template ;-)

Templating

beulogue uses ejs.

You have access to another variable: attributes (it comes from your markdown front matter).

RSS

beulogue can generate your rss.xml file, which will be at the root of your output folder.

Calling beulogue with the base, rss-title and rss-description flags is mandatory to generate the sitemap (eg. beulogue base=http://my-site).

beulogue creates something like this:

<?xml version="1.0"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>ehret.me</title>
    <description>Hi! I am Siegfried. I am a developer. I like burgers. I'm curious and I love the open web.</description>
    <link>https://ehret.me</link>
    <item>
      <title>ng-semver</title>
      <guid>https://ehret.me/ng-semver.html</guid>
      <link>https://ehret.me/ng-semver.html</link>
      <pubDate>Thu, 15 Dec 2016 00:00:00 GMT</pubDate>
    </item>
  </channel>
</rss>

where each item element represents one of your blog posts.

RSS generation uses the following front-matter elements to populate items:

• title: the title of the post
• description: the description of the post
• author: the author of the post

Sitemap

beulogue can generate your sitemap.xml file, which will be at the root of your output folder.

Calling beulogue with the base flag is mandatory to generate the sitemap (eg. beulogue base=http://my-site).

beulogue creates something like this:

<?xml version="1.0"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
  <url>
    <loc>http://ehret.me/to-2016-and-beyond.html</loc>
    <lastmod>2016-01-01</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.8</priority>
  </url>
</urlset>

where each url element represents one of your blog posts.

Default and custom values

Each url has default values for its children elements:

loc

Provides the full URL of the page or sitemap, including the protocol (e.g. http, https) and a trailing slash, if required by the site's hosting server.

The base flag is used. The resulting value is /<post.filename>.

lastmod

The date that the file was last modified, in ISO 8601 format.

You can use front-matter in your posts:

• sitemapLastmod if present
• date (used in blog posts) otherwise

changefreq

How frequently the page may change:

• always
• hourly
• daily
• weekly
• monthly
• yearly
• never

You can use front-matter in your posts:

• sitemapChangefreq: with the value you want
• default value: monthly

priority

The priority of that URL relative to other URLs on the site.

You can use front-matter in your posts:

• sitemapPriority: with the value you want
• default value: 0.5

References

• http://www.sitemaps.org
• https://en.wikipedia.org/wiki/Sitemaps

Last things

Need something? Create an issue !

Ideas:

• [x] Add date and author somewhere (markdown front matter ? properties file ?) => front matter
• [ ] Prev/next post ? (I actually don't care about this)
• [ ] Plugins ? (less/sass and stuff ?)
• [x] Tags ?

Versioning

beulogue was using semantic versioning in its early days.

Since semver does not mean anything to a lot of people, I decided to abandon it and use the Fibonnacci Versioning (FibVer).

FibVer is still making its way in my head, this may change.

Basically, it is like semantic versioning, using a MAJOR.MINOR.PATCH pattern, except that:

• MAJOR is an alias to «You will have to change your code to use this new version»
• MINOR is an alias to «Hey, I am still ok for you, but here is something nice you may be interested in»
• PATCH is an alias to «I fucked up, here is a fix for you buddy»
• Each number should belong to the Fibonnacci sequence (because why not ?!)
• Once you have bump a number under a major, do not reset it. This reflects that the release contains patches and features, instead of meaninglessly being a nice x.x.0 patchless program.

License

MIT © Siegfried Ehret