Hamlet Builder

https://github.com/zkreations/hamlet-builder
Admin
Hamlet Builder is a compiler for building Blogger templates with support for Handlebars templating,...
Tokens:7,010
Snippets:76
Trust Score:7.4
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Hamlet-builder via NPM

Source: https://github.com/zkreations/hamlet-builder/blob/main/README.md

The standard command to install the hamlet-builder package as a dependency in your project.

```bash
npm install hamlet-builder
```

--------------------------------

### Example Usage of @adsense - XML

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Example of how to include the Adsense async script using the @adsense function.

```XML
<b:include name='@adsense'/>
```

--------------------------------

### Example Usage of @menu - XML

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Example of how to create a menu using the @menu function, passing the 'data:links' object as the source for the menu items.

```XML
<b:include name='@menu' data='{ links: data:links }'/>
```

--------------------------------

### Example Usage of @image - XML

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Example of how to insert a custom image using the @image function, setting the source to the featured image of a post.

```XML
<b:include name='@image' data='{ src: data:view.featuredImage }'/>
```

--------------------------------

### Example Usage of @ads - XML

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Example of how to include an Adsense ad block using the @ads function with the 'in-feed' layout parameter.

```XML
<b:include name='@ads' data='{ layout: "in-feed" }'/>
```

--------------------------------

### Example Usage of @avatar - XML

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Example of how to create an avatar image using the @avatar function, setting the source to the author's photo.

```XML
<b:include name='@avatar' data='{ src: data:post.author.authorPhoto.image }'/>
```

--------------------------------

### Example Usage of @kind - XML

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Example of how to include the @kind function, which adds classes to the body tag based on the current view.

```XML
<b:include name='@kind'/>
```

--------------------------------

### Example Usage of @attr - XML

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Example of how to add multiple attributes ('id' and 'class') to an element using the @attr function.

```XML
<b:include name='@attr' data='{["id","foo"],["class","foo"]}'/>
```

--------------------------------

### Execute Hamlet CLI Commands

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Commands for building and watching Blogger templates. Supports custom input/output paths and toggling minification modes.

```bash
# Basic production build
hamlet --mode production

# Build with custom input/output paths
hamlet --input ./theme --output ./build --mode production

# Development build without minification
hamlet --mode development --no-minify

# Watch with development mode
hamlet --mode development --watch

# Watch in production mode with custom paths
hamlet -i ./src -o ./dist -m production -w

# Watch without CSS minification
hamlet --watch --no-minify-css
```

--------------------------------

### Configure Hamlet Project Settings

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Configuration files for theme metadata, JavaScript bundling via Rollup, CSS processing via PostCSS, and Handlebars helper registration.

```json
// .themerc.json or theme.config.json
{
  "name": "My Awesome Theme",
  "author": "Your Name",
  "version": "1.0.0",
  "description": "A modern Blogger theme",
  "customVar": "Available in templates as {{customVar}}"
}
```

```javascript
// rollup.config.js or .rolluprc.js
import terser from "@rollup/plugin-terser"
import resolve from "@rollup/plugin-node-resolve"

export default {
  plugins: [
    resolve(),
    terser({
      compress: { drop_console: true }
    })
  ]
}
```

```javascript
// postcss.config.js or .postcssrc.js
import autoprefixer from "autoprefixer"
import cssnano from "cssnano"
import tailwindcss from "tailwindcss"

export default {
  plugins: [
    tailwindcss(),
    autoprefixer(),
    cssnano({ preset: 'default' })
  ]
}
```

```javascript
// handlebars.config.js or .handlebarsrc.js
const formatDate = (date, format) => {
  return new Date(date).toLocaleDateString('en-US', { dateStyle: format })
}

const uppercase = (str) => str.toUpperCase()

export default {
  helpers: {
    formatDate,
    uppercase
  }
}
```

--------------------------------

### Include Handlebars Partials and Helpers

Source: https://github.com/zkreations/hamlet-builder/blob/main/README.md

Demonstrates how to include partials using the '{{>}}' syntax and how to utilize built-in helpers like 'asset' and 'currentYear' within Handlebars templates.

```handlebars
{{> module}}
{{> folder.FOLDER_NAME}}

{{asset "dist/css/main.css"}}
{{asset "~/tooltips/main.css"}}

{{currentYear}}
```

--------------------------------

### Responsive Image Handling with @image and @picture

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Provides utilities for responsive images. @image handles basic resizing and srcset generation, while @picture supports art direction with multiple source sizes.

```xml
<!-- Basic image -->
<b:include name='@image' data='{ src: data:post.featuredImage }'/>

<!-- Full featured image with all options -->
<b:include name='@image' data='{
  src: data:post.featuredImage,
  alt: data:post.title,
  class: "post-thumbnail",
  resize: 800,
  ratio: "16:9",
  loading: "lazy",
  srcset: [400, 800, 1200],
  sizes: "(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
}'/>

<!-- Basic picture element -->
<b:include name='@picture' data='{ src: data:view.featuredImage }'/>
```

--------------------------------

### Compile Blogger XML Template Enhancements

Source: https://github.com/zkreations/hamlet-builder/blob/main/README.md

Shows the shorthand syntax for root tag attributes and variable definitions in Blogger XML templates, which are automatically expanded during compilation.

```xml
<!-- Root tag shorthand -->
<html class='test'>

<!-- Variable definition shorthand -->
<Variable name="test"/>
<Variable name="example" value="false"/>
```

--------------------------------

### Configure Theme metadata

Source: https://github.com/zkreations/hamlet-builder/blob/main/README.md

Define theme information in a configuration file or package.json, which becomes available as context in Handlebars templates.

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

--------------------------------

### Implement Template Partials

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Reusable template fragments using file-based partials or folder-based bulk inclusion.

```handlebars
<!-- src/_header.hbs -->
<header class="site-header">
  <h1>{{name}}</h1>
  <nav>{{> navigation}}</nav>
</header>

<!-- src/_navigation.hbs -->
<ul class="nav-list">
  <li><a href="/">Home</a></li>
  <li><a href="/about">About</a></li>
</ul>

<!-- src/main.hbs - Include partials -->
<html>
<head>
  {{> super.meta}}
</head>
<body>
  {{> header}}
  <main>
    <b:section id='main'>
      <b:widget type='Blog'/>
    </b:section>
  </main>
</body>
</html>

<!-- Automatically includes all partials in the 'components' folder -->
{{> folder.components}}
```

--------------------------------

### Page Context Styling with @kind

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Automatically injects CSS classes into the body tag based on the current page type (e.g., is-home, is-post, is-page).

```xml
<body>
  <b:include name='@kind'/>
</body>
```

--------------------------------

### Configure Rollup for JavaScript bundling

Source: https://github.com/zkreations/hamlet-builder/blob/main/README.md

Create a rollup configuration file to define custom plugins like terser for minification.

```javascript
import terser from "@rollup/plugin-terser"

export default {
  plugins: [
    terser()
  ]
}
```

--------------------------------

### Configure Browserslist

Source: https://github.com/zkreations/hamlet-builder/blob/main/README.md

Specify target browser versions for CSS and JS transpilation using the browserslist configuration.

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

--------------------------------

### Configure PostCSS for style processing

Source: https://github.com/zkreations/hamlet-builder/blob/main/README.md

Define PostCSS plugins such as autoprefixer and cssnano to process and minify CSS files.

```javascript
import cssnanoPlugin from "cssnano"
import autoprefixer from "autoprefixer"

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

--------------------------------

### Define Blogger Widgets with Hamlet-builder

Source: https://github.com/zkreations/hamlet-builder/blob/main/README.md

Demonstrates how to declare Blogger widgets using the simplified syntax. The builder automatically assigns IDs and versions, defaulting to the HTML type if the type is omitted or invalid.

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

```xml
<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'/>
```

--------------------------------

### Generate Meta Tags with @meta

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Configures document head metadata including favicons, Open Graph, and Twitter cards. Supports custom configurations for robots, HTTPS enforcement, and social media images.

```xml
<head>
  <!-- Basic meta with defaults -->
  <b:include name='@meta'/>

  <!-- With custom configuration -->
  <b:include name='@meta' data='{
    favicon: "https://example.com/favicon.png",
    favSizes: [32, 64, 128, 256],
    cardType: "summary",
    forceHttps: true,
    robots: "index,follow",
    ogImage: "https://example.com/default-og.jpg"
  }'/>
</head>
```

--------------------------------

### Configure package.json scripts

Source: https://github.com/zkreations/hamlet-builder/blob/main/README.md

Define build and development scripts in your package.json to execute hamlet-builder with various modes and flags.

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

--------------------------------

### Automate Blogger Variable Attributes

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Automatically completes Variable elements with required description and type attributes based on the provided name and value.

```xml
<!-- Input -->
<Variable name="primaryColor"/>
<Variable name="showSidebar" value="true"/>

<!-- Output -->
<Variable name='primaryColor' description='primaryColor' type='string'/>
<Variable name='showSidebar' description='showSidebar' type='string' value='true'/>
```

--------------------------------

### Automate Blogger Widget Attributes

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Automatically injects required id, type, and version attributes into Blogger widget tags. This ensures valid XML structure for theme components.

```xml
<!-- Input -->
<b:widget/>
<b:widget type='PopularPosts'/>
<b:widget type='Label'/>
<b:widget type='Label'/>

<!-- Output -->
<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'/>
```

--------------------------------

### Configure Package.json Scripts

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Defines the npm scripts and dependencies required to run the Hamlet Builder development and production build workflows.

```json
{
  "name": "my-blogger-theme",
  "version": "1.0.0",
  "scripts": {
    "dev": "hamlet --mode development --watch",
    "start": "hamlet --mode production --watch",
    "build": "hamlet --mode production",
    "build:dev": "hamlet --mode development"
  },
  "devDependencies": {
    "hamlet-builder": "^1.0.46"
  },
  "theme": {
    "name": "My Theme",
    "author": "Your Name",
    "version": "1.0.0"
  },
  "browserslist": [
    ">= 1%",
    "last 2 major versions",
    "not dead"
  ]
}
```

--------------------------------

### Normalize Blogger Tag Spacing

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Normalizes multi-line Blogger tag attributes into a single-line format to ensure compatibility and cleaner output files.

```xml
<!-- Input (readable multi-line) -->
<b:include name='@image' data='{
  src: data:sourceUrl,
  resize: (data:shrinkToFit
    ? 500
    : 1280)
}'/>

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

--------------------------------

### Navigation Menu Creation with @menu

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Generates navigation menus from PageList widget data. Supports dropdowns via specific naming conventions in the link list.

```xml
<b:include name='@menu' data='{
  links: data:links,
  prefix: ">>",
  class: "main-navigation",
  id: "primary-nav"
}'/>
```

--------------------------------

### Configure Handlebars helpers

Source: https://github.com/zkreations/hamlet-builder/blob/main/README.md

Define custom Handlebars helpers in a configuration file to extend template functionality.

```javascript
const sayHello = (name) => {
  return `Hello, ${name}!`
}

export default {
  helpers: {
    sayHello
  }
}
```

--------------------------------

### @meta

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Generates comprehensive page header metadata including favicons, Open Graph, Twitter tags, and robots configuration.

```APIDOC
## @meta

### Description
Creates the header metadata for the page, including favicons, description, canonical URL, robots, Open Graph, and Twitter tags. It's a modern replacement for Blogger's global inclusion `all-head-content`.

### Parameters
#### Request Body
- **cardType** (string) - Optional - Twitter card type. Default: `summary_large_image`
- **forceHttps** (boolean) - Optional - Force https on Canonicals URL.
- **favicon** (string) - Optional - URL of multiple resolutions favicon.
- **favSizes** (array) - Optional - Array of numbers/dimensions for favicons. Default: `[32,96,180,192]`
- **robots** (string) - Optional - Custom meta robots specifications.
- **ogImage** (string) - Optional - Default social networks image.

### Request Example
```xml
<b:include name='@meta' data='{ robots: "noindex,nofollow" }'/>
```
```

--------------------------------

### Generate Page Metadata with @meta

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

The @meta component generates comprehensive header metadata including favicons, Open Graph, Twitter tags, and robots directives. It serves as a modern replacement for the default Blogger all-head-content.

```hbs
{{> super.meta}}
```

```xml
<b:include name='@meta' data='{ robots: "noindex,nofollow" }'/>
```

--------------------------------

### AdSense Integration with @ads and @adsense

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Manages Google AdSense scripts and ad block placement. Supports standard, in-feed, and in-article ad layouts.

```xml
<head>
  <b:include name='@adsense'/>
</head>

<b:include name='@ads' data='{
  slot: "1234567890",
  layout: "in-article"
}'/>
```

--------------------------------

### Create Responsive Images with @picture

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

The @picture component generates a responsive picture tag with support for custom resizing, alt text, and various HTML attributes. It simplifies the implementation of responsive images within Blogger templates.

```hbs
{{> super.picture}}
```

```xml
<b:include name='@picture' data='{ src: data:view.featuredImage }'/>
```

--------------------------------

### @snippet

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Truncates a string to a specified length and wraps it in an HTML container.

```APIDOC
## @snippet

### Description
Creates a snippet of a string. It allows you to specify the length of the string, the HTML tag to be used, and whether to include ellipsis at the end.

### Parameters
#### Request Body
- **string** (string) - Required - Text to be shortened.
- **tag** (string) - Optional - Container HTML tag. Default: `p`
- **class** (string) - Optional - Container class.
- **id** (string) - Optional - Container id.
- **length** (number) - Optional - Length of the string. Default: `70`
- **ellipsis** (string) - Optional - Ellipsis to be added at the end of the string. Default: `...`

### Request Example
```xml
<b:include name='@snippet' data='{ string: data:post.snippets.long, length: 100 }'/>
```
```

--------------------------------

### Utilize Handlebars Template Helpers

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Built-in helpers for embedding external assets and dynamic data like the current year into templates.

```handlebars
<!-- Include compiled CSS inline -->
<style>
{{asset "dist/css/main.css"}}
</style>

<!-- Include compiled JavaScript inline -->
<script>
{{asset "dist/js/main.js"}}
</script>

<!-- Include from node_modules using ~ prefix -->
<style>
{{asset "~/normalize.css/normalize.css"}}
</style>

<!-- Footer copyright -->
<footer>
  <p>&copy; {{currentYear}} My Blog. All rights reserved.</p>
</footer>
```

--------------------------------

### User Avatar Generation with @avatar

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Renders user avatar images with support for custom fallbacks, resizing, and CSS class application. Useful for comment sections and author profiles.

```xml
<b:include name='@avatar' data='{
  src: data:comment.author.avatar.image,
  default: "https://example.com/default-avatar.png",
  resize: 64,
  alt: data:comment.author.name,
  class: "comment-avatar",
  loading: "lazy"
}'/>
```

--------------------------------

### @defaultmarkups

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Overrides default Blogger inclusions to prevent automatic widget markup generation.

```APIDOC
## @defaultmarkups

### Description
Generates a list of Blogger's default inclusions and all its widgets that are closed. By doing this, it prevents Blogger from generating its own inclusions.

### Usage
Must be included inside the `<b:defaultmarkups>` tag.

### Request Example
```hbs
<b:defaultmarkups>
  {{> super.defaultmarkups}}
</b:defaultmarkups>
```
```

--------------------------------

### Create Menu List (@menu) - Handlebars

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Creates a list of links using a PageList widget. It accepts an array of links, an optional prefix for filtering, and custom class and ID attributes for the menu.

```Handlebars
{{> super.menu}}
```

--------------------------------

### @picture

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Generates a responsive HTML5 picture tag with support for automatic resizing and custom image parameters.

```APIDOC
## @picture

### Description
Create a custom picture tag. It accepts image parameters along with other HTML attributes.

### Parameters
#### Request Body
- **src** (string) - Required - Image URL.
- **resizeSet** (array) - Optional - Array of dimensions for the image. Default: `[700,400]`
- **alt** (string) - Optional - Alt text for the image. Default: `data:messages.image`
- **id** (string) - Optional - Unique ID for the image.
- **class** (string) - Optional - Additional classes for the image.
- **width** (string) - Optional - Image width.
- **height** (string) - Optional - Image height.
- **ratio** (string) - Optional - Aspect ratio for the image.
- **loading** (string) - Optional - Loading attribute for the image.
- **params** (string) - Optional - Additional Google image parameters.

### Request Example
```xml
<b:include name='@picture' data='{ src: data:view.featuredImage }'/>
```
```

--------------------------------

### Text Truncation with @snippet

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Creates truncated text blocks from long strings. Allows customization of the HTML tag, length, and ellipsis character.

```xml
<b:include name='@snippet' data='{
  string: data:post.body,
  tag: "div",
  class: "post-excerpt",
  id: "excerpt-1",
  length: 150,
  ellipsis: " [...]"
}'/>
```

--------------------------------

### Include Adsense Async Script (@adsense) - Handlebars

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Includes the Adsense asynchronous script in the head of the page. This function does not accept any parameters.

```Handlebars
{{> super.adsense}}
```

--------------------------------

### Attribute Management with @attr

Source: https://context7.com/zkreations/hamlet-builder/llms.txt

Dynamically adds or removes HTML attributes from elements in a single include call.

```xml
<div>
  <b:include name='@attr' data='{["id","container"],["class","wrapper"],["data-theme","dark"]}'/>
</div>
```

--------------------------------

### Truncate Text with @snippet

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

The @snippet component creates a truncated version of a string, allowing for custom length, container tags, and ellipsis characters. It is useful for generating post excerpts or summaries.

```hbs
{{> super.snippet}}
```

```xml
<b:include name='@snippet' data='{ string: data:post.snippets.long, length: 100 }'/>
```

--------------------------------

### Override Default Markups

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

The defaultmarkups component prevents Blogger from generating its own default inclusions by explicitly defining closed widgets. This must be wrapped within a <b:defaultmarkups> tag.

```hbs
<b:defaultmarkups>
  {{> super.defaultmarkups}}
</b:defaultmarkups>
```

--------------------------------

### Include Adsense Ad Block (@ads) - Handlebars

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Generates an Adsense ad block. It accepts parameters for client ID, style, slot, and layout. The default style is 'display: block'.

```Handlebars
{{> super.ads}}
```

--------------------------------

### Insert Custom Image Tag (@image) - Handlebars

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Inserts a custom image tag with support for various HTML attributes and image-specific parameters like resize, ratio, and srcset. It also allows for additional Google image parameters.

```Handlebars
{{> super.image}}
```

--------------------------------

### Create Avatar Image (@avatar) - Handlebars

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Generates an avatar image, allowing for a custom source, default image, resizing, alt text, and CSS classes. The default avatar image is 'https://lh3.googleusercontent.com/a/default-user' and the default resize is 40px.

```Handlebars
{{> super.avatar}}
```

--------------------------------

### Add Body Classes Based on View (@kind) - Handlebars

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Adds CSS classes to the body tag based on the current view of the page. This function does not accept any parameters.

```Handlebars
{{> super.kind}}
```

--------------------------------

### Add or Remove Multiple Attributes (@attr) - Handlebars

Source: https://github.com/zkreations/hamlet-builder/blob/main/src/README.md

Used to add or remove multiple attributes from an HTML element. Attributes are provided as an array of key-value pairs. If a value is not specified, the attribute is removed.

```Handlebars
{{> super.attr}}
```
Tokens:
Raw