mdout

Markdown → DOCX / PDF / HTML document builder for Node.js — write your documents in plain Markdown, configure once, compile to polished Word documents, PDFs, and more.

Features

Markdown to DOCX — headings, paragraphs, bold/italic/underline/strikethrough/code inline, <br> line breaks, blockquotes, bulleted and numbered lists (nested)
Automatic heading numbering — H1 in Roman numerals (I, II, III…), sub-headings in hierarchical decimals (1., 1.1., 1.1.1.); opt out with {.no-num} on any heading
Tables — pipe-syntax tables with proportional column widths, styled header row, alternating row colors; handles escaped pipes and pipes inside math/code
Math formulas — $$…$$ blocks rendered as native Word OMML equations; $…$ inline math via Unicode; falls back gracefully with W004
Fenced code blocks — styled with monospace font, code color, and accent border
Callout / admonition blocks —  before any paragraph or blockquote
Image embedding — ![alt](path) and  for PNG/JPEG/GIF/WebP/BMP
Script-generated figures —  executes a Node/Python/TS script that draws a canvas and outputs a PNG path
Recursive file imports —  embeds Markdown files (circular-import detection E003)
Word document import — embed .docx files via AltChunk (embed) or extract text via mammoth (extract)
Template variable substitution — define vars in config, reference as {{name}}; override per-file with 
Inline styling — {color:X}, {font:Name}, {size:N}, {bg:X}, {style:…} spans; shorthand {b}, {i}, {u}, {s}; superscript ^…^ and subscript ~…~; ==highlight==
Multi-section documents —  splits the document into distinct Word sections with individual page settings
Word bookmarks / anchors —  inserts named bookmarks for cross-references
Auto-numbered captions —  numbers elements globally;  inserts a collected list
Table of contents —  inserts a ToC built from all headings; configurable depth and title
Theme system — full control over colors, fonts, font sizes, and spacing per project
Page layout — A4 / Letter / A3 or custom mm dimensions; per-section orientation and margins; configurable page numbering format and start value
Cover page — Markdown file or built-in cover builder (array of styled text entries and spacers)
Rich headers/footers — simple text or full run-level control with bold/italic/color/field substitution (PAGE_CURRENT, PAGE_TOTAL); per-section override
Watch mode — --watch debounced rebuilds while you edit; Windows-friendly file-lock retry
PDF generation — via LibreOffice on Linux/macOS; tries Microsoft Word COM first on Windows; force with --pdf-engine word|libreoffice
Export to images — mdout export images converts any project's PDF to PNG/JPEG pages via pdftoppm (preferred) or Ghostscript; select pages with --pages 1,3-5, set DPI with --dpi, choose format with --image-format
Export to flat Markdown — mdout export md flattens all imported Markdown files and executes figure scripts to produce a single self-contained .md file; ideal for AI agent ingestion
Machine-readable output — --json [path] writes a structured result object after any export; combine with --no-build to skip rebuilding when DOCX is already up-to-date

Requirements

Node.js v18+
LibreOffice (optional) — for PDF generation

canvas requires native binaries. On Windows you may need the GTK runtime.

Installation

# Install from npm
npm install -g @salahxg/mdout

# Or with pnpm
pnpm add -g @salahxg/mdout

Development / from source

git clone https://github.com/vinodnal/mdout.git
cd mdout
pnpm install

# Make the mdout command available globally (optional)
pnpm install -g .

Quick Start

# Scaffold a new project from a template
mdout init --template thesis ./my-thesis
mdout init --template report ./reports/q1

# Build a project (generates DOCX + PDF)
mdout projects/my-thesis

# DOCX only (no PDF)
mdout --no-pdf projects/my-thesis

# Verbose output with per-step timings
mdout -v projects/my-thesis

# Watch files and rebuild after changes
mdout --watch --no-pdf projects/my-thesis

# Convert an existing DOCX to PDF (no rebuild)
mdout --pdf-only projects/my-thesis

# Force Word output on Windows, or LibreOffice if you need a fallback path
mdout --pdf-engine word projects/my-thesis
mdout --pdf-engine libreoffice projects/my-thesis

# Override output path
mdout -o ./dist/output.docx projects/my-thesis

# Validate imports and variables without building
mdout validate projects/my-thesis

# Show all CLI options
mdout --help

# Export all pages as PNG images (builds DOCX → PDF → images)
mdout export projects/my-thesis

# Export specific pages at high DPI
mdout export images --pages 1,3-5 --dpi 200 projects/my-thesis

# Flatten entire document to a single Markdown file for AI agents
mdout export md --out ./thesis_flat.md projects/my-thesis

# Re-export images from an existing DOCX without rebuilding
mdout export images --no-build --pages 2- projects/my-thesis

# Export help
mdout export --help

Project Structure

mdout/
├── src/
│   ├── cli.js             — CLI argument parsing and commands
│   ├── builder.js         — Assembles Document from config
│   ├── renderer.js        — Theme-aware docx element factory
│   ├── parser.js          — Markdown → docx elements
│   ├── importer.js        — @import directive handler
│   ├── canvas-utils.js    — Shared canvas drawing primitives for figure scripts
│   ├── latex.js           — LaTeX → Unicode conversion
│   ├── math.js            — Math rendering helpers (LaTeX → OMML)
│   ├── schema.js          — Config validation and defaults
│   ├── validator.js       — Pre-build validation (imports, variables)
│   ├── logger.js          — Structured logger with warning/error codes
│   ├── utils.js           — Shared utilities (retry, fs helpers)
│   ├── pdf.js             — DOCX → PDF conversion (LibreOffice / Word COM)
│   ├── index.js           — Public programmatic API
│   └── templates/         — Starter project templates (simple, report, thesis, manual)
│
├── src/
│   └── exporter/          — Export sub-modules
│       ├── images.js      — PDF → PNG/JPEG via pdftoppm / Ghostscript
│       ├── markdown.js    — Flatten MD tree to single file
│       └── pages.js       — Page range parser + executable finder
│
├── bin/
│   └── mdout.js            — CLI executable entry point
│
├── projects/              — Your document projects (git-ignored)
│   └── my-project/
│       ├── project.config.js
│       ├── index.md
│       └── figures/
│
├── package.json
└── node_modules/

Creating a New Project

Create a new folder under projects/:

mkdir projects/my-report

Add a project.config.js with the nested schema (see USAGE.md for full schema reference):

module.exports = {
  name:   'My Report',
  input:  './content.md',
  output: './my-report.docx',
  
  meta: {
    author:   'My Organization',
    subject:  'Report subject',
    keywords: ['report', 'analysis'],
    language: 'en-US',
  },

  page: {
    size:    'A4',                      // A4 | Letter | A3 | { width: 210, height: 297 }
    margins: 25,                        // mm — uniform or { top, right, bottom, left }
    pageNumbers: { start: 1, format: 'decimal' },
  },

  // Optional default paragraph/heading alignment when not explicitly set in Markdown.
  defaultAlignment: 'justify',          // left | center | right | justify

  theme: {
    colors: {
      primary:     '1F3864',  // H1, table header fill, cover titles
      secondary:   '2E4C7E',  // H2
      accent:      '2E75B6',  // H3, links, code/math borders
      h4:          '4472C4',  // H4
      body:        '1A1A1A',  // body text
      note:        '555555',  // captions, blockquotes
      code:        '2D2D2D',  // inline code and code blocks
      codeBg:      'F5F5F5',  // code block background
      rowAlt:      'EBF2FA',  // alternating table rows
      headerText:  'FFFFFF',  // table header text color
      mathBg:      'EEF4FB',  // $$math$$ background
      tableBorder: 'AAAAAA',  // table borders
    },
    fonts: {
      body: 'Calibri',
      code: 'Courier New',
      math: 'Cambria Math',
    },
    fontSize: {
      body: 11, h1: 18, h2: 14, h3: 12, h4: 11,
      caption: 9, code: 9, header: 9, footer: 9,
    },
    spacing: {
      paragraphLine: 320,      // 1.33× line height
      paragraphAfter: 120,     // gap after paragraphs
      bulletAfter: 80,         // gap after bullets
      codeLineSpacing: 220,    // tighter in code blocks
      headings: {
        h1: { before: 480, after: 240 },
        h2: { before: 360, after: 180 },
        h3: { before: 280, after: 140 },
        h4: { before: 200, after: 100 },
      },
    },
  },

  cover: [
    { text: 'My Organization', style: 'institution' },
    { spacer: 600 },
    { text: 'MY REPORT TITLE', style: 'banner' },
    { text: 'Subtitle line', style: 'subtitle' },
    { spacer: 800 },
    { text: '2025 / 2026', style: 'year' },
  ],

  // Simple mode (backward compatible)
  // header: { text: 'My Report — Section Title', align: 'center' },
  // footer: { text: 'Organization Name — 2026', align: 'center', showPageNumbers: true },

  // Rich mode: complex formatting + dynamic fields
  header: {
    align: 'center',
    paragraphs: [
      {
        runs: [
          { text: 'My Report — Section Title', bold: true, size: 9, color: '2E4C7E' },
          { text: ' | ', color: '555555' },
          { text: 'Confidential', italics: true, color: '555555' },
        ],
      },
    ],
  },
  footer: {
    align: 'center',
    paragraphs: [
      {
        runs: [
          { text: 'Organization Name — 2026  ', color: '555555' },
          { field: 'PAGE_CURRENT', bold: true, color: '2E75B6' },
          { text: ' / ', color: '555555' },
          { field: 'PAGE_TOTAL', color: '555555' },
        ],
      },
    ],
  },
};

Write content.md using standard Markdown (see Markdown Syntax above).
Build:

mdout projects/my-report
# Output: my-report.docx and my-report.pdf (if LibreOffice is available)

For detailed config schema and advanced features, see USAGE.md.

Cover Entry Styles

Style	Description
`overline`	Small grey text (e.g. country name)
`institution`	Bold navy, medium size
`banner`	Large bold all-caps
`title`	Large bold title
`subtitle`	Medium secondary color
`chapterTitle`	Medium accent color
`year`	Small italic grey

Use { spacer: N } (N in DXA units, ~570 DXA per cm) to add vertical space.

Page Sizes

Key	Dimensions
`A4`	210 × 297 mm
`Letter`	215.9 × 279.4 mm
`A3`	297 × 420 mm

Or pass { size: { width: 210, height: 297 }, margins: 25 } for custom sizes (in mm).

@import Directive

Use in Markdown to embed external content at build time:

<!-- @import: ./figures/chart.js | caption: Figure 1 — My chart | width: 560 -->
<!-- @import: ./images/photo.png | caption: Figure 2 | width: 400 -->
<!-- @import: ./appendix.md -->

Script figures (*.js): The script must write a PNG to disk and print the file path to stdout (no newline). Use src/canvas-utils.js helpers:

const u = require('../../../src/canvas-utils');
const { createCanvas } = u;
const path = require('path');

const OUT = path.join(__dirname, '_chart.png');
const canvas = createCanvas(800, 400);
const ctx = canvas.getContext('2d');

// ... draw your chart ...

u.saveAndPrint(canvas, OUT);

CLI Reference

mdout [build] [options] <project-dir>
mdout export [format] [options] <project-dir>
mdout validate [--dep-graph] <project-dir|config-path>
mdout init [--template <name>] <new-dir>

Options (build):
  -h, --help              Show help and exit
      --version           Print version
  -v, --verbose           Per-step timings and debug output
  -q, --quiet             Suppress output except errors
  -p, --pdf               Generate PDF (on by default)
      --pdf-only          Convert existing DOCX to PDF without rebuild
      --no-pdf            Skip PDF generation
  -o, --out <path>        Override output path from config
      --soffice <path>    Path to soffice executable (auto-detected)
      --pdf-engine <name>  PDF engine: auto|word|libreoffice (default: auto)
      --watch             Rebuild on file changes (debounced)
      --watch-debounce N  Debounce delay in ms (default: 300)
      --var key=val       Override a project.config.js variable
      --json [path]       Write build result as JSON

Options (export):
  -f, --format <name>     images | md  (repeatable; default: both)
      --pages <spec>      Page range: 1,3-5 | 2- | -4 | all
      --image-format      png | jpg (default: png)
      --dpi <n>           Resolution in DPI (default: 150)
      --prefix <name>     Image file name prefix
      --no-build          Skip DOCX build, use existing output
      --no-cover          Omit cover from flat Markdown
      --pdftoppm <path>   Override pdftoppm binary
      --gs <path>         Override Ghostscript binary
      --json [path]       Write export result as JSON

Examples:

mdout projects/my-report                          # DOCX + PDF
mdout -v --no-pdf projects/my-report              # DOCX only, verbose
mdout --pdf-only projects/my-report               # PDF from existing DOCX
mdout -o ./dist/output.docx projects/my-report
mdout --watch projects/my-thesis                  # watch mode
mdout validate projects/my-report                 # validate only, no build
mdout init --template thesis ./new-thesis         # scaffold from template
mdout export projects/my-thesis                   # images + flat MD
mdout export images --pages 1-3 --dpi 300 projects/my-thesis
mdout export md --out ./flat.md projects/my-thesis

Note: PDF generation uses LibreOffice by default and will try Microsoft Word COM first on Windows. Use --pdf-engine word to force Word, or --pdf-engine libreoffice to force LibreOffice. Word PDF output is configured for print-quality rendering and keeps embedded figure compression disabled when possible.

Advanced Topics

See USAGE.md for:

Complete config schema reference with all options
@import directive guide (images, files, scripts)
Figure generation with canvas-utils
Troubleshooting and common errors
Validation error messages and fixes

canvas-utils API

Shared helpers for figure scripts (from src/canvas-utils.js):

Function	Description
`createCanvas(w, h)`	Create a canvas (re-exported from `canvas`)
`background(ctx, w, h, color?)`	Fill background
`title(ctx, text, x, y, opts?)`	Draw a title label
`chartArea(W, H, margin?)`	Compute `{ cW, cH, ox, oy }`
`hGrid(ctx, ox, oy, cW, cH, ticks, opts?)`	Horizontal grid lines + Y labels
`axes(ctx, ox, oy, cW, cH, opts?)`	Draw X/Y axes with optional arrow
`roundRect(ctx, x, y, w, h, r?)`	Rounded rectangle path (call `ctx.fill()` after)
`drawBox(ctx, x, y, w, h, lines, fill, textColor?, opts?)`	Labeled rounded box
`drawArrow(ctx, x1, y1, x2, y2, opts?)`	Arrow with arrowhead and optional label
`drawDot(ctx, x, y, r?, fill?, stroke?)`	Circle dot
`rotatedLabel(ctx, text, x, y, angleDeg, opts?)`	Rotated text
`saveAndPrint(canvas, outPath)`	Write PNG and print path to stdout

Markdown Syntax

Feature	Syntax	Notes
Headings	`# H1`, `## H2`, `### H3`, `#### H4`	Colored and sized per theme
Paragraphs	Plain text	Wrapped and justified
Bold	`text` or `__text__`
Italic	`text` or `_text_`
Code inline	`code`	Monospace, theme colors
Code blocks	```language\ncode\n```	With border and background
Math inline	$LaTeX$	Rendered with Unicode fallback
Math blocks	`$$LaTeX$$` or `$$\nformula\n$$`	Centered, shaded
Links	`[text](url)`	Clickable hyperlinks
Line break	`<br>`, `<br/>`, `<br />`	Inline hard line break inside a paragraph
Images	`![alt](path/to/image.png)`	Embedded at full width
Tables	Pipe-delimited rows	Styled header, alternating rows
Blockquotes	`> quote text`	Indented, accent color
Bullets	`- item` or `* item`	Indented, nested (4 spaces per level)
Numbered	`1. item`, `2. item`	Auto-numbered
Page break	`---` or `***` or `___`	Standalone line
Captions	`*Figure N — description`	After images/tables

For full examples, see USAGE.md.

Included Templates

Starter templates are available under src/templates/:

Template	Description
`thesis`	Full academic thesis with cover, TOC, numbered chapters
`report`	Professional report with cover and section structure
`simple`	Single-file minimal document
`manual`	Technical manual with appendices

Create a new project from a template:

mdout init --template thesis projects/my-thesis

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.agents/skills		.agents/skills
.github		.github
bin		bin
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
USAGE.md		USAGE.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
skills-lock.json		skills-lock.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

mdout

Features

Requirements

Installation

Development / from source

Quick Start

Project Structure

Creating a New Project

Cover Entry Styles

Page Sizes

@import Directive

CLI Reference

Advanced Topics

canvas-utils API

Markdown Syntax

Included Templates

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

mdout

Features

Requirements

Installation

Development / from source

Quick Start

Project Structure

Creating a New Project

Cover Entry Styles

Page Sizes

@import Directive

CLI Reference

Advanced Topics

canvas-utils API

Markdown Syntax

Included Templates

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages