BL-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 bl-pack and other packages. You also will need to add bl-pack commands and tasks.

bl-pack commands

Define bl-pack commands and tasks to build and develop bl-pack theme.

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

Basic example

package.json

{
  "scripts": {
    "start": "bl-pack --mode production --watch",
    "build": "bl-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 bl-pack 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>