Learning Assemble, Step 8 - Debugging Assemble

Assemble has its own debugging pattern, which can be a bit tough when you first pick it up. In this post, we'll look at some ways to help you troubleshoot problems and understand what is going on in Assemble.

• Logging and debugging with buit-in Handlebars helpers
• Creating diagnostic pages to view Assemble's data model

Logging And Debugging With Buit-In Handlebars Helpers

Assemble thoughtfully includes some built-in Handlebars Helpers for logging and debugging, plus some general purpose helpers that are useful for debugging.

Logging with {{log}}

The log helper outputs the parameter you give it to the console, and it can be especially helpful to dump your custom objects or to inspect Assemble's data model. Imagine we were trying to troubleshoot the Home page, index.hbs, to understand how our promotions YAML definition converted to Javascript. We'll use {{log}} to output the object:

---
title: "Home"
message: We have lots of cool stuff
promotions:
 one:
  title: "Promotion 1"
 two:
  title: "Promotion 2"
 three:
  title: "Promotion 3"
navTags:
 - header
 - footer
navLabel: Home
navSort: 0
---
<h1>{{title}}</h1>
<p>{{message}}</p>
{{log promotions}}
<ul>
    {{#each promotions}}
        <li>{{title}}</li>
    {{/each}}
</ul>

When you run Assemble, you will the data logged to the console:

Running "assemble:hello" (assemble) task
Assembling output/about.html OK
Assembling output/blog.html OK
Assembling output/blog/fluff.html OK
Assembling output/blog/hello-blog.html OK
Assembling output/blog/keyword-stuffing.html OK
Assembling output/features.html OK
{ one: { title: 'Promotion 1' },
  two: { title: 'Promotion 2' },
  three: { title: 'Promotion 3' } }
Assembling output/index.html OK
Assembling output/pricing.html OK
Assembling output/privacy.html OK
>> 9 pages assembled.

Logging with {{debug}}

The {{debug}} helper works similarly to {{log}}, except that it also dumps the "context" object this. Dumping this can be very useful, but you must be aware that this in most template contexts is the entire Assemble data model, which is rather lengthy for a console window. I certainly found it educational to dump the entire thing and see how it is structured, but it isn't a concisely targeted action.

Give it a try and see what happens, just change our index.hbs experiment from {{log}} to {{debug}}:

---
title: "Home"
message: We have lots of cool stuff
promotions:
 one:
  title: "Promotion 1"
 two:
  title: "Promotion 2"
 three:
  title: "Promotion 3"
navTags:
 - header
 - footer
navLabel: Home
navSort: 0
---
<h1>{{title}}</h1>
<p>{{message}}</p>
{{debug promotions}}
<ul>
    {{#each promotions}}
        <li>{{title}}</li>
    {{/each}}
</ul>

Outputting Objects with Stringify

A similar technique involves dumping objects to the output HTML using the {{stringify}} helper. I believe this helper is undocumented, but it does exist and works just fine. Let's modify our features.hbs template to include the this object:

---
title: "Features"
navTags:
 - header
 - footer
navLabel: Features
navSort: 10
---
<h1>{{ title }}</h1>
<p>Our features are the best</p>
<pre>
{{stringify this}}
</pre>

You might find this easier than dumping the object graph to the console, either in reading the text of features.html or from viewing it in a browser. In any event, it's another option.

Handlebars Comments

Commenting out some of your page is a crudely effective way to zero in on a problem in Handlebars Templates. This may be helpful and necessary while troubleshooting in Assemble.

Handlebars supports comment start and end tagging in the form of {{!-- and --}}.

<ul>
    <li>Nothing else gets added to this list
    {{!--
    {{#each pages}}
        <li>{{data.title}}
    {{/each}}
     --}}
</ul>

Create Diagnostic Pages

Most problems I've had in Assemble have been the result of misunderstanding the data model. The logging tools above are helpful, but not a substitute for hands-on practice with the model. I recommend that you construct one or more diagnostic templates to iterate through pages and tags so you can both visualize your site model and confirm working code patterns.

Let's try building a diagnostic template that goes through the page data model, listing out our custom data. We'll call it diagnostics.hbs. Here is my first pass at this page:

---
title: Diagnostics
---
<h1>{{title}}</h1>
<table>
    <thead>
        <tr>
            <th>basename</th>
            <th>relativeLink</th>
            <th>data.title</th>
            <th>data.navTitle</th>
            <th>data.navSort</th>
        </tr>
    </thead>
    <tbody>
        {{#each pages}}
        <tr>
            <td>{{basename}}</td>
            <td>{{relativeLink}}</td>
            <td>{{data.title}}</td>
            <td>{{data.navTitle}}</td>
            <td>{{data.navSort}}</td>
        {{/each}}
    </tbody>
</table>

Luckily for me writing a debugging post, I made a mistake here using an incorrect value, {{data.navTitle}} instead of the correct {{data.navLabel}}. It was clear in the output that no page had that attribute. This inspired me to demonstrate the use of {{stringify}} in a more useful context by creating a column for the page metadata. Here it is again with slight improvements:

---
title: Diagnostics
---
<h1>{{title}}</h1>
<table>
    <thead>
        <tr>
            <th>basename</th>
            <th>relativeLink</th>
            <th>data.title</th>
            <th>data.navSort</th>
            <th>data</th>
        </tr>
    </thead>
    <tbody>
        {{#each pages}}
        <tr>
            <td>{{basename}}</td>
            <td>{{relativeLink}}</td>
            <td>{{data.title}}</td>
            <td>{{data.navSort}}</td>
            <td>{{stringify data}}</td>
        </tr>
        {{/each}}
    </tbody>
</table>

I know it doesn't look good, sorry, I'm still avoiding CSS. But you can see how helpful this might be while you experiment with navigation and custom data schemes. I particularly like the treatment of navSort, how you can see what all the values are and identify pages that have no value. You would definitely want to customize this to the data points you use in your own site.

For the code, please see the learning-assemble repository on GitHub. The branch step08-debugging-assemble contains the completed code from this post.