Nuclear Pumpkin Mocha

    beulogue

    34.0.0 • Public • Published

    beulogue

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

    An almost configuration-less static blog generator.

    NPM

    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

    Last things

    Need something? Create an issue !

    Ideas:

    • 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 ?)
    • 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

    Install

    npm i beulogue

    DownloadsWeekly Downloads

    16

    Version

    34.0.0

    License

    MIT

    Last publish

    Collaborators

    • siegfriedehret