MarkiTect is an advanced markdown processing engine that provides sophisticated document management capabilities. This demo showcases the DocumentNavigator widget, which provides Substack-style navigation for long-form documents.

The navigator automatically extracts headings from your content and builds a hierarchical table of contents that floats elegantly on the side of your document.

The DocumentNavigator widget includes numerous advanced features designed for optimal user experience:

• Automatic Heading Detection: Scans document for H1, H2, H3 elements
• Hierarchical Structure: Maintains proper heading hierarchy with indentation
• Scroll Spy: Highlights current section as you scroll
• Smooth Navigation: Animated scrolling to clicked sections
• Responsive Design: Auto-hides on mobile devices

The navigator intelligently adapts to different screen sizes. On desktop computers, it remains visible as a floating panel. On mobile devices, it automatically hides to preserve screen real estate for content.

Try resizing your browser window to see this behavior in action. The navigator will disappear when the viewport becomes narrow (under 768px wide).

The DocumentNavigator is built with accessibility in mind:

• Full keyboard navigation support
• ARIA labels and proper semantic markup
• Screen reader compatibility
• High contrast hover states
• Focus management

The DocumentNavigator is implemented as a modular ES6 class that extends our base UIWidget class. This follows the planned plugin architecture for MarkiTect widgets.

Key implementation highlights include:

• extractHeadings() - Scans DOM for heading elements
• buildNavigationTree() - Creates hierarchical structure
• handleScroll() - Manages scroll spy functionality
• navigateToHeading() - Handles smooth scrolling

The DocumentNavigator follows a clean architectural pattern that separates concerns and provides maximum flexibility for customization and extension.

The widget is designed as part of a larger plugin ecosystem that will allow developers to create custom UI components that can be loaded dynamically and configured independently.

Our widget system is built on a foundation of base classes that provide common functionality:

• Widget: Core functionality (events, state, lifecycle)
• UIWidget: DOM manipulation and visual behavior
• InteractiveWidget: Event handling and user interaction

DocumentNavigator extends UIWidget directly since it doesn't require complex interaction handling beyond basic click and keyboard events.

The widget uses a custom event system built on the native EventTarget API. This allows for clean separation of concerns and easy integration with other components.

Key events emitted by DocumentNavigator:

• rendered - Widget has been rendered to DOM
• navigate - User navigated to a heading
• toggle - Widget was expanded or collapsed
• theme-changed - Theme was changed
• destroyed - Widget was destroyed

State management is handled through a simple Map-based system that provides reactive updates and event emission when state changes occur.

This approach is lightweight but powerful enough for most widget use cases while remaining debuggable and predictable.

While the current implementation works standalone, it's designed to integrate seamlessly with our planned plugin system. The plugin definition includes:

• Metadata and versioning information
• Dependency declarations
• Default configuration options
• Lifecycle hooks
• Theme variants
• Development helpers

The DocumentNavigator can be used in several ways, from simple instantiation to advanced configuration with custom themes and behavior.

The simplest way to use DocumentNavigator is with default settings:

const navigator = new DocumentNavigator();
await navigator.initialize();
await navigator.render();

This creates a navigator with default settings that will scan the entire document for headings and display them in a collapsible panel on the left side.

For more control, you can specify detailed configuration options:

const navigator = new DocumentNavigator({
    position: 'right',
    collapsed: false,
    theme: 'dark',
    maxHeadingLevel: 4,
    enableScrollSpy: true,
    smoothScroll: true
});

This creates a navigator on the right side that starts expanded, includes H4 headings, and uses the dark theme.

The navigator supports multiple built-in themes and can be extended with custom themes. The theming system integrates with MarkiTect's document themes for consistent styling.

Available themes include default, dark, and minimal, each optimized for different use cases and aesthetics.

The DocumentNavigator implementation follows Test-Driven Development (TDD) methodology with comprehensive test coverage ensuring reliability and maintainability.

Our test suite covers all major functionality:

• Widget instantiation and configuration
• DOM rendering and element creation
• Heading extraction and hierarchy building
• Navigation and smooth scrolling
• Expand/collapse animations
• Scroll spy functionality
• Responsive behavior
• Keyboard navigation
• Event emission
• Edge cases and error handling

The navigator is optimized for performance with several key strategies:

• Throttled Scroll Events: Scroll spy updates are throttled to 100ms intervals
• Efficient DOM Queries: Heading extraction is done once and cached
• Conditional Rendering: Navigator only renders if minimum heading count is met
• Memory Management: Proper cleanup prevents memory leaks
• Responsive Loading: Navigator automatically hides on mobile to save resources

The DocumentNavigator widget successfully brings Substack-style navigation to MarkiTect documents. It provides an intuitive, accessible, and performant way for users to navigate long-form content.

The implementation demonstrates the power of our widget architecture approach, with clean separation of concerns, comprehensive testing, and excellent extensibility for future enhancements.

Scroll back to the top and try the navigation features! The hamburger menu should be visible on the left side of your screen.