Skip to content

Aethlon/article-engine

BranchesTags

Repository files navigation

Article Engine

High-performance markdown processing engine and React previewer for advanced document rendering

License: MIT Node.js Version npm Version TypeScript

🎯 What is Article Engine?

Article Engine is a production-grade markdown processing and rendering platform that combines:

  • High-Performance Processor: Convert markdown to optimized JSON AST
  • React Components: Beautiful, responsive preview and editor components
  • Advanced Features: Syntax highlighting, math rendering, diagrams, and more
  • Reliability: Circuit breaker, retry logic, fallback chains, and health monitoring
  • Performance: Worker pools, caching, streaming, and resource monitoring

Perfect for technical documentation, blogs, knowledge bases, and educational platforms.

✨ Key Features

📝 Markdown Processing

  • Unified/Remark Pipeline: Industry-standard markdown parsing
  • Frontmatter Support: YAML metadata extraction
  • GFM Extensions: Tables, strikethrough, task lists, and more
  • Table of Contents: Auto-generated with hierarchy

🎨 Advanced Rendering

  • Syntax Highlighting: 200+ languages with 50+ themes (Shiki)
  • Math Equations: KaTeX rendering for complex mathematics
  • Diagrams: Mermaid support for flowcharts, sequences, and more
  • Responsive Tables: Beautiful, accessible table rendering

⚡ Performance

  • Web Workers: Offload processing to background threads
  • Predictive Caching: Smart caching of frequently accessed content
  • Streaming Parser: Process large documents without memory spikes
  • GPU Acceleration: CSS 3D transforms for smooth scrolling

🛡️ Reliability

  • Circuit Breaker: Automatic failure detection and recovery
  • Retry Logic: Exponential backoff for transient failures
  • Fallback Chain: Graceful degradation when features fail
  • Health Monitoring: Real-time system health tracking

🎯 Developer Experience

  • TypeScript: Full type safety and IDE support
  • Comprehensive API: 50+ documented functions
  • Plugin Architecture: Extend with custom processors
  • Extensive Testing: Property-based and integration tests

🚀 Quick Start

Installation

# Install the npm package
npm install article-engine

# Or from local path (development)
npm install c:\Users\jenit\Desktop\mono-repo\article-engine\npm

Note

Currently, Article Engine only supports the Node/NPM ecosystem. The Python package (pip) is under active development and will be released soon.

Basic Usage

import { processor, Preview } from "article-engine";

// Initialize
await processor.init();

// Process markdown
const markdown = "# Hello\n\nThis is **bold** text.";
const doc = await processor.process(markdown, "hello-world");

console.log(doc.meta.title);      // "Hello"
console.log(doc.meta.wordCount);  // 5

React Component

import React from "react";
import { Preview } from "article-engine";

export default function ArticleViewer({ documentAST }) {
  return (
    <div className="article-container">
      <Preview document={documentAST} theme="dark" />
    </div>
  );
}

Block Editor

import React, { useState } from "react";
import { BlockEditor } from "article-engine";

export default function Editor() {
  const [markdown, setMarkdown] = useState("# My Document");

  return (
    <BlockEditor
      value={markdown}
      onChange={setMarkdown}
      onSave={({ markdown, metrics }) => {
        console.log("Saved:", markdown);
      }}
    />
  );
}

📚 Documentation

Getting Started

NPM Package

Examples

🎓 Learning Path

Beginner (1-2 hours)

  1. Read SETUP.md - Get your environment ready
  2. Read DEVELOPER.md - Quick start section
  3. Try basic examples - Process markdown
  4. Try React component - Render preview

Intermediate (3-4 hours)

  1. Read DEVELOPER.md - Core concepts
  2. Read DEVELOPER.md - API reference
  3. Try advanced examples - Math, diagrams, tables
  4. Try block editor - Visual editing

Advanced (5+ hours)

  1. Read DEVELOPER.md - Advanced features
  2. Read DEVELOPER.md - Performance
  3. Explore source code - Architecture deep dive
  4. Contribute - Add features or fix bugs

🏗️ Architecture

Modular Architecture Flow

graph TD
    subgraph Client ["Client Layer (React / Browser)"]
        User[Markdown Source / User Input] --> Editor[BlockEditor / CanvasEditor]
        Editor -->|Synchronized AST| Preview[Preview / EnhancedPreview]
    end

    subgraph Engine ["Engine Core (Unified Pipeline)"]
        Editor -.-> Orchestrator[createArticleEngine Orchestrator]
        Orchestrator --> Cache[Predictive AST Cache]
        Cache -->|Cache Miss| WorkerPool[Worker Pool Manager]
        
        subgraph Workers ["Parallel Worker Threads (Off-Thread)"]
            WorkerPool -->|Task Dispatch| WorkersMain[Worker Instances]
            WorkersMain --> Unified[Unified/Remark Parser]
            Unified --> Shiki[Shiki Code Highlight]
            Unified --> KaTeX[KaTeX Math Renderer]
            Unified --> Mermaid[Mermaid Diagram Compiler]
        end
    end

    subgraph Resiliency ["Resiliency & Quality Assurance"]
        WorkerPool --> CircuitBreaker[Circuit Breaker]
        WorkerPool --> Retry[Retry with Exponential Backoff]
        WorkerPool --> Fallback[Graceful Degradation Fallbacks]
    end

    WorkersMain -->|DocumentJSON AST| Cache
    Cache -->|Return Resolved AST| Editor
Loading

Module Organization

Article Engine
├── Processor (Node.js & Browser)
│   ├── Markdown Parser (Unified/Remark)
│   ├── Feature Processors
│   │   ├── Shiki (Syntax Highlighting)
│   │   ├── KaTeX (Math Rendering)
│   │   └── Mermaid (Diagrams)
│   └── AST Transformer
│
├── React Components (Browser)
│   ├── Preview (Rendering)
│   ├── BlockEditor (Visual Editing)
│   └── EnhancedPreview (Advanced)
│
└── Infrastructure
    ├── Worker Pool (Parallelization)
    ├── Circuit Breaker (Fault Tolerance)
    ├── Cache (Performance)
    ├── Resource Monitor (Observability)
    └── Telemetry (Metrics)

📊 Performance

Processing Speed

  • Small Documents (< 10KB): < 100ms
  • Medium Documents (10-100KB): 100-500ms
  • Large Documents (> 100KB): Streaming mode available

Memory Usage

  • Baseline: ~5MB
  • Per Document: ~1-2MB per 100KB of markdown
  • Streaming Mode: Constant memory regardless of size

Browser Support

  • Chrome/Edge 90+
  • Firefox 88+
  • Safari 14+
  • Mobile browsers (iOS Safari 14+, Chrome Mobile 90+)

🔒 Security

  • HTML Sanitization: DOMPurify integration
  • XSS Prevention: Automatic escaping of user content
  • No External Calls: All processing is local
  • No Data Collection: User content stays on device
  • GDPR Compliant: No personal data collection

📦 Installation Methods

Method 1: Direct File Path (Recommended for Windows)

npm install c:\Users\jenit\Desktop\mono-repo\article-engine\npm

Method 2: NPM Link

cd c:\Users\jenit\Desktop\mono-repo\article-engine\npm
npm link
npm link article-engine  # In your project

Method 3: Git Clone

git clone https://github.com/your-org/article-engine.git
cd article-engine/npm
npm install
npm run build

Method 4: Monorepo Workspaces

{
  "workspaces": ["packages/*", "article-engine/npm"]
}

See SETUP.md for detailed instructions.

🛠️ Development

Setup

cd npm
npm install
npm run build

Testing

npm run test          # Run tests once
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report

Development Workflow

# Terminal 1: Watch for changes
npm run build:watch

# Terminal 2: Run tests
npm run test:watch

# Terminal 3: Use in your project
npm install c:\Users\jenit\Desktop\mono-repo\article-engine\npm

🤝 Contributing

We welcome contributions! See DEVELOPER.md for guidelines.

Development Steps

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests: npm run test
  5. Build: npm run build
  6. Submit a pull request

📋 Use Cases

Technical Documentation

  • API documentation with code examples
  • Architecture diagrams and flowcharts
  • Mathematical formulas and equations

Blog Platforms

  • Rich content editing
  • SEO-optimized metadata
  • Beautiful rendering

Knowledge Bases

  • Collaborative documentation
  • Table of contents navigation
  • Search-friendly structure

Educational Content

  • Interactive tutorials
  • Mathematical notation
  • Code examples and diagrams

Internal Tools

  • Documentation generation
  • Report creation
  • Knowledge sharing

🗺️ Roadmap

Current (v1.2)

  • ✅ Core processor and preview
  • ✅ Block editor
  • ✅ Syntax highlighting
  • ✅ Math rendering
  • ✅ Diagram support
  • ✅ Performance optimization
  • ✅ Telemetry
  • ✅ Collaborative editing ready (Structured Block models)
  • ✅ Smart popover keyboard navigation & aliases
  • ✅ 5 brand new rich blocks (Todo list, accordion toggle summaries, embeds, bookmarks, attachments)
  • ✅ Custom themes & rendering customizability (React Render Overrides API)
  • ✅ Dynamic Workspace Import & Export (Atomic imports, file limit checks, null-byte binary filters)
  • ✅ Memory-Safe Exports (Object URL revocations and mobile Safari downloads)
  • ✅ Web Worker AbortSignal Task Cancellation (Prevents zombie background compiles on rapid typing)
  • ✅ Structured Compile Lifecycles (Reporting compile status: processing, success, degraded, error)
  • ✅ Portable AI Agent Skill Integration (Invariants-driven developer guidance for Gemini/Claude assistants)

Future (v2.0)

  • 📋 AI-powered features
  • 📋 Advanced analytics
  • 📋 Mobile app
  • 📋 Cloud sync
  • 📋 Full real-time synchronization layer
  • 📋 Extensible plugin manager framework

💡 Key Differentiators

Feature Article Engine Standard Libs
Dual processor + renderer ✅ ❌
Isomorphic (Node + Browser) ✅ ❌
Built-in math rendering ✅ ❌
Built-in diagram support ✅ ❌
Visual block editor ✅ ❌
Worker pool management ✅ ❌
Performance monitoring ✅ ❌
Fallback chain ✅ ❌

📞 Support

Documentation

Community

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Built with:

🚀 Get Started Today

  1. Read SETUP.md - Get your environment ready
  2. Read DEVELOPER.md - Learn the API
  3. Try Examples - See it in action
  4. Build Something - Create your first project

Article Engine - Transform Your Content
High-Performance Markdown Processing & Rendering

Version: 1.2.0
Last Updated: May 2026
License: MIT

📊 Project Statistics

  • Total Documentation: ~5,300 lines
  • API Functions: 50+ documented
  • Features: 10+ advanced features
  • Use Cases: 5+ real-world scenarios
  • Installation Methods: 4+ options
  • Browser Support: 4+ major browsers
  • Languages Supported: 200+ for syntax highlighting
  • Themes Available: 50+ color schemes

🎉 Ready to Get Started?

# Install
npm install c:\Users\jenit\Desktop\mono-repo\article-engine\npm

# Import
import { processor, Preview } from "article-engine";

# Use
await processor.init();
const doc = await processor.process(markdown, slug);

Happy coding! 🚀

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages