What is this?
A static site generator, built using Node.
Why is it named Bulba?
- Bulbasaur is the best Pokemon
- There was a Bulbasaur plushie next to me when I was thinking of a name
To use Bulba, you first need to install it using npm:
npm install -g @chrishannah/bulba
Once you have Bulba installed, you need to run the
bulba init command in the directory where you want the your blog to be.
This will create an example blog, containing an example blog post, about page, and a config file.
The structure is as below:
. └── blog/ ├── content/ │ ├── about.md │ ├── posts/ │ │ └── example.md │ └── images/ │ └── image.png └── config.yaml
To generate a site using Bulba, you will need to run the
bulba generate command from the root of the blog directory.
This will then generate a static site in the directory determined from the config file, default is inside a subdirectory named
out inside your blog directory.
The outputted site will look something like this:
. └── out/ ├── assets/ │ ├── css/ │ │ └── style.css │ └── images/ │ └── image.png ├── archive.html ├── about.html ├── feed.json ├── feed.xml └── blog-post.html
A few notes on the outputted files:
- Posts will be exported to the base of the
- Required assets will be exported into the assets directory, inside subdirectories noting their type.
- An archive page will be generated with contains a list of all blog posts.
- A JSON Feed will be generated at
- A RSS2 Feed will be generated at
- The about page will be generated from the
about.mdfile located inside the content directory.
- All content inside the
content/imagesdirectory will be exported to the
assets/images/directory relative to the output directory.
Posts should be saved as
.md files, inside the
content/posts directory, with the following format:
--- title: Example post slug: example date: 2010-09-15 14:40:45 excerpt: Just an example blog post. --- Content
excerpt is optional.
To include images in blog posts, they need to be placed in the
content/images directory. Everything in this directory will be copied to the
assets/images directory, with the same folder structure.
For example, for an image named
screenshot.png, at the following location:
will be copied to the following location, relative to the output directory:
The latter is the path required to reference an image in a blog post.
Custom header content
If you want to inject custom HTML in the header in all pages, then you can do this by creating a
header.html file at the root of your blog directory.
The content of this file will then be injected into every page between the
The config file is where you configure your site information, author details, and a few extra options to customise how the site is generated.
Here is the demo config that is created after running
site: name: The name of your blog description: A description url: https://example.blog accentColour: red author: name: Your name link: https://example.blog twitter: postsPerPage: 10 numberOfPostsInFeed: 10 paths: assets: assets outputDirectory: out/ showFullContentOnIndex: true enableCodeHighlighting: true enableSearchOnArchivePage: true
- site.name: The name of your blog. Appears in the header and footer of the site, and also in the JSON feed.
- site.description: The name of your blog. Appears in the footer of the site and in the JSON feed.
- site.url: The base URL of where your blog is accessible. Used for link generation.
site.accentColour: A accent colour that is used in the theme for styling links, quotes, etc. Supports hex, rgb, and HTML colour names. Defaults to
- author.name: Used in the JSON Feed.
- author.link: Used in the JSON Feed.
- author.twitter: The full URL of your Twitter account, this will enable a Twitter icon in the footer. Optional.
- postsPerPage: This number determines how many posts to put on each of the paginated index pages.
- numberOfPostsInFeed: The number of posts that will be included in the syndicated feeds.
path.assets: The relative output directory of asset files used by the site, at the moment this is just the needed
.jsfiles needed for site generation. This is relative to the outputDirectory below.
- outputDirectory: The relative output directory for the site content.
- showFullContentOnIndex: Setting this to true will show the full blog posts content on index pages, otherwise only the excerpt will be displayed.
enableCodeHighlighting: This enables code highlighting, which is powered by highlight.js. The styles used are
atom-one-lightdepending on the system appearance. If set to false, highlight.js will not be used or linked from your pages.
Deploying the site
At the moment, Bulba is strictly a site generator and nothing else. So there are no built-in deployment tools.
My personal set up for dev.chrishannah.me is that I have a server running on Digital Ocean, where I have Bulba installed via npm. I also have a repository for my blog content, which I have checked out on the server.
So when I want to rebuild my site, or update content, I run
git pull to fetch any latest changes, then run
bulba generate to generate the site, followed by a small script that moves the generated files to the correct place.
Note: When generationg the site, Bulba will attempt to erase the contents of the configured output directory, ready to generate the fresh site. So be careful if you are customising the outputDirectory in the config file.