markforge

📑 Table of Contents

• 🌟 Why MarkForge?

• ✨ Key Features

• 🏗️ System Architecture

• 🎨 Document Templates & Presets

• 🚀 Quickstart

  • 1. Developer CLI

  • 2. Interactive Web Studio

  • 3. Docker Container

• 🤖 Model Context Protocol (MCP) Setup

• 📖 Deep Documentation

• 📦 Monorepo Topology

• 🧪 Quality Gates & Testing

• 🤝 Contributing & Community

• 📄 License & Author

Related MCP server: docuflow

🌟 Why MarkForge?

Writing documents in Markdown is frictionless, but converting them into corporate-ready formats is notoriously painful:

• Pandoc often strips formatting nuances or requires complex LaTeX toolchains.

• Manual word processor exports lead to broken margins, inconsistent fonts, and mangled tables.

• Standard resume templates trigger parsing failures in legacy Applicant Tracking Systems (ATS).

MarkForge bridges this gap:

1. 1:1 Visual Parity: Generates native OpenXML (.docx) and print-quality PDF files that share identical typography, margins, and section spacing.

2. Built-in ATS & Quality Auditor: Evaluates your markdown AST against recruitment criteria (scores 0-100, action verb density, quantifiable metrics, section completeness).

3. AI-Native via MCP: Enables LLMs (Claude Desktop, Cursor, Antigravity) to directly compile, audit, and optimize documents without leaving chat.

4. Developer-First DX: Watch mode for instantaneous recompilation, debounced AST evaluation, and structured Pino/OpenTelemetry observability.

✨ Key Features

• 📄 Universal Output: Compile to OpenXML (.docx), Headless PDF (via LibreOffice or WeasyPrint), Pure HTML5 with Print CSS, or both simultaneously.

• 🎯 ATS Optimization Engine: AST-based parser that calculates ATS parseability, flags missing sections, counts high-impact action verbs (EN/ID), and highlights quantifiable metrics.

• 🎨 5 Curated Document Presets:

  • ats-classic: Minimalist, zero graphics, 100% parseable by legacy and modern Applicant Tracking Systems.

  • modern-accent: Contemporary emerald accents, refined headers, and crisp dividers.

  • tech-spec: Engineered for RFCs, architectural blueprints, tables, and code snippets.

  • academic: Formal serif typography, numbered sections, and standard 1-inch margins.

  • executive: Polished serif headers with bronze accents for leadership profiles.

• 📊 Native Mermaid Flowcharts: Transpile mermaid code blocks into scalable vector SVG diagrams in Web Studio and high-fidelity representations in exports.

• 🌐 Type-Safe Dual-Language Support: Complete bilingual interface (Bahasa Indonesia id and English en) across Web Studio, error messages, and starter templates.

• 🖥️ Next.js 15 Web Studio: Split-screen live editor, simulated A4 preview canvas, dashed page-break guides, browser print fallback, and official shadcn/ui components.

• 🔌 Official MCP Server: Turn Claude Desktop, Cursor IDE, or Antigravity into your document compiler and ATS editor over standard I/O (stdio).

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Markdown Input (.md)                     │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                   MarkForge Core Engine                     │
│  - AST Parser & Inline Tokenizer                            │
│  - ATS & Quality Analyzer (Scores, Verbs, Metrics)         │
│  - Template Registry (ATS Classic, Modern, Tech Spec...)    │
│  - Structured Pino Logger & OpenTelemetry Spans             │
└──────────────┬────────────────┬─────────────────┬───────────┘
               │                │                 │
               ▼                ▼                 ▼
      ┌────────────────┐ ┌──────────────┐ ┌───────────────┐
      │  OpenXML DOCX  │ │  Pure HTML5  │ │ Headless PDF  │
      │   (docx-js)    │ │ (Print CSS)  │ │ (LibreOffice) │
      └────────────────┘ └──────────────┘ └───────────────┘
               ▲                ▲                 ▲
               └────────────────┼─────────────────┘
                                │
        ┌───────────────────────┴───────────────────────┐
        │                                               │
   ┌─────────┐                                    ┌───────────┐
   │ CLI DX  │                                    │  Web UI   │
   │ (bun)   │                                    │ (Next.js) │
   └─────────┘                                    └───────────┘
                                                        ▲
                                                        │
                                                 ┌─────────────┐
                                                 │ MCP Server  │
                                                 │ (Claude/AI) │
                                                 └─────────────┘

📖 For in-depth compiler pipeline specifications, read System Architecture.

🎨 Document Templates & Presets

📐 Production Mermaid Architecture Templates

MarkForge natively renders enterprise-grade Mermaid diagrams with automatic template-synchronized palette theming, live SVG generation, and clean fallback warnings:

• Cloud Microservices & Zero-Trust Ingress (cloud-microservices): Cloudflare CDN/WAF, Envoy Gateway, JWT verification, microservices mesh, Kafka, PostgreSQL HA, Redis, OTel tracing.

• Event-Driven CQRS & Real-Time Ingestion (event-driven-cqrs): Partitioned Kafka buffer, stream workers, append-only event store, resilient Dead Letter Queue (DLQ), and query projection search views.

• Clean Hexagonal Architecture (hexagonal-architecture): Domain-Driven Design (DDD) with Driving Adapters, Application Use Cases, Core Domain, and Driven Infrastructure Ports.

• Zero-Trust Enterprise Security (zero-trust-security): IdP auth, Edge Policy Enforcement Points (PEP), Open Policy Agent (OPA) engine, SPIFFE mTLS workload mesh, and immutable WORM audit trails.

• Multi-Region High-Availability & Disaster Recovery (multi-region-resilience): Anycast Geo-DNS, active Kubernetes compute pods, warm standby region, and cross-region asynchronous database WAL replication.

• Production Lifecycle & Decision Logic (standard-flowchart): Standard production engineering workflow with AST validation checkpoints and error recovery paths.

📖 For complete template catalogs, read Templates & Architecture Guide.

🚀 Quickstart

1. Developer CLI

Run directly with bun or npx:

# Compile markdown into both DOCX & PDF
bun run packages/cli/src/index.ts build resume.md --template ats-classic --format both

# Watch mode for real-time live compilation while editing
bun run packages/cli/src/index.ts watch resume.md --template modern-accent

# Run ATS & document quality audit
bun run packages/cli/src/index.ts analyze resume.md

# Enforce minimum ATS score threshold in CI (exit code 1 if < 85)
bun run packages/cli/src/index.ts analyze resume.md --min-score 85 --json

# Preview formatted markdown directly in terminal via native Bun.markdown
bun run packages/cli/src/index.ts preview resume.md

# Verify local rendering engines
bun run packages/cli/src/index.ts doctor

📖 For complete command parameters and flags, read CLI Documentation.

2. Interactive Web Studio

🌐 Live Edge Deployment: https://mark.arafz.id (Global Next.js 15 deployment on Cloudflare Workers)

Or launch the split-screen web studio locally:

# Clone the repository
git clone https://github.com/rafliiar17/markforge.git
cd markforge

# Install dependencies
bun install

# Start Next.js development server
bun dev:web

Open http://localhost:3030 to access the studio.

3. Docker Container

Deploy the complete environment (including pre-configured LibreOffice, WeasyPrint, and Web Studio) in an isolated container:

docker-compose up --build

Access the studio at http://localhost:3030.

🤖 Model Context Protocol (MCP) Setup

Turn your AI assistant into an autonomous document compiler and resume coach.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "markforge": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/markforge/packages/mcp/src/index.ts"]
    }
  }
}

Cursor IDE (.cursor/mcp.json):

{
  "mcpServers": {
    "markforge": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/markforge/packages/mcp/src/index.ts"]
    }
  }
}

Available MCP Tools:

📖 For complete MCP setup guides and sample AI prompts, read MCP Documentation.

📖 Deep Documentation

Explore our comprehensive technical guides:

• 🏛 Architecture & Compiler Pipelines

• 💻 CLI Command Manual & Flags

• 🤖 Model Context Protocol (MCP) Integration

• 🎨 Templates & Dynamic Document Types

• 🌐 Internationalization (i18n) Architecture

• 📝 Markdown Syntax Reference & Cheatsheet

📦 Monorepo Topology

markforge/
├── packages/
│   ├── core/      # AST parser, DOCX & PDF compilers, ATS analyzer, Pino logger
│   ├── cli/       # Developer CLI (`markforge build`, `watch`, `analyze`, `doctor`)
│   ├── mcp/       # Model Context Protocol (MCP) server for Claude / Cursor / AI
│   └── web/       # Next.js 15 App Router studio with Tailwind & shadcn/ui
├── docs/          # Deep technical documentation
├── examples/      # Sample ATS resumes, technical specifications, and portfolios
└── .github/       # CI/CD workflows, issue templates, PR template

🧪 Quality Gates & Testing

MarkForge maintains a 100% automated test pass rate across all packages:

# Run 112 automated unit and E2E tests
bun test

# Typecheck all packages with strict TypeScript
bun --cwd packages/core tsc --noEmit
bun --cwd packages/cli tsc --noEmit
bun --cwd packages/mcp tsc --noEmit
bun --cwd packages/web tsc --noEmit

# Test production Web Studio build
bun run --cwd packages/web build

🤝 Contributing & Community

Contributions are warmly welcome! Please review:

• Contributing Guidelines

• Code of Conduct

• Security Policy

• Changelog

📄 License & Author

Distributed under the MIT License.
Engineered with ❤️ by Rafli Arraafi Albaasith.