Lorem ipsum content...
+
+
Test Chapter 1
+
Sample content for testing heading extraction.
+
Section 1.1
+
Subsection 1.1.1
+
More sample content.
+
Section 1.2
+
Test Chapter 2
+
+
1. Introduction to MarkiTect
+
+
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.
+
+
+
1.1 Core Features
+
+
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
+
+
+
+
1.1.1 Responsive Behavior
+
+
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).
+
+
+
1.1.2 Accessibility Features
+
+
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
+
+
+
+
1.2 Implementation Details
+
+
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 elementsbuildNavigationTree() - Creates hierarchical structurehandleScroll() - Manages scroll spy functionalitynavigateToHeading() - Handles smooth scrolling
+
+
+
2. Widget Architecture
+
+
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.
+
+
+
2.1 Base Class Hierarchy
+
+
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.
+
+
+
2.1.1 Event System
+
+
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 DOMnavigate - User navigated to a headingtoggle - Widget was expanded or collapsedtheme-changed - Theme was changeddestroyed - Widget was destroyed
+
+
+
2.1.2 State Management
+
+
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.
+
+
+
2.2 Plugin System Integration
+
+
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
+
+
+
+
3. Usage Examples
+
+
The DocumentNavigator can be used in several ways, from simple instantiation to advanced configuration with custom themes and behavior.
+
+
+
3.1 Basic Usage
+
+
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.
+
+
+
3.2 Advanced Configuration
+
+
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.
+
+
+
3.2.1 Custom Theming
+
+
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.
+
+
+
4. Testing and Quality
+
+
The DocumentNavigator implementation follows Test-Driven Development (TDD) methodology with comprehensive test coverage ensuring reliability and maintainability.
+
+
+
4.1 Test Coverage
+
+
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
+
+
+
+
5. Conclusion
+
+
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.
+
+