Debugging Theme Templates

Template Debugging Techniques

{{#set site.debugMode = true}}

<!-- 1. Variable inspection with dump filter -->
{{#if site.debugMode}}
<div class="debug-panel">
    <h3>Template Variables</h3>
    <details>
        <summary>Site Settings</summary>
        <pre>{{site | dump}}</pre>
    </details>
    <details>
        <summary>Current Page Metadata</summary>
        <pre>{{metadata | dump}}</pre>
    </details>
    <details>
        <summary>Theme Information</summary>
        <pre>{{theme | dump}}</pre>
    </details>
</div>
{{/if}}

<!-- 2. Conditional debugging for specific contexts -->
{{#if taxonomyRoute}}
<!---->
{{#if site.debugMode}}
<div class="debug-info">
    <p>Taxonomy Type: {{taxonomyType}}</p>
    <p>Taxonomy Term: {{taxonomyTerm}}</p>
    <p>Posts Count: {{posts | length}}</p>
    <p>Pagination: {{pagination | dump}}</p>
</div>
{{/if}}
<!---->
{{/if}}

<!-- 3. Console logging for development -->
{{posts | log("Posts data for debugging")}}
<!---->
{{pagination | log("Pagination object")}}

<!-- 4. Visual debugging helpers -->
{{#if site.debugMode}}
<style>
    .debug-border {
        border: 2px solid red !important;
    }
    .debug-bg {
        background: rgba(255, 0, 0, 0.1) !important;
    }
</style>

<div class="debug-border">
    <p>Debug mode active - Template: {{#if isCustomPage}}Custom{{#else}}{{fileType | capitalize}}{{/if}}</p>
</div>
{{/if}}

<!-- 5. Feature detection -->
{{#if posts}}
<p class="debug">✓ Posts available ({{posts | length}} items)</p>
{{#else}}
<p class="debug">✗ No posts found</p>
{{/if}}
<!---->
{{#if pagination}}
<p class="debug">✓ Pagination available</p>
{{#else}}
<p class="debug">✗ No pagination</p>
{{/if}}

Development vs Production Modes

<!-- Environment-specific content -->
{{#if site.environment == "development"}}
<div class="dev-tools">
    <h4>Development Tools</h4>
    <ul>
        <li>Template: {{#if isCustomPage}}custom/{{customPath}}.html{{#else}}templates/{{fileType}}.html{{/if}}</li>
        <li>Route: {{#if homeRoute}}Home{{#elseif contentRoute}}Content{{#elseif taxonomyRoute}}Taxonomy{{/if}}</li>
        <li>User: {{#if editable}}Editable{{#else}}Read-only{{/if}}</li>
    </ul>
</div>
{{/if}}

<!-- Production optimizations -->
{{#if site.environment == "production"}}
<!-- Minified CSS and JS -->
<link rel="stylesheet" href="/content/themes/{{theme.name}}/assets/css/style.min.css" />
{{#else}}
<!-- Development CSS with source maps -->
<link rel="stylesheet" href="/content/themes/{{theme.name}}/assets/css/style.css" />
{{/if}}

Next

With a solid understanding of theming in place, you're now ready to Go Beyond The Surface — and dive into Aether’s API.