@alotool/blogger-pack

Blogger-pack

A tool for develop Blogger theme.

Getting started

Features

• Nunjucks
• Sass and ES6+
• CSS and JS linter
• CSS and JS minification
• and more

Usage

Use starter themes for quick start.

Main folder structure

.
├── dist/ (g)
|   └── theme.xml <---------------------------+
├── src/                                      |
|   ├── js/                                   |
|   |   ├── dist/ (g)                         |
|   |   |   └── script.js <-------+           |
|   |   ├── js-in-template/ (g)   |           |
|   |   └── index.js >------------^           |
|   ├── sass/                                 |
|   |   ├── dist/ (g)                         |
|   |   |   └── style.css <-----------+       |
|   |   ├── sass-in-template/ (g)     |       |
|   |   └── index.scss >--------------^       |
|   ├── skin/                                 |
|   |   ├── dist/ (g)                         |
|   |   |   └── style.css <---------------+   |  # (<-) = Compiled
|   |   ├── skin-in-template/ (g)         |   |  # (>-) = Source
|   |   └── index.css >-------------------^   |  # (c)  = Config file
|   └── index.xml >---------------------------^  # (g)  = Auto-generated
├── .browserslistrc   (c)
├── .eslintrc.json    (c)
├── .stylelintrc.json (c)
├── banner.txt        (c)
├── data.json         (c)
└── package.json      (c)

Index files

• Template: src/index.xml
• Sass: src/sass/index.scss
• Skin: src/skin/index.css
• JS: src/js/index.js

Config files

.browserslistrc

The config to share target browsers. Learn more about Browserslist.

.eslintrc.json

The default config is recommended, but if you want to change the config you can read the ESLint docs.

.stylelintrc.json

The default config is recommended, but if you want to change the config you can read the Stylelint docs.

banner.txt

The header for compiled Sass, Skin and JS. You can access data from data.json using <%= data.keyName %>, you can also access data from package.json using <%= pkg.keyName %>.

data.json

Store your theme config in this file. This is Nunjucks template context, which means it can be accessed in template using {{ data.keyName }}. Learn more.

package.json

Use this file to manage and install Bloggerpack and other packages. You also will need to add Bloggerpack commands and tasks.

Bloggerpack commands

Define Bloggerpack commands and tasks to build and develop Bloggerpack theme.

The commands and tasks are defined in the scripts property of package.json.

Basic example

package.json

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

You’ll be able to run:

• npm start - Watches the source files and automatically building them whenever you save.
• npm run build - Build the theme.

Available flags

Flag	Description
--mode	production or development (no minification)
--no-sass	Exclude Sass from compilation.
--no-sass-lint	Disable Sass linter.
--no-skin	Exclude Skin from compilation.
--no-skin-lint	Disable Skin linter.
--no-js	Exclude JS from compilation.
--no-js-lint	Disable JS linter.
--watch	Watches the source files and automatically building them whenever you save.
--gulpfile	Custom gulpfile.
--cwd	Custom CWD.

Concepts

Template

We uses Nunjucks for its template engine. File extension for template files is .xml.

Source

• Index file: src/index.xml
• Compiled to: dist/theme.xml

Paths

• ./example.xml - Relative to file's directory.
• ../example.xml - Relative to file's parent directory.
• example.xml - Relative to the index.xml directory.

<bp:template> tag

Wrap the markup with <bp:template> tag in .xml files.

<bp:template>
  <p>example</p>
</bp:template>

Note: The <bp:template> tag is always required.

template tag

Do not use the default Nunjucks {% include %} tag, use {% template %} tag instead.

src/example-dir/example.xml:

<bp:template>
  <div>
    <p>example</p>
  </div>
</bp:template>

src/index.xml:

<bp:template>
  <div>
    {% template "./example-dir/example.xml" %}
  </div>
</bp:template>

Output:

<div>
  <div>
    <p>example</p>
  </div>
</div>

Including template from node modules

You can also include template from node modules:

<bp:template>
  {% template "package-name/path/to/file.xml" %}
</bp:template>

Learn how to create plugin for Bloggerpack by reading this section below.

asset tag

Use {% asset %} tag to include compiled Sass, Skin, JS, and other CSS and JS assets.

Note: You must use the {% asset %} tag to prevent assets from being prettied.

Usage example

{% asset %}
  <style>
  .element {
    display: block;
  }
  </style>
{% endasset %}

With files:

{% asset %}
  <style>
  {% asset "./path/to/file1.css" %}
  {% asset "./path/to/file2.css" %}
  </style>
{% endasset %}

Examples

Normal CSS:

{% asset %}
  <b:if cond='!data:view.isLayoutMode'>
  <style>
  {% asset "./sass/dist/style.css" %}
  </style>
  </b:if>
{% endasset %}

Skin CSS:

{% asset %}
  <b:if cond='!data:view.isLayoutMode'>
  <b:skin>
  <![CDATA[
  {% asset "./skin/dist/style.css" %}
  ]]>
  </b:skin>
  </b:if>
{% endasset %}

Layout Mode CSS:

{% asset %}
  <b:if cond='data:view.isLayoutMode'>
  <b:template-skin>
  <![CDATA[
  body#layout {}
  ]]>
  </b:template-skin>
  </b:if>
{% endasset %}

JS:

{% asset %}
  <script>
  //<![CDATA[
  {% asset "./js/dist/script.js" %}
  //]]>
  </script>
{% endasset %}

Including assets from node modules

You can also include assets from node modules:

{% asset %}
  <b:if cond='!data:view.isLayoutMode'>
  <style>
  {% asset "package-name/path/to/file.css" %}
  </style>
  </b:if>
{% endasset %}

extends tag

Use Nunjucks {% extends %} tag. See Nunjucks template inheritance.

src/base.xml:

<bp:template>
  <header>
    {% block header %}{% endblock %}
  </header>

  <main>
    {% block main %}{% endblock %}
  </main>

  <footer>
    {% block footer %}{% endblock %}
  </footer>
</bp:template>

src/index.xml:

<bp:template>
  {% extends "./base.xml" %}

  {% block header %}
  This is header content.
  {% endblock %}

  {% block main %}
  This is main content.
  {% endblock %}

  {% block footer %}
  This is footer content.
  {% endblock %}
</bp:template>

Output:

<header>
  This is header content.
</header>

<main>
  This is main content.
</main>

<footer>
  This is footer content.
</footer>

Variables

You can use variables from data.json using {{ data.keyName }} and you can also use variables from package.json using {{ pkg.keyName }}.

Example

data.json:

{
  "myVar": "Value of myVar"
}

package.json:

{
  "name": "my-awesome-theme"
}

file.xml:

<bp:template>
  <p>{{ data.myVar }}</p>
  <p>{{ pkg.name }}</p>
</bp:template>

Output:

<p>Value of myVar</p>
<p>my-awesome-theme</p>

Sass

Write your styles with Sass.

Source

• Index file: src/sass/index.scss
• Compiled to: src/sass/dist/style.css

Partialize

Do not write styles in src/sass/index.scss directly. Add a new file (e.g., _my-component.scss) within src/sass/ and than import the file to src/sass/index.scss:

Note: You can omit the _ prefix and the .scss extension.

@import "my-component";

It also support glob imports:

@import "dir/**/*.scss";

Import from node modules:

@import "~package-name"; // node_modules/package-name/<index.scss>
@import "~package-name/dir/file"; // node_modules/package-name/dir/file.scss

// @import "~package-name/dir/**/*.scss";
// Glob import is not supported. You don't need glob import inside node_modules.

Sass-in-Template

You can write Sass for specific template in the template file directly using <bp:sass> tag.

<bp:template>
  <h1 class='example'>Example</h1>
</bp:template>

<bp:sass>
$heading-color: #fff !default;

.example {
  color: $heading-color;
}
</bp:sass>

The styles within the tag would be automatically extracted to src/sass/sass-in-template folder.

Skin

Skin is CSS that support Blogger's skin variables to allow your theme to be able to customize through the Blogger theme designer.

Source

• Index file: src/skin/index.css
• Compiled to: src/skin/dist/style.css

Note: The compiled skin is not minified, so it can be customizable in the Blogger code editor.

Partialize

Do not write styles in src/skin/index.css directly. Add a new file (e.g., _my-component.css) within src/skin/ and than import the file to src/skin/index.css:

Note: You can omit the _ prefix and the .css extension.

@import "./my-component";

It also support glob imports:

@import "./dir/**/*.css";

Import from node modules:

@import "package-name"; /* node_modules/package-name/<index.css> */
@import "package-name/dir/file"; /* node_modules/package-name/dir/file.css */
@import "package-name/dir/**/*.css"; /* glob inside node_modules/package-name/dir */

Skin-in-Template

You can write skin CSS for specific template in the template file directly using <bp:skin> tag.

<bp:template>
  <h1 class='example'>Example</h1>
</bp:template>

<bp:skin>
/*
<Variable name="heading.color"
    description="Heading color"
    type="color"
    default="#ffffff"
    value="#ffffff"/>
*/

.example {
  color: $(heading.color);
}
</bp:skin>

The styles within the tag would be automatically extracted to src/skin/skin-in-template folder.

JS

The JavaScript. You can write your script with ES6+.

Source

• Index file: src/js/index.js
• Compiled to: src/js/dist/script.js

Partialize

Do not write scripts in src/js/index.js directly. Add a new file (e.g., my-script.js) within src/js/ and than import the file to src/js/index.js:

Note: You can omit the .js extension.

import './my-script';

It also support glob imports:

import './dir/**/*.js';

Import from node modules:

import 'package-name'; // node_modules/package-name/<index.js>

import square from 'package-name/lib/math'; // node_modules/package-name/lib/math.js

console.log(square(5));

// import 'package-name/dir/**/*.js';
// Glob import is not supported. You don't need glob import inside node_modules.

JS-in-Template

You can write JavaScript for specific template in the template file directly using <bp:js> tag.

<bp:template>
  <h1 class='example' id='example'>Example</h1>
</bp:template>

<bp:js>
const example = document.getElementById('example');
</bp:js>

The JavaScript within the tag would be automatically extracted to src/js/js-in-template folder.

Tips

Creating theme variants

You may want to create a variants of theme with shared components, CSS and JS.

To create a variant of theme, just create a file named src/index-<name>.xml, src/sass/index-<name>.scss, src/skin/index-<name>.css and src/js/index-<name>.js.

• The src/index-<name>.xml would be compiled to dist/theme-<name>.xml.
• The src/sass/index-<name>.scss would be compiled to src/sass/dist/style-<name>.css.
• The src/skin/index-<name>.css would be compiled to src/skin/dist/style-<name>.css.
• The src/js/index-<name>.js would be compiled to src/js/dist/script-<name>.js.

Example:

.
├── dist/
|   ├── theme.xml <-------------------------------+
|   ├── theme-one-column.xml <--------------------|--+
|   └── theme-offcanvas.xml <---------------------|--|--+
└── src/                                          |  |  |
    ├── js/                                       |  |  |
    |   ├── dist/                                 |  |  |
    |   |   ├── script.js <--------------+        |  |  |
    |   |   ├── script-one-column.js <---|--+     |  |  |
    |   |   └── script-offcanvas.js <----|--|--+  |  |  |
    |   ├── index.js >-------------------^  |  |  |  |  |
    |   ├── index-one-column.js >-----------^  |  |  |  |
    |   └── index-offcanvas.js >---------------^  |  |  |
    ├── sass/                                     |  |  |
    |   ├── dist/                                 |  |  |
    |   |   ├── style.css <--------------+        |  |  |
    |   |   ├── style-one-column.css <---|--+     |  |  |
    |   |   └── style-offcanvas.css <----|--|--+  |  |  |
    |   ├── index.scss >-----------------^  |  |  |  |  |
    |   ├── index-one-column.scss >---------^  |  |  |  |
    |   └── index-offcanvas.scss >-------------^  |  |  |
    ├── skin/                                     |  |  |
    |   ├── dist/                                 |  |  |
    |   |   ├── style.css <--------------+        |  |  |
    |   |   ├── style-one-column.css <---|--+     |  |  |
    |   |   └── style-offcanvas.css <----|--|--+  |  |  |
    |   ├── index.css >------------------^  |  |  |  |  |
    |   ├── index-one-column.css >----------^  |  |  |  |
    |   └── index-offcanvas.css >--------------^  |  |  |
    ├── index.xml >-------------------------------^  |  |
    ├── index-one-column.xml >-----------------------^  |
    └── index-offcanvas.xml >---------------------------^

Creating plugins

You just need to write Bloggerpack template in a .xml file or you can use @bloggerpack/plugin-create.

Example my-plugin.xml:

<bp:template>
  <div class='my-component' id='myComponent'>
    ...
  </div>
</bp:template>

Use .bloggerpack.xml extension to extract Sass-in-Template, Skin-in-Template, and JS-in-Template to the user theme.

my-plugin.bloggerpack.xml:

<bp:template>
  <div class='my-component' id='myComponent'>
    ...
  </div>
</bp:template>

<bp:sass>
.my-component {
  ...
}
</bp:sass>

<bp:skin>
.my-component {
  ...
}
</bp:skin>

<bp:js>
const myComponent = document.getElementById('myComponent');
</bp:js>

Sharing plugins

Use the bloggerpack-plugin keyword within your package.json and GitHub topics.

Learn more

Learn how to include template from node modules by reading this section above.

Learn how to create npm package by reading its documentation.

Official plugins

Bloggerpack plugins

Creating starters

You can use @bloggerpack/starter-create to create a new starter theme for Bloggerpack.

Sharing starters

Use the bloggerpack-starter keyword within your package.json and GitHub topics.

Official starters

Bloggerpack starters

Changelog

See CHANGELOG.