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 LightningCSS 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

Flag	Short Flag	Description	Default
--input	-i	Input path	src
--output	-o	Output path	dist
--mode	-m	Set mode: development or production	development
--watch	-w	Watches the source files and rebuilds on changes
--info	-I	Display information about the project
--no-minify	-n	Disable all minification
--no-minify-css		Disable minification for CSS
--no-minify-js		Disable minification for JS

Usage

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

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

Note

You can invoke the CLI using either hamlet or hamlet-builder.

Then you can run the following commands:

npm run start
npm run build

You can also use the CLI directly. For example, to start it in development mode with automatic file watching:

npx hamlet --mode development --watch

Configuration Files

Hamlet

Configuration file for Hamlet plugins, custom helpers, and build options. You can add a configuration file to the root of your project by creating a .hamletrc.js or hamlet.config.js file, or by placing a hamletrc.js file inside a .config/ folder. You can also use .cjs or .mjs extensions.

Basic configuration

import testPlugin from '@hamlet/test-plugin'

export default {
  recompileStyleOnAnyChange: false,
  helpers: {
    sayHello: name => `Hello, ${name}!`,
  },
  plugins: [
    testPlugin(),
  ]
}

Options

• helpers — Object with custom Handlebars helpers. These helpers don't require namespacing and can override built-in helpers if needed. Use for local project helpers only; for distributable helpers, use the plugins system with namespacing.
• plugins — Array of plugin factory functions. Each plugin should return an object with partials and/or helpers keys. Namespaced helpers/partials from plugins cannot override built-in or previously registered ones (will be skipped with a warning).
• recompileStyleOnAnyChange — Boolean (default: false). If true, CSS is recompiled whenever any file changes (useful for class-based CSS frameworks like Tailwind that generate styles dynamically).

Using context in configuration

If your configuration needs access to paths or other context information, export a function instead of an object:

export default ({ paths }) => ({
  recompileStyleOnAnyChange: true,
  helpers: {
    projectRoot: () => paths.root,
  },
  plugins: [
    // can use paths.src, paths.dist, etc.
  ]
})

Available context properties:

• paths.root — Absolute path to the project root
• paths.src — Absolute path to the source directory (input)
• paths.dist — Absolute path to the output directory (dist)

Plugin development

A plugin must export a default function that returns an object with partials and/or helpers. If a plugin tries to register a name that already exists (a built-in helper/partial, or one from another plugin), it will be skipped with a console warning instead of overwriting it.

Important

Plugins execute arbitrary Node.js code. Treat them as you would any other npm dependency—only install plugins from trusted sources.

Tip

Want to build your own plugin? Check out the official starter: hamlet-plugin-template.

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 babel plugins are used by default 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 autoprefixer from 'autoprefixer'
import cssnanoPlugin from 'cssnano'

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

Note

The autoprefixer plugin is used by default 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}}

In addition to theme data, the following variables are always available in every template:

Variable	Type	Description
defaultmarkups	object	Blogger widget markup definitions used by {{> hamlet.defaultmarkups}}
development	boolean	true when --mode development, false otherwise

Example usage of the development variable:

{{#if development}}
  <!-- debug info only visible in development mode -->
{{/if}}

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 xml, hbs and handlebars 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}}

Tip

If you have a folder with partials that you frequently create or delete, and they are also called together in a main file, you can use the folder. prefix to include all the partials from that folder, for example: {{> folder.FOLDER_NAME}}

Helpers

These helpers are defined by default in the system, and you can use them in your templates. You can add custom helpers in your hamlet.config.js:

export default {
  helpers: {
    myHelper: value => value.toUpperCase(),
  }
}

Built-in helpers available:

Helper	Description
asset	Include the content of the file in the template
currentYear	Include the current year
eq	Check if two values are equal (===)
ne	Check if two values are not equal (!==)
lt	Check if the first value is less than the second
gt	Check if the first value is greater than the second
and	Logical AND between two values
or	Logical OR between two values
not	Negate a value
concat	Concatenate multiple strings
includes	Check if a string contains a substring
capitalize	Capitalize the first letter of a string
first	Get the first element of an array
last	Get the last element of an array
switch / case / default	Block helpers to create switch-like conditional logic

Example of use 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.css"}}

Important

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

Example of use the currentYear helper:

{{currentYear}}

Example of use the comparison and logic helpers:

{{#if (eq view.type "post")}}
  This is a post
{{/if}}

{{#if (and isPost hasThumbnail)}}
  This post has a thumbnail
{{/if}}

Example of use the switch / case / default helpers:

{{#switch view.type}}
  {{#case "post"}}This is a post{{/case}}
  {{#case "page"}}This is a page{{/case}}
  {{#default}}Unknown type{{/default}}
{{/switch}}

Partials

There are predefined partials that you can use in your templates. These are identified with the prefix hamlet.. To learn more, you can refer to the documentation on default partials. Below is a table with the available partials:

Partial	Description
hamlet.defaultmarkups	Override: suppress Blogger's auto-generated widget inclusions
hamlet.overrides	Include all override partials at once
hamlet.functions	Include all function partials at once
hamlet.ads	Function: Create AdSense ads
hamlet.adsense	Function: AdSense async script
hamlet.attr	Function: Add or remove multiple attributes
hamlet.avatar	Function: Replace the default avatar image with a custom image
hamlet.contrast	Function: Evaluate color brightness and expose contrast state
hamlet.image	Function: Create custom image tag
hamlet.kind	Function: Add classes to body tag based on the current view
hamlet.menu	Function: Create a menu from a list of links
hamlet.meta	Function: Generate meta tags
hamlet.picture	Function: Create custom picture tag
hamlet.snippet	Function: Create a snippet of a string
hamlet.skinVars	Generated: CSS variables derived from skin Group variables at build time

hamlet.functions includes all function partials in a single call, which is equivalent to including each of the function partials individually. Use it at the top of your template to make all functions available:

{{> hamlet.functions}}

hamlet.skinVars is not a callable function — it is automatically generated at build time by scanning <Group> sections in your source files and converting color, background, and font type variables into CSS custom properties. No parameters are accepted.

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) }'/>

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! 🐋

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 👏.

License

Hamlet-builder is licensed under the MIT License