Debugging andLogging

Enable or disable console logging

HistropediaJS uses a centralized Logger service to control all debug output. Logging is disabled by default so it will not spam your console unless you explicitly turn it on.

You can toggle logging globally via the default Histropedia export, or work directly with the Logger class in ESM/bundler setups. UMD/script builds expose the same helpers on the global Histropedia namespace.

When using the default export, call the convenience helpers below to enable or disable debug output across the library. These methods internally delegate to the shared Logger instance.

import Histropedia from 'histropediajs';
// Or use the global Histropedia object directly for UMD/script-tag usage

// Turn on all HistropediaJS logging
Histropedia.enableDebug();

// Or explicitly set the flag
Histropedia.setDebug(true);

// Later, turn logging off again
Histropedia.disableDebug();
// Equivalent:
Histropedia.setDebug(false);

// Check current state
const isOn = Histropedia.isDebugEnabled(); // boolean

Use the Logger directly

In module-based builds you can import the Logger class directly. This gives you fine-grained control over the debug flag and lets you emit structured messages at different levels.

import { Logger } from 'histropediajs';

Logger.setEnabled(true); // enable logging
Logger.debug('Timeline initialized');
Logger.info('Loaded articles', articles);
Logger.warn('Something looks odd');
Logger.error('Something went wrong', err);

Use logging with a script tag

When using the UMD build via a <script> tag, the same helpers are available on the global Histropedia object. You can either toggle logging via Histropedia.enableDebug() or work with Histropedia.Logger directly.

<script src="https://cdn.jsdelivr.net/npm/histropediajs@1/dist/histropedia.umd.min.js"></script>
<script>
  // Enable debug logging
  Histropedia.enableDebug();

  // Or via the Logger instance
  Histropedia.Logger.setEnabled(true);
  Histropedia.Logger.debug('Timeline ready');
</script>

Change the console prefix

All log messages are prefixed with a label (by default [Histropedia]) so you can easily spot them in the console. You can change this prefix to include your app name, environment, or any other marker.

import { Logger } from 'histropediajs';

// Set a custom label that will appear in front of every log message
Logger.setPrefix('[MyApp Timeline]');

Logger.setEnabled(true);
Logger.debug('Loading articles...');
// Output: [MyApp Timeline] Loading articles...

For script-tag/UMD usage you can configure the same prefix via the global Logger instance:

Histropedia.Logger.setPrefix('[MyApp Timeline]');
Histropedia.enableDebug();
Histropedia.Logger.info('Timeline is ready');
// Output: [MyApp Timeline] Timeline is ready

The prefix is applied to all standard console-style methods exposed by the logger (log, info, warn, error, debug, group, groupCollapsed, groupEnd).

Use visual density-region overlays new

Visual diagnostics are configured per timeline and are separate from the global logging helpers above. Enable debugOverlays.densityRegions to draw vertical guides at the boundaries currently used by article-density filtering. The overlay is disabled by default and does not intercept pointer input or alter timeline state. See the Timeline Options reference for the option definitions.

const timeline = new Histropedia.Timeline(container, {
  debugOverlays: {
    densityRegions: true
  }
});

// Toggle the guides later without changing global logging
timeline.setOption('debugOverlays.densityRegions', false);