🏡 meblog
A simple blog engine for personal blogging
Website: meblog.sinzii.me
Table of contents
- Have a quick taste
- Features
- Template project structure
- How to create new post
- Preview your post while editing
- Configuration
- Template variables
- Event hooks
- I18n
- Deploy your site on Github
- Websites built with meblog
- Contribution
- License
Have a quick taste
npm install --save meblog
npx meblog init
npx meblog sample --number-of-posts=20
npx meblog serve
Features
- Simple and fast as you always want.
- Edit the code or posts and see the change immediately with the support of browser-sync.
- Support different styles of post url.
- Built-in static site generator for pages, posts and tag pages.
- Built-in RSS feed generator
- Support event hooks to customize build process
- Support i18n out-of-the-box
- Love how simple and powerful
pug
template is? meblog is the right tool for you.
Template project structure
The project makes use of pug
for templating, scss
for styling and gulpjs
for generating the site and automating the process.
-
templates
: Template files-
templates/pages
: Add new pages here -
templates/posts
: Add new post layout here. By default,post.pug
will be used as default layout for posts -
templates/tags
:-
templates/tags/tag.pug
: Default tag template for rendering tag pages
-
-
-
scss
: SCSS styling files-
scss/main.scss
: Main entry point of scss files, the engine will generate this file tomain.css
on building.
-
-
assets
: Put your images, favicon, and other resources here -
posts
: Put your posts in markdown format here. Ideally, arrange your posts into year and month folders for better searching. -
config.js
: Config file for the site -
i18n
: Put translation files for i18n here
How to create new post
Simply run meblog draft
or create a new file post-name.md
in folder posts
using the below format:
---
title: This is the post title
publishedAt: 2021-05-15T18:04:00+07:00 (YYYY-MM-DDTHH:mm:ssZ)
tags: tag1, tag2
excerpt: Some thoughts about the growing journey
layout: ... (post is default layout for rendering posts page, but you can defined new layout in templates/posts folder)
language: en
customfield: Custom field will also be parsed and loaded into post object
---
Post body goes here
The file name post-name
will be used as post slug.
Preview your post while editing
Run the command meblog serve
and start editing your post then hit the save button if you want to see the change.
Set the auto saving interval to 2s in your editor for better editing experience. (As far as I know, Visual Studio Code or IntelliJ-based IDEs have this feature
Configuration
Put all configurations in config.js
file, then all the data in this file will be available to use in the pug
templates.
But there are some configurations that you need understand why do we have it.
-
baseUrl
: This will be the host url that you're about to deploy to, eg:https://sinzii.me
orhttps://yourname.github.io
. It's not required for the site to work properly. But if you care about sharing your posts on Facebook, this property will be used to calculate the url in meta tags for the purpose of SEO or sharing your posts on social media or generate RSS feed. -
baseContext
: If you want to deploy the site on a sub directory likehttps:/sinzii.me/blog
. Then set it's value asblog
. -
postUrlStyle
: The engine can generate different styles of post url, choose your favorite one.-
POSTS_SLUG
: ../posts/hello-world.html (default) -
POSTS_YEAR_MONTH_SLUG
: ../posts/2021/05/hello-world.html -
POSTS_YEAR_SLUG
: ../posts/2021/hello-world.html -
YEAR_MONTH_SLUG
: ../2021/05/hello-world.html -
YEAR_SLUG
: ../2021/hello-world.html -
SLUG
: ../hello-world.html
-
Template variables
Global variables
-
locale
: Current rendering locale -
allPosts
: List of all posts include every locales, a post can also be accessed by its slug usingallPosts[post-slug]
. -
posts
: List of posts of current rendering locale -
tags
: List of available tags -
templateName
: Name of current rendering template -
formatDateTime
: A function taking a date and locale as inputs, output formatted date time followdateTimeFormat
config -
formatDate
: A function taking a date and locale as inputs, output formatted date followdateFormat
config -
rootUrl
: A function taking a path and locale as inputs, ouput an absolute url of the site -
url
: A function taking a path and locale as inputs, output a relative url from currentbaseContext
config -
postRootUrl
: A function taking post object as input, output an absolute url of the post -
postUrl
: A function taking post object as input, output a relative url of the post -
tagRootUrl
: A function taking tag name and locale as inputs, output an absolute url of the tag -
tagUrl
: A function taking tag name and locale as inputs, output a relative url of the tag - And all properties from exported object in
config.js
will be available as global variables (eg:baseUrl
,siteName
, ...)
Post layout template variables
Variable listed here is only available in post layout template in folder templates/posts
-
post
: Current rendering post object
Tag template variables
Variables listed here are only available in tag template in folder templates/tags
-
tag
: Current rendering tag name -
postsByTag
: List of post tagged with current renderingtag
of current rendering locale
Event hooks
By default, the engine only processes pug
tempate to html pages and scss
to css. What if you need to write some JavaScript
or even TypeScript
and want those scripts to be bundle into one file or hot reload the script files on change when designing the site?
This is when event hooks come into play. Let's me first explain about the build process of meblog.
The build process
Both meblog serve
and meblog build
commands will trigger the build process when running, the only different is the former uses dev
enviroment, and the latter uses prod
enviroment.
When the build process is running, a series of tasks will be triggered one by one.
-
CleanCache
: Clean cache -
Clean
: Clean output directory -
Build
: Build the site-
CopyAssets
: Copy assets to output directory -
LoadData
: Parsing and loading posts from markdown format to javascript object. -
GenerateTemplates
: Generate templates-
GeneratePages
: Generate pages -
GeneratePosts
: Generate posts -
GenerateTags
: Generate tags
-
-
GenerateRssFeed
: Generate RSS feed -
GenerateCSS
: Generate CSS
-
-
OnServe
: Starting local development server & watching file changes (only inmeblog serve
command)
For each task, the engine will emit one event named BEFORE:TaskName
before running the task and one event named AFTER:TaskName
after the task is finished running. Therefore, in order to hook into the build process, we simply need to listen to those events and do some customization.
Listen to the events
For example, we need to write some javascript in js/main.js
then want to minify and copy this file to output directory after GenereteCss
task.
// in config.js file
const gulp = require('gulp');
const minify = require('gulp-minify');
module.exports = {
...
eventRegister(emitter) {
emitter.on('AFTER:GenerateCss', () => {
return new Promise(resolve => {
const prod = !this.config.devMode;
let stream = gulp.src('./js/main.js');
if (prod) {
stream = stream.pipe(minify());
}
stream
.pipe(gulp.dest(this.outputDirectory))
.on('end', resolve);
});
})
}
...
}
I18n
The project uses package i18n-node to implement i18n.
Put translation files in folder i18n
and update config.js
for which locales you want to support.
// in config.js file
module.exports = {
...
defaultLocale: 'en', // Default language of the site, default: en
locales: ['en', ...] // A list of the language that you want to support, default ['en']
...
}
In pug
template, i18n
translate functions are available to use. Supported translate functions: __
, __n
, __l
, __h
, __mf
.
By default, all posts are belong to the defaultLocale
, use language
meta field to define language for a post in markdown file.
Deploy your site on Github
- Put all your posts in folder
posts
. - Run
meblog build
, your site will be generated into folderdocs
, use option--outdir
if you want the build to be generated somewhere else. - Commit the files & push your commit to Github.
- Enable Github Pages, make sure to choose
/docs
as the source folder. - Enjoy the result!
🍺
Websites built with meblog
- meblog.sinzii.me - meblog website
- sinzii.me - Thang X. Vu (@sinzii)
- Who next?
Contribution
- We embrace all the contributions to our hearts. So don't hesitate to shoot a pull request.
- If you spot any problems or have any ideas to improve meblog, let's discuss it here!