VuePress Active Header Links Plugin

The VuePress Active Header Links Plugin automatically activates sidebar links when the page scrolls, providing visual feedback to users about their current position in the document. It monitors scroll events and determines which header anchor is currently visible, then updates the browser's hash and highlights the corresponding sidebar link.

Package Information

• Package Name: @vuepress/plugin-active-header-links
• Package Type: npm
• Language: JavaScript
• Installation: npm install @vuepress/plugin-active-header-links

Core Imports

// In VuePress config file
module.exports = {
  plugins: ['@vuepress/active-header-links']
}

Plugin Development Dependencies:

const { path } = require('@vuepress/shared-utils');
import debounce from 'lodash.debounce';

Basic Usage

// Basic plugin registration
module.exports = {
  plugins: ['@vuepress/active-header-links']
}

// With custom configuration options
module.exports = {
  plugins: ['@vuepress/active-header-links', {
    sidebarLinkSelector: '.sidebar-link',
    headerAnchorSelector: '.header-anchor'
  }]
}

Capabilities

Plugin Factory Function

Creates and configures the VuePress plugin with optional settings for CSS selectors.

/**
 * Main plugin export - factory function that creates the active header links plugin
 * @param {PluginOptions} options - Configuration options for the plugin (defaults to empty object)
 * @returns {PluginObject} VuePress plugin object
 */
const { path } = require('@vuepress/shared-utils');

module.exports = (options = {}) => ({
  clientRootMixin: path.resolve(__dirname, 'clientRootMixin.js'),
  define: {
    AHL_SIDEBAR_LINK_SELECTOR: options.sidebarLinkSelector || '.sidebar-link',
    AHL_HEADER_ANCHOR_SELECTOR: options.headerAnchorSelector || '.header-anchor'
  }
});

interface PluginOptions {
  /** CSS selector for sidebar links (default: '.sidebar-link') */
  sidebarLinkSelector?: string;
  /** CSS selector for header anchors (default: '.header-anchor') */
  headerAnchorSelector?: string;
}

interface PluginObject {
  /** Path to client-side mixin file */
  clientRootMixin: string;
  /** Global constants for client-side usage */
  define: {
    AHL_SIDEBAR_LINK_SELECTOR: string;
    AHL_HEADER_ANCHOR_SELECTOR: string;
  };
}

// TypeScript type support from @vuepress/types
type Plugin<T extends PluginOptions = PluginOptions> = 
  (options: T) => PluginObject;

Usage Examples:

// Default configuration
module.exports = {
  plugins: ['@vuepress/active-header-links']
}

// Custom selectors for different theme structure
module.exports = {
  plugins: ['@vuepress/active-header-links', {
    sidebarLinkSelector: '.custom-sidebar-link',
    headerAnchorSelector: '.custom-header-anchor'
  }]
}

// Using full plugin name
module.exports = {
  plugins: [
    ['@vuepress/plugin-active-header-links', {
      sidebarLinkSelector: '.nav-link',
      headerAnchorSelector: '.anchor-link'
    }]
  ]
}

Client-Side Behavior

The plugin automatically injects client-side functionality that provides smooth scrolling behavior and active link highlighting.

Client-Side Implementation: The plugin injects a Vue.js mixin (clientRootMixin.js) that provides:

// Vue.js mixin pattern
import debounce from 'lodash.debounce';

export default {
  mounted() {
    window.addEventListener('scroll', this.onScroll);
  },
  methods: {
    onScroll: debounce(function() {
      this.setActiveHash();
    }, 300),
    setActiveHash() {
      // Active header detection logic
    }
  },
  beforeDestroy() {
    window.removeEventListener('scroll', this.onScroll);
  }
};

Scroll Event Handling:

• Listens to window scroll events with 300ms debouncing for performance
• Determines which header anchor is currently visible in the viewport
• Updates browser hash to reflect the current section
• Integrates seamlessly with VuePress routing system

Active Link Detection Algorithm:

• Finds all sidebar links that correspond to header anchors on the page
• Calculates scroll position using cross-browser compatible methods
• Determines active anchor based on scroll position and viewport
• Handles edge cases like being at the bottom of the page

Hash Management:

• Updates $route.hash to maintain navigation state
• Temporarily disables VuePress scroll behavior during hash updates
• Uses decodeURIComponent for proper Unicode support in anchors
• Preserves existing hash when user is at bottom of page
• Uses this.$vuepress.$set('disableScrollBehavior', true) for scroll management
• Integrates with Vue router using this.$router.replace()

Configuration Options

sidebarLinkSelector

CSS selector for sidebar navigation links.

sidebarLinkSelector?: string = '.sidebar-link'

This selector is used to find sidebar links that should be activated based on the current scroll position. The plugin will match these links with corresponding header anchors on the page.

headerAnchorSelector

CSS selector for header anchor elements.

headerAnchorSelector?: string = '.header-anchor'

This selector identifies the anchor elements within headers that are used for navigation. These anchors must have hash properties that correspond to sidebar link destinations.

Integration Requirements

Dependencies:

• @vuepress/shared-utils: Used for path resolution utilities
• lodash.debounce: Used for scroll event debouncing (300ms delay)

VuePress Plugin System:

• Must be registered in the VuePress configuration file
• Integrates with VuePress's client-side plugin system
• Uses VuePress's clientRootMixin mechanism for client-side functionality

DOM Structure Requirements:

• Sidebar links must have hash properties matching header anchors
• Header anchors must be positioned within elements that have offsetTop properties
• Elements must be accessible via document.querySelectorAll()

Browser Compatibility:

• Supports modern browsers with ES6+ features
• Uses standard DOM APIs and scroll event handling
• Compatible with VuePress's Vue.js version requirements

Error Handling

The plugin gracefully handles common scenarios:

• Missing Elements: If selectors don't match any elements, the plugin continues to work without errors
• Scroll Position Edge Cases: Properly handles being at the top or bottom of the page
• Hash Conflicts: Resolves conflicts when multiple anchors could be considered active
• Route Changes: Cleans up event listeners when navigating between pages