Markdown Document Generator (markdown-doc-gen)

A universal, framework-agnostic Markdown processing and multi-format document generation library for Browser and Node.js environments.

Currently available outputs:

• Web (HTML): Semantic HTML with customizable styling and CSS Custom Properties.
• Word (.docx): Fully editable Microsoft Word documents powered by docx.
• PowerPoint (.pptx): Editable slides powered by PptxGenJS.

Planned and future targets:

• PDF: Planned in Task 4.3; the adapter is not available yet.

🌟 Key Features

• Isomorphic (Universal): Runs seamlessly in both browser clients (Angular, React, Vue, Svelte, Vanilla JS) and server-side runtimes (Node.js, Bun, Deno).
• Framework Agnostic: Zero dependencies on any UI framework.
• AST-Driven Architecture: Powered by marked.lexer and a decoupled Intermediate Document Model (IR) shared by the supported output adapters.
• Unified Design Tokens (DocTheme): Configure colors, fonts, and spacing consistently across currently supported outputs using typed JSON/TypeScript design tokens.
• Zero-Dependency HTML Engine: Fast, pure TypeScript semantic HTML renderer.
• Developer Playground & Test Suite: Interactive Vite-powered browser playground and full test coverage with Vitest.

🏗️ Architecture & Pipeline

[Markdown String]                     [Custom Theme (Optional)]
       │                                         │
       ▼                                         ▼
1. Lexer (marked.lexer)                  Theme Definition
       │                                 (Defaults + Overrides)
       ▼                                         │
[Raw Tokens AST]                                 │
       │                                         │
       ▼                                         │
2. Intermediate Document Model (IR)              │
   • Pure semantic AST normalization             │
       │                                         │
       └────────────────────┬────────────────────┘
                            │
                            ▼
3. Theme Resolution & Style Binding
   • Binds design tokens to the semantic tree
                            │
        ┌──────────────────────┼──────────────────────┐
        ▼                      ▼                      ▼
   4a. HTML Adapter       4b. DOCX Adapter       4c. PPTX Adapter
      (available)            (available)            (available)
        │                      │                      │
        ▼                      ▼                      ▼
      [HTML]                 [DOCX]                 [PPTX]

        Planned: PDF adapter (`pdfmake`, Task 4.3)

For complete technical specifications, see ARCHITECTURE.md.

📦 Quick Start (Conceptual Usage)

1. Web HTML Rendering

import { parseToAst, normalizeAst, renderToHtml } from 'markdown-doc-gen';

const ast = parseToAst('# Hello World\nThis is **Markdown** rendered to semantic HTML.');
const ir = normalizeAst(ast);

// Fully self-contained: embeds theme variables and base styles automatically
const html = renderToHtml(ir, {
  theme: {
    colors: { primary: '#1e3a5f', text: '#334155' }
  }
});

2. PDF Document Generation (Planned)

Technology: pdfmake (planned).

Architecture: A native adapter will map the IR directly into a pdfmake document definition. Its flow layout will handle line wrapping and pagination without converting HTML to PDF.

Planned capabilities:

• Theme-mapped typography, colors, spacing, headings, paragraphs, lists, code blocks, blockquotes, tables, and images.
• Page size, orientation, margins, page breaks, and page backgrounds.
• Image resolution from data URIs, local paths, or a custom resolver.
• Browser Blob output and Node.js Buffer output.

Status: Planned in Task 4.3. The adapter and its public API are not implemented yet.

3. Word (.docx) Document Generation

import {
  parseToAst,
  normalizeAst,
  renderDocxToBlob,
  renderDocxToBuffer
} from 'markdown-doc-gen';

const ir = normalizeAst(parseToAst(markdown));

// Browser: returns a Blob that can be downloaded by the host application
const docxBlob = await renderDocxToBlob(ir);

// Node.js: returns the DOCX bytes as a Buffer
const docxBuffer = await renderDocxToBuffer(ir);

4. PowerPoint (.pptx) Generation

PptxGenJS generates editable PowerPoint-native slides directly from the IR.

import { renderPptxToBlob, renderPptxToBuffer } from 'markdown-doc-gen';

const ir = normalizeAst(parseToAst(markdown));
const pptxBlob = await renderPptxToBlob(ir);
const pptxBuffer = await renderPptxToBuffer(ir);

• Each <!-- page --> declaration starts a slide; a leading declaration configures the first slide.
• Without page declarations, the document is placed on one slide.
• Slides default to widescreen 16:9. Layout and content margins can be configured through RenderPptxOptions.
• Content is not split across slides or automatically shrunk to fit. Authors are responsible for adapting it to each slide.
• Page backgrounds, images, theme styling, and browser Blob / Node.js Buffer output are supported.
• Inline images retain their aspect ratio and are limited to 5.5 inches wide by default, the available slide content width, and 240pt high. maxImageWidth sets the width limit in inches; source pixels are interpreted at 72 pixels per inch without upscaling.
• New exports normalize PptxGenJS slide XML, including rich-text paragraph properties and unique table/shape IDs.

📑 Pages, Backgrounds & Margins

Declare a page boundary and its optional background image and content margins with an HTML comment:

<!-- page bg-image="./assets/cover.jpg" margin="36pt 48pt" -->

# Cover content

<!-- page margin="20mm 25mm" -->

# Next page content

• bg-image applies to the full page surface, centered and scaled with cover while preserving the image proportions. It is independent of content margins; margins do not shrink or offset the background.
• margin controls only the content area. It accepts one to four physical measurements in pt, mm, cm, or in, and uses CSS shorthand order.
• A page directive at the start of the document configures the first page or slide without adding an empty one. Later directives start new pages or slides.
• Page backgrounds and margins are currently supported in HTML, DOCX, and PPTX. PDF is planned.

🎨 Theme Customization (DocTheme)

Style currently supported outputs consistently with a single typed configuration:

import type { DocTheme } from 'markdown-doc-gen';

const customTheme: DocTheme = {
  colors: {
    primary: '#0f766e',     // Headings, links, accent borders
    text: '#1e293b',        // Paragraph and list body text
    codeBg: '#0f172a',      // Dark background for code blocks
    codeText: '#f8fafc',    // Code font color
    cardBg: '#f8fafc',      // Blockquote background
    border: '#e2e8f0'       // Divider lines & table borders
  },
  typography: {
    fontFamily: 'Segoe UI',
    codeFontFamily: 'Consolas',
    baseFontSize: 11
  }
};

🧪 Testing & Interactive Playground

• Interactive Web Playground: Run npm run dev:playground to test Markdown parsing, live HTML rendering, and DOCX/PPTX downloads with hot reloading. See PLAYGROUND.md.
• Automated Tests: Run npm test to execute the full test suite with Vitest.

📄 Documentation Links

• ARCHITECTURE.md - System architecture, IR design, and technology decisions.
• PLAYGROUND.md - Manual verification harness and browser playground specification.

📜 License

MIT License.

Author

Duvan Hurtado