Bludit Troubleshooting: Common Issues and Fixes

Debug analytics issues on Bludit — flat-file CMS caching, theme hook conflicts, plugin loading order, and JSON database quirks affecting tracking.

Bludit is a flat-file CMS that uses JSON files instead of a database. Its simplicity is a strength, but analytics troubleshooting is different from database-driven CMS platforms because there are no SQL queries to debug, no database caching layers, and theme/plugin issues trace back to PHP files and JSON configs on disk.

Bludit-Specific Debugging Approach

Since Bludit stores everything in JSON files under bl-content/, you can directly inspect the state of the system by reading files. No database client needed.

Check Plugin Status and Loading Order

# SSH into your Bludit server

# Check which plugins are active and their loading order
cat bl-content/databases/plugins.php
# This is actually a JSON file despite the .php extension

# Check if your analytics plugin exists
ls -la bl-plugins/ | grep -i "analytics\|gtm\|google\|tracking"

# Check the site head output for your tracking tag
curl -s http://localhost/ | grep -iE "gtag|gtm|analytics|tracking" | head -5

Verify Theme Hook Execution

Bludit themes must call specific hooks for plugins to inject code. If the theme skips a hook, plugin-based analytics will silently fail:

<?php
// Check your active theme's php files for these required hooks:
// In bl-themes/[your-theme]/php/head.php or similar:

// This hook is where analytics plugins inject <head> scripts
Theme::plugins('siteHead');  // MUST be present in <head>

// This hook is where body-end scripts get injected
Theme::plugins('siteBodyEnd');  // MUST be present before </body>
?>

# Quick check: does your active theme call the required hooks?
THEME=$(php -r "echo json_decode(file_get_contents('bl-content/databases/site.php'))->theme;")
grep -r "plugins('siteHead')" bl-themes/$THEME/
grep -r "plugins('siteBodyEnd')" bl-themes/$THEME/

Most Common Bludit Analytics Issues

1. Theme Missing Plugin Hook Calls

Symptoms: Analytics plugin is enabled in the admin panel but no tracking code appears in the page source.

Root cause: The active theme does not call Theme::plugins('siteHead') or Theme::plugins('siteBodyEnd') where the analytics plugin expects to inject its code.

Fix: Edit your theme's template file:

<!-- In bl-themes/[your-theme]/php/head.php -->
<head>
  <meta charset="utf-8">
  <title><?php echo $page->title(); ?></title>
  <!-- Add this line if missing: -->
  <?php Theme::plugins('siteHead'); ?>
</head>

<!-- In bl-themes/[your-theme]/php/footer.php, before </body>: -->
<?php Theme::plugins('siteBodyEnd'); ?>
</body>

2. Custom Code Plugin HTML Escaping

Symptoms: You pasted a GTM snippet into Bludit's "Custom Code" plugin but the rendered output has escaped HTML entities.

Root cause: Some Bludit versions or configurations run htmlspecialchars() on custom code plugin content.

Fix: Use the Custom Code plugin's raw head/body fields, or inject directly via a custom plugin:

<?php
// Create bl-plugins/my-analytics/plugin.php
class pluginMyAnalytics extends Plugin {
    public function siteHead() {
        return '<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag("js", new Date());
gtag("config", "G-XXXXXXX");
</script>';
    }
}
?>

3. Bludit Page Cache Serving Stale HTML

Symptoms: Tracking code was added but only appears on some pages, or appears after a delay.

Root cause: Bludit has a built-in page cache (bl-content/cache/). Cached pages serve pre-rendered HTML that may not include recently added tracking code.

Fix:

# Clear the Bludit cache
rm -rf bl-content/cache/*

# Or via Bludit admin: Settings > General > Clear Cache

Prevention: After any analytics changes, always clear the cache from Settings > General in the Bludit admin panel.

4. Slug-Based Routing Causing Duplicate Pageviews

Symptoms: Some posts show double pageviews. The same content appears accessible at multiple URL paths.

Root cause: Bludit can serve content at both /post-slug and /category/post-slug depending on URL configuration in Settings > General > URL.

Diagnosis:

// Check for canonical URL consistency
console.log('Path:', window.location.pathname);
console.log('Canonical:', document.querySelector('link[rel="canonical"]')?.href || 'NONE');

Fix: Ensure your Bludit URL scheme is consistent in Settings > General, and that your theme includes a canonical link tag.

5. Plugin Loading Order Conflicts

Symptoms: Analytics code appears in the source but JavaScript errors prevent it from executing. Other plugins' scripts throw errors first.

Root cause: Bludit loads plugins in alphabetical order by directory name. A broken plugin loading before yours can halt JavaScript execution.