Hamlet-builder

This package makes it easy to build a Blogger Template. It is used to build the Blogger template Hamlet, and all Blogger themes derived from it.

Features

• Use Handlebars to compile HBS and XML files
• Use Rollup to bundle JS files
• Use PostCSS to process CSS files
• Minify CSS and JS files using CleanCSS and Terser (Can be disabled)
• You can use the Blogger language with some additional facilities
• You can use configuration files to customize the build process (Optional)
• Fast and easy to use

Install

npm install hamlet-builder

Flags

This package has the following flags:

| Flag | Short Flag | Description | Default | | --------- | ---------- | ----------------------------------- | ------- | | --input | -i | Input path | src | | --output| -o | Output path | dist | | --mode | -m | Set mode: development or production | development | | --watch | | Watches the source files and rebuilds on changes | | | --no-minify | | Disable minification | |

Usage

Add some scripts to your package.json, a good way to do it is the following:

{
  "scripts": {
    "start": "hamlet --mode production --watch",
    "build": "hamlet --mode production"
  }
}

Then you can run the following commands:

npm run start
npm run build

Configuration Files

Rollup

Add a .rolluprc.js, rollup.config.js or create a folder .config with a file rolluprc.js. You can also use the extension .cjs or .mjs. Here is an example of configuration:

import terser from "@rollup/plugin-terser"

export default {
  plugins: [
    terser()
  ]
}

[!NOTE] The nodeResolve, commonjs and babel plugins are used by default even if a configuration file is not specified.

PostCSS

Add a .postcssrc.js, postcss.config.js or create a folder .config with a file postcssrc.js. You can also use the extension .cjs or .mjs. Here is an example of configuration:

import cssnanoPlugin from "cssnano"
import autoprefixer from "autoprefixer"

export default {
  plugins: [
    autoprefixer(),
    cssnanoPlugin()
  ]
}

[!NOTE] The autoprefixer plugin is used by default even if a configuration file is not specified.

Handlebars

Add a .handlebarsrc.js, handlebars.config.js or create a folder .config with a file handlebarsrc.js. You can also use the extension .cjs or .mjs. The file defines the helpers that will be used in the templates. Here is an example of configuration:

export default {
  helpers: {
    foo: function () {
      return "bar"
    }
  }
}

Use the helper in the template:

{{foo}}

[!NOTE] The helper asset is available by default even if a configuration file is not specified.

Theme

Add a .themerc, .themerc.json, theme.config.json or create a folder .config with a file themerc.json. Also you can add the information in the package.json file using the theme key. Here is an example of configuration:

{
  "theme": {
    "name": "Hamlet",
    "author": "zkreations"
  }
}

The data will be the context of the Handlebars templates, so you can access them as follows:

{{name}}
{{author}}

Browserlist

Add a .browserslistrc or add the information in the package.json file using the browserslist key. Here is an example of configuration:

{
  "browserslist": [
    "last 2 versions",
    "not dead"
  ]
}

More information about the Browserslist configuration, check the Browserslist repository.

Structure

The user is free to organize the files and folders as they wish, as the system will search for scss, sass, css, js, hbs and xml files to compile them as needed.

Compile styles

The system will search for sass, scss and css files to compile them. If the file name starts with an underscore _, it will be considered a partial file, for example:

├── src
│   ├── scss
│   │   ├── _module.scss
│   │   └── main.scss

Another example with css files:

├── src
│   ├── css
│   │   ├── _module.css
│   │   └── main.css

The file main.scss or main.css will be the main file that will be compiled and saved in the default output folder or the one specified by the user.

[!TIP] The PostCSS plugins will also be applied to the sass and scss files after being compiled.

Compile scripts

The system will search for js files, however only those that end with bundle.js will be considered as main files, for example:

├── src
│   ├── js
│   │   ├── module.js
│   │   └── main.bundle.js

The file main.bundle.js will be the main file, while the other files will be considered as modules. Also, when the main file is compiled, "bundle" is removed from the file name, so the resulting file will be main.js.

[!NOTE] The name of the main file will be used as the name of the function generated by Rollup.

Compile templates

The system will search for hbs and xml files to compile them. If the file name starts with an underscore _, it will be considered a partial file, for example:

├── src
│   ├── templates
│   │   ├── _module.hbs
│   │   └── main.hbs

Another example with xml files:

├── src
│   ├── templates
│   │   ├── _module.xml
│   │   └── main.xml

The file main.hbs or main.xml will be the main file that will be compiled and saved in the default output folder or the one specified by the user.

You can create any number of partials and organize them as you wish, just make sure to use unique names, when a partial is repeated you will receive a warning message. To include a partial use the following syntax:

{{> module}}

You can also include files in your template using the asset helper:

{{asset "dist/css/main.css"}}
{{asset "dist/js/main.js"}}

If the file is in the node_modules folder, you can omit the folder and use ~ to reference it:

{{asset "~/tooltips/main.js"}}

[!IMPORTANT]
Remember to use the <style> and <script> tags to include the CSS and JS files in your template.

Additional features

When writing your templates, you will be able to use the Blogger language you already know, with some additional facilities.

Root

You don't need to add the attributes to the root tag:

<html class='test'>

The above will compile to:

<html class='test' b:css='false' b:js='false' b:defaultwidgetversion='2' b:layoutsVersion='3' expr:dir='data:blog.languageDirection' expr:lang='data:blog.locale'>

Variables

You can define variables with only the name attribute:

<Variable name="test"/>
<Variable name="example" value="false"/>

The above will compile to:

<Variable name='test' description='test' type='string'/>
<Variable name='example' description='example' type='string' value='false'/>

Widgets

In the case of the widget tags, no attribute is required, you only need the type:

<b:widget/>
<b:widget type='PopularPosts'/>
<b:widget type='Label'/>
<b:widget type='Label'/>

The above will compile to:

<b:widget id='HTML1' type='HTML' version='2'/>
<b:widget id='PopularPosts1' type='PopularPosts' version='2'/>
<b:widget id='Label1' type='Label' version='2'/>
<b:widget id='Label2' type='Label' version='2'/>

[!NOTE] When type is not specified, or if the specified type is not valid, HTML will be used by default.

Normalize spaces

When you use b:* tags you can use spaces or line breaks to improve the clarity of your code, when it is compiled, these spaces will be normalized.

<b:include name='@image' data='{
  src: data:sourceUrl,
  resize: (data:shrinkToFit
    ? 500
    : 1280)
}'/>

The above will compile to:

<b:include name='@image' data='{ src: data:sourceUrl, resize: (data:shrinkToFit ? 500 : 1280) }'/>

Supporting

If you want to help me keep this and more related projects always up to date, you can buy me a coffee ☕. I will be very grateful 👏.

Create your beautiful theme

If you used this repository as a template, please, add a star ⭐ and add the following tags in yours:

• blogger-hamlet
• blogger-handlebars
• blogger-hbs

Thanks for using this repository. Happy coding! 🚀

License

Hamlet-builder is licensed under the MIT License