### Install md-to-docx Skill from Local Clone

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Install the md-to-docx skill from a local clone of the repository.

```bash
npx skills add . --skill md-to-docx --agent cursor --yes --full-depth
```

--------------------------------

### Install md-to-docx Package

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Install the package using npm, pnpm, or yarn.

```bash
npm install @mohtasham/md-to-docx
# or
pnpm add @mohtasham/md-to-docx
# or
yarn add @mohtasham/md-to-docx
```

--------------------------------

### Install and run CLI globally

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Install the package globally using npm and then run the command-line tool. Specify input and output file paths.

```bash
# Or install globally
npm install -g @mohtasham/md-to-docx
md-to-docx input.md output.docx
```

--------------------------------

### Discover md-to-docx Skill Before Installing

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Discover the md-to-docx skill before proceeding with installation.

```bash
npx skills add MohtashamMurshid/md-to-docx --list --full-depth
```

--------------------------------

### Install md-to-docx Globally

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/cli.md

Install the md-to-docx package globally using npm for command-line access.

```bash
npm install -g @mohtasham/md-to-docx
```

--------------------------------

### Install and Use md-to-docx CLI

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/README.md

Install the md-to-docx CLI globally and use it to convert a Markdown file to DOCX, optionally providing a configuration file.

```bash
npm install -g @mohtasham/md-to-docx

md-to-docx input.md output.docx --options config.json
```

--------------------------------

### Run CLI without installation

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Execute the conversion directly using npx without a global installation. Provide input and output file paths.

```bash
# Run without installing
npx @mohtasham/md-to-docx input.md output.docx
```

--------------------------------

### Install md-to-docx Skill from GitHub URL

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Quickly add the md-to-docx skill to your agent environment using its GitHub URL.

```bash
npx skills add https://github.com/mohtashammurshid/md-to-docx --skill md-to-docx
```

--------------------------------

### Install md-to-docx Skill from GitHub Shorthand

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Add the md-to-docx skill using GitHub shorthand, pinned to a specific agent.

```bash
npx skills add MohtashamMurshid/md-to-docx --skill md-to-docx --agent cursor --yes --full-depth
```

--------------------------------

### Unordered List Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Demonstrates the markdown syntax for creating unordered lists with nested items.

```markdown
- Item one
- Item two
  - Nested item
    - Doubly nested
- Back to level one
```

--------------------------------

### CLI Conversion Examples

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/skills/md-to-docx/SKILL.md

Use these commands for file-to-file conversion via the command line interface. Options can be provided via a JSON file.

```bash
npx @mohtasham/md-to-docx input.md output.docx
```

```bash
md-to-docx input.md output.docx
```

```bash
md-to-docx input.md output.docx --options options.json
```

```bash
md-to-docx input.md output.docx -o options.json
```

```bash
md-to-docx --help
```

--------------------------------

### Clone md-to-docx Repository and Install Dependencies

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Clone the md-to-docx repository and install its npm dependencies for development.

```bash
git clone https://github.com/MohtashamMurshid/md-to-docx.git
cd md-to-docx
npm install
```

--------------------------------

### TextReplacement Example Usage

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/types.md

Provides examples of configuring text replacements using the TextReplacement interface. Demonstrates literal string replacement, regex replacement, and callback-based replacement.

```typescript
textReplacements: [
  { find: /oldText/g, replace: "newText" },
  { find: "Company Name", replace: "Acme Corp" },
  { find: /(\d+)/g, replace: (match) => `Number: ${match}` },
]
```

--------------------------------

### Configuring Remote Image Handling

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Provides a configuration example for enabling and specifying allowed hosts for remote images.

```typescript
{
  imageHandling: {
    remote: {
      enabled: true,
      allowedHosts: ["cdn.example.com", "images.example.com"]
    }
  }
}
```

--------------------------------

### Example CodeHighlightTheme Object

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/types.md

An example of how to define a CodeHighlightTheme object, specifying colors for various elements and tokens. This demonstrates the structure required for custom themes.

```typescript
const theme = {
  default: "C9D1D9",
  background: "0D1117",
  border: "30363D",
  keyword: "FF7B72",
  string: "A5D6FF",
  number: "79C0FF",
  comment: "8B949E",
};
```

--------------------------------

### Image Example with Sizing

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Demonstrates how to embed an image using Markdown syntax. Supports HTTP(S) and data: URLs. Sizing can be controlled using URL parameters.

```markdown
![alt text](https://example.com/image.png#w=100&h=50)
```

--------------------------------

### TypeScript Multi-Section Document Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/README.md

Demonstrates how to configure a multi-section document using 'template' for shared defaults and 'sections' for explicit per-section layout.

```typescript
await convertMarkdownToDocx("", {
  template: {
    pageNumbering: { display: "current" }
  },
  sections: [
    {
      markdown: "# Cover\n\nTitle",
      pageNumbering: { display: "none" }
    },
    {
      markdown: "# Body\n\nContent",
      headers: { default: { text: "Report" } }
    }
  ]
});
```

--------------------------------

### Table of Contents Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Shows the syntax for generating a Table of Contents (TOC). The TOC is clickable, auto-populated, and styleable.

```markdown
[TOC]
```

--------------------------------

### Inline Link Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Illustrates how to create inline links with custom text and a URL. Supports HTTP(S), mailto:, and tel: protocols.

```markdown
[link text](https://example.com)
```

--------------------------------

### Styling Inline Code

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Provides an example of how to configure the color and background of inline code using a style object.

```typescript
{
  style: {
    inlineCodeColor: "D81B60",      // Text color
    inlineCodeBackground: "FFFACD"  // Background fill
  }
}
```

--------------------------------

### Ordered List Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Illustrates the syntax for ordered lists using numbered items. Supports nesting and per-document numbering.

```markdown
1. First item
2. Second item
   1. Nested item 2.1
```

--------------------------------

### Unordered List Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Shows the syntax for creating unordered lists using asterisks or hyphens as bullet points. Supports nesting and mixed formatting within list items.

```markdown
* Item 1
* Item 2
  * Nested Item 2.1
```

--------------------------------

### Table Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Shows the syntax for creating tables using GitHub-Flavored Markdown (GFM) table syntax. Supports alignment and nested formatting within cells.

```markdown
| Header 1 | Header 2 |
| :------- | :------: |
| Cell 1   | Cell 2   |
```

--------------------------------

### Ordered List Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Shows the markdown syntax for ordered lists, noting that Word handles auto-numbering.

```markdown
1. First step
2. Second step
   1. Sub-step A
   2. Sub-step B
3. Third step
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/RELEASING.md

Examples of commit messages that trigger different release types (patch, minor, major) or no release.

```markdown
feat: add syntax highlighting option to code blocks
fix: preserve aliases in codeHighlighting.languages
feat!: drop support for Node 16

BREAKING CHANGE: Node 18 is now the minimum supported runtime.
```

--------------------------------

### Blockquote Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Demonstrates the syntax for blockquotes using the greater-than symbol. Blockquotes can contain nested lists and code blocks.

```markdown
> This is a blockquote.
> It can contain multiple lines.
```

--------------------------------

### Page Break Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Demonstrates the syntax for inserting a page break. This is represented as an HTML block on its own line and is fully supported.

```markdown
\pagebreak
```

--------------------------------

### Handling Conversion Limits with Options

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/errors.md

This example shows how to configure conversion limits (input length, element count, timeout) using the options object and how to handle the corresponding errors within a catch block. It checks for specific context properties to identify the type of limit exceeded.

```typescript
const options = {
  maxInputLength: 1_048_576,  // 1 MB
  maxElements: 50_000,
  signal: AbortSignal.timeout(10_000),  // 10 second timeout
};

try {
  const blob = await convertMarkdownToDocx(markdown, options);
} catch (error) {
  if (error instanceof MarkdownConversionError) {
    const ctx = error.context as Record<string, unknown>;
    
    if (ctx.inputLength !== undefined) {
      // Input length exceeded
      console.error("Document is too large");
    } else if (ctx.elementCount !== undefined) {
      // Element count exceeded
      console.error("Document structure is too complex");
    } else if (ctx.reason === "AbortError") {
      // Timeout or user cancellation
      console.error("Conversion took too long");
    }
  }
}
```

--------------------------------

### CLI Options JSON for styling

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Example JSON configuration for the CLI options. This defines document type, font family, heading alignment, paragraph alignment, and code highlighting.

```json
{
  "documentType": "report",
  "style": {
    "fontFamily": "Trebuchet MS",
    "heading1Alignment": "CENTER",
    "paragraphAlignment": "JUSTIFIED"
  },
  "codeHighlighting": { "enabled": true }
}
```

--------------------------------

### Download DOCX in React

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/conversion-functions.md

Example of using `downloadDocx` within a React component to allow users to download a DOCX file. The filename is dynamically generated.

```typescript
function ExportButton({ markdown }) {
  const handleExport = async () => {
    const blob = await convertMarkdownToDocx(markdown);
    await downloadDocx(blob, `export-${Date.now()}.docx`);
  };

  return <button onClick={handleExport}>Download DOCX</button>;
}
```

--------------------------------

### JSON Configuration for Multi-Section Documents

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/configuration.md

Example JSON configuration for creating multi-section documents with custom page numbering and headers using the md-to-docx CLI.

```json
{
  "template": {
    "pageNumbering": { "display": "current", "alignment": "CENTER" }
  },
  "sections": [
    {
      "markdown": "# Cover\n\nTitle Page",
      "pageNumbering": { "display": "none" }
    },
    {
      "markdown": "[TOC]\n\n# Body\n\nContent...",
      "headers": { "default": { "text": "Main" } },
      "pageNumbering": { "start": 1 }
    }
  ]
}
```

--------------------------------

### List Items with Formatting Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Illustrates list items supporting inline formatting, code, and nested block structures like blockquotes and paragraphs.

```markdown
- **Bold item** with `code`
- *Italic text* inside the item
  - Nested list
  - Another item
    > Blockquote inside list
    
    And paragraphs too
```

--------------------------------

### Convert Markdown to DOCX using npx

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/cli.md

Execute the md-to-docx conversion directly using npx without global installation.

```bash
npx @mohtasham/md-to-docx input.md output.docx
```

--------------------------------

### HTML Comment Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Shows how to use HTML comments. Word comments can be specifically handled using the `<!-- COMMENT: text -->` format.

```markdown
<!-- This is a regular HTML comment -->
<!-- COMMENT: This is a word comment -->
```

--------------------------------

### Advanced Multi-Section Document Configuration

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/configuration.md

An example showcasing advanced multi-section document generation. It configures global styles, template defaults for page layout and numbering, and defines specific settings for cover, executive summary, and appendix sections.

```typescript
await convertMarkdownToDocx("", {
  style: { fontFamily: "Calibri", paragraphSize: 24 },
  template: {
    page: { margin: { top: 1440, right: 1080, bottom: 1440, left: 1080 } },
    pageNumbering: { display: "current", alignment: "CENTER" },
  },
  sections: [
    {
      markdown: "# Cover\n\nPrepared for ACME Inc.",
      style: { paragraphAlignment: "CENTER", paragraphSize: 32 },
      footers: { default: null },       // No footer on cover
      pageNumbering: { display: "none" }, // No page number on cover
      type: "NEXT_PAGE",
    },
    {
      markdown: "[TOC]\n\n# Executive Summary\n\n...",
      titlePage: true,
      type: "NEXT_PAGE",
      headers: { default: { text: "Executive Summary", alignment: "RIGHT" } },
      footers: {
        default: {
          text: "Page",
          pageNumberDisplay: "currentAndSectionTotal",
          alignment: "RIGHT",
        },
      },
      pageNumbering: { start: 1, formatType: "decimal" },
    },
    {
      markdown: "# Appendix\n\n...",
      type: "ODD_PAGE",
      page: { size: { orientation: "LANDSCAPE" } },
      pageNumbering: { start: 1, formatType: "upperRoman" },
    },
  ],
});
```

--------------------------------

### Fenced Code Blocks Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Demonstrates how to use fenced code blocks with optional language labels for syntax highlighting. This is a standard Markdown feature.

```markdown
```python
print("Hello, World!")
```
```

--------------------------------

### Inline Code Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Shows the syntax for inline code, which is rendered in a monospace font with background shading. This is useful for short code snippets within text.

```markdown
`inline code`
```

--------------------------------

### Hard Line Break Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Illustrates how to create hard line breaks by ending a line with a backslash followed by a newline. These breaks are preserved in the output.

```markdown
This is the first line.\
This is the second line.
```

--------------------------------

### Custom Styling for DOCX Conversion

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/cli.md

Apply custom styles to your document by providing a JSON configuration file. This example sets font family, heading alignment, and paragraph alignment.

```json
{
  "style": {
    "fontFamily": "Trebuchet MS",
    "heading1Alignment": "CENTER",
    "paragraphAlignment": "JUSTIFIED",
    "heading1Size": 36,
    "paragraphSize": 22
  }
}
```

```bash
md-to-docx README.md README.docx -o style.json
```

--------------------------------

### Multi-Section Document with Custom Headers and Footers

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/headers-footers.md

An example of a comprehensive report with multiple sections, each having distinct headers, footers, and page numbering configurations. This includes a cover page, table of contents, executive summary, detailed report, and appendix.

```typescript
await convertMarkdownToDocx("", {
  template: {
    page: {
      margin: { top: 1440, right: 1080, bottom: 1440, left: 1080 }
    },
    pageNumbering: {
      display: "current",
      alignment: "CENTER"
    }
  },
  sections: [
    // Section 1: Cover Page
    {
      markdown: "# Annual Report\n\n2024",
      titlePage: true,
      type: "NEXT_PAGE",
      headers: { default: null },
      footers: { default: null },
      pageNumbering: { display: "none" },
      style: { paragraphAlignment: "CENTER", paragraphSize: 32 }
    },

    // Section 2: Table of Contents
    {
      markdown: "[TOC]",
      type: "NEXT_PAGE",
      titlePage: true,
      headers: { default: null },
      footers: { default: null },
      pageNumbering: { display: "none" }
    },

    // Section 3: Executive Summary
    {
      markdown: "# Executive Summary\n\nKey findings...",
      type: "NEXT_PAGE",
      headers: {
        default: {
          text: "Executive Summary",
          alignment: "RIGHT"
        }
      },
      footers: {
        default: {
          text: "Page",
          alignment: "CENTER",
          pageNumberDisplay: "current"
        }
      },
      pageNumbering: { start: 1, formatType: "decimal" }
    },

    // Section 4: Detailed Report
    {
      markdown: "# Financial Analysis\n\nDetailed breakdown...",
      type: "CONTINUOUS",
      headers: {
        default: {
          text: "Financial Analysis",
          alignment: "RIGHT"
        }
      },
      footers: {
        default: {
          text: "Page",
          alignment: "CENTER",
          pageNumberDisplay: "current"
        }
      }
    },

    // Section 5: Appendix (new page numbering)
    {
      markdown: "# Appendix\n\nSupporting documents...",
      type: "ODD_PAGE",
      headers: {
        default: {
          text: "Appendix",
          alignment: "RIGHT"
        }
      },
      pageNumbering: { start: 1, formatType: "upperRoman" }
    }
  ]
});
```

--------------------------------

### Display CLI help

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Access the help information for the command-line interface to understand available commands and options.

```bash
# Help
md-to-docx --help
```

--------------------------------

### Fenced Code Block Example

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Shows the basic markdown syntax for a fenced code block with a language specifier.

```markdown
```typescript
const greet = (name: string) => `Hello, ${name}`;
```
```

--------------------------------

### Convert Markdown to DOCX with Options File

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/cli.md

Apply custom configurations for styling and layout by providing a JSON options file. The short form `-o` can also be used.

```bash
md-to-docx input.md output.docx --options config.json
```

```bash
md-to-docx input.md output.docx -o config.json
```

--------------------------------

### Data URL Image in Markdown

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

An example of embedding an image directly using a data URL, which is typically always allowed.

```markdown
![icon](data:image/png;base64,iVBORw0KGgo...)
```

--------------------------------

### Display Help Information

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/cli.md

Show usage instructions and available commands for the md-to-docx CLI. The short form `-h` is also available.

```bash
md-to-docx --help
```

```bash
md-to-docx -h
```

--------------------------------

### Basic Conversion with Options

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/configuration.md

Demonstrates how to pass an `Options` object to the `convertMarkdownToDocx` function to customize various aspects of the generated document, such as document type, styling, table of contents, and more.

```typescript
const blob = await convertMarkdownToDocx(markdown, {
  documentType: "report",
  style: { /* ... */ },
  toc: { /* ... */ },
  sections: [ /* ... */ ],
  codeHighlighting: { /* ... */ },
  imageHandling: { /* ... */ },
  textReplacements: [ /* ... */ ],
  maxInputLength: 1_048_576,
  maxElements: 50_000,
  signal: abortController.signal,
  template: { /* ... */ },
});
```

--------------------------------

### Image Sizing in Markdown

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Shows how to specify image dimensions (width and height) by appending parameters to the image URL.

```markdown
![diagram](https://example.com/diagram.png#w=400&h=300)
```

--------------------------------

### Apply styling with CLI options

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Use the --options flag to apply custom styling or multi-section configurations from a JSON file. The -o flag is a shorthand for --options.

```bash
# Apply styling or multi-section config from a JSON file
md-to-docx input.md output.docx --options options.json
md-to-docx input.md output.docx -o options.json
```

--------------------------------

### Markdown to DOCX Conversion Flow

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/README.md

Illustrates the step-by-step process of converting markdown input to a DOCX blob, including parsing, transformation, and document building.

```text
Markdown Input
    ↓
[parseMarkdownToAst] → mdast AST (unified/remark)
    ↓
[applyTextReplacements] → modified AST
    ↓
[mdastToDocxModel] → internal DocxDocumentModel
    ↓
[modelToDocx] → docx library objects (Paragraph, Table, TextRun)
    ↓
[buildHeaders/Footers/TOC] → section structure
    ↓
[Document + Packer] → DOCX Blob
    ↓
Output: Blob / ArrayBuffer / Buffer
```

--------------------------------

### Convert Markdown to DOCX

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/conversion-functions.md

Converts Markdown text to a DOCX Blob. This example demonstrates basic usage in a Node.js environment, saving the output to a file.

```typescript
import { convertMarkdownToDocx } from "@mohtasham/md-to-docx";
import fs from "node:fs/promises";

const markdown = "\n# Hello, World\nThis is a **test** document.\n";

const blob = await convertMarkdownToDocx(markdown);
await fs.writeFile("output.docx", Buffer.from(await blob.arrayBuffer()));
```

--------------------------------

### Minimal Options JSON Configuration

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/cli.md

A basic JSON configuration file specifying the document type.

```json
{
  "documentType": "document"
}
```

--------------------------------

### Basic Text Links in Markdown

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Demonstrates the syntax for creating basic text links, including web, email, and telephone links.

```markdown
[Anthropic](https://anthropic.com)
[Email support](mailto:support@example.com)
[Call us](tel:+1-555-0123)
```

--------------------------------

### CLI Usage

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/modules.md

The command-line interface allows for direct conversion of Markdown files to DOCX files from the terminal.

```APIDOC
## CLI Usage

```bash
md-to-docx <input.md> <output.docx> [--options <config.json>]
```

This command takes an input Markdown file and an output DOCX file path. Optional configuration can be provided via a JSON file.
```

--------------------------------

### SectionPageNumbering Interface Definition

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/types.md

Defines the configuration options for page numbering within a document section. Use this to control start page, format, separator, display style, and alignment.

```typescript
interface SectionPageNumbering {
  start?: number;
  formatType?: SectionPageNumberFormat;
  separator?: SectionPageNumberSeparator;
  display?: SectionPageNumberDisplay;
  alignment?: AlignmentOption;
}
```

--------------------------------

### SectionPageNumbering Interface

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/types.md

Defines the configuration for page numbering within a document section. Allows customization of the starting page number, format type, separator style, display mode, and alignment.

```APIDOC
## SectionPageNumbering Interface

### Description
Defines the configuration for page numbering within a document section. Allows customization of the starting page number, format type, separator style, display mode, and alignment.

### Fields
- **start** (number) - Optional - Page number to start from in this section (≥ 1)
- **formatType** (string) - Optional - Number format. Options: "decimal", "upperRoman", "lowerRoman", "upperLetter", "lowerLetter"
- **separator** (string) - Optional - Separator for chapter-page formatting. Options: "hyphen", "period", "colon", "emDash", "endash"
- **display** (string) - Optional - Page number rendering style. Options: "none", "current", "currentAndTotal", "currentAndSectionTotal"
- **alignment** (string) - Optional - Auto-generated page number footer alignment. Options: "LEFT", "CENTER", "RIGHT", "JUSTIFIED"
```

--------------------------------

### Convert Markdown to DOCX with Options

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/conversion-functions.md

Demonstrates converting Markdown to DOCX with custom styling and code highlighting options. This allows for fine-grained control over the document's appearance.

```typescript
const blob = await convertMarkdownToDocx(markdown, {
  style: {
    fontFamily: "Calibri",
    heading1Size: 32,
    paragraphSize: 24,
  },
  codeHighlighting: {
    enabled: true,
    theme: { keyword: "FF7B72" },
  },
});
```

--------------------------------

### Browser Entry Point for md-to-docx

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/modules.md

Use this snippet to convert Markdown to a Docx file in the browser and initiate a download. It requires the markdown content and optional configuration.

```typescript
import { convertMarkdownToDocx, downloadDocx } from "@mohtasham/md-to-docx";

const blob = await convertMarkdownToDocx(markdown, options);
await downloadDocx(blob, "file.docx");
```

--------------------------------

### JSON Configuration for Document Styling and TOC

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/configuration.md

A sample JSON configuration file for the md-to-docx CLI, defining document type, font styles, heading sizes, paragraph alignment, and table of contents settings.

```json
{
  "documentType": "report",
  "style": {
    "fontFamily": "Calibri",
    "heading1Size": 32,
    "paragraphSize": 24,
    "paragraphAlignment": "JUSTIFIED"
  },
  "toc": {
    "title": "Contents",
    "minDepth": 1,
    "maxDepth": 3
  },
  "codeHighlighting": {
    "enabled": true,
    "showLanguageLabel": true,
    "theme": {
      "keyword": "FF7B72",
      "string": "A5D6FF"
    }
  },
  "maxInputLength": 1048576,
  "maxElements": 50000
}
```

--------------------------------

### Programmatic Conversion and Download

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/skills/md-to-docx/SKILL.md

Convert a Markdown string to a DOCX Blob using `convertMarkdownToDocx` and then download it in the browser using `downloadDocx`. Ensure you are in a browser environment for `downloadDocx`.

```typescript
import { convertMarkdownToDocx, downloadDocx } from "@mohtasham/md-to-docx";

const markdown = "# Title\n\nHello **DOCX**.";
const blob = await convertMarkdownToDocx(markdown, {
  documentType: "report",
  style: {
    fontFamily: "Trebuchet MS",
    heading1Alignment: "CENTER",
    paragraphAlignment: "JUSTIFIED",
    codeBlockAlignment: "LEFT",
    direction: "LTR"
  }
});

downloadDocx(blob, "output.docx");
```

--------------------------------

### Basic Text Formatting in Markdown

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/markdown-support.md

Demonstrates basic emphasis styles like bold, italic, underline, and strikethrough using markdown syntax.

```markdown
**bold text**
*italic text*
***bold and italic***
++underline++
~~strikethrough~~
```

--------------------------------

### Basic Document Styling Configuration

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/README.md

Configure basic document styles such as font family, heading and paragraph sizes, paragraph alignment, and line spacing.

```typescript
{
  style: {
    fontFamily: "Calibri",
    heading1Size: 32,
    paragraphSize: 24,
    paragraphAlignment: "JUSTIFIED",
    lineSpacing: 1.5
  }
}
```

--------------------------------

### Code Highlighting Utilities

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/modules.md

Utilities for syntax tokenization and theme resolution for code highlighting.

```APIDOC
## `resolveTheme`

### Description
Resolves a code highlighting theme from a partial theme definition.

### Parameters
- **partial** (object) - A partial theme object.

### Returns
- (CodeHighlightTheme) - The resolved code highlighting theme.
```

```APIDOC
## `tokenizeToRuns`

### Description
Tokenizes code into text runs using a specified language, style, and options. This is a wrapper around the `lowlight` library.

### Parameters
- **code** (string) - The code string to tokenize.
- **language** (string) - The programming language of the code.
- **style** (object) - The style to apply to the tokenized runs.
- **options** (object) - Additional options for tokenization.

### Returns
- (TextRun[]) - An array of text runs representing the tokenized code.
```

--------------------------------

### Build and Test md-to-docx Project

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Compile TypeScript to dist/ and run the Jest test suite for the md-to-docx project.

```bash
npm run build   # compile TypeScript to dist/
npm test        # run the Jest suite (4 suites, 45 tests)
```

--------------------------------

### Browser Usage

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/modules.md

Use these functions in a browser environment to convert Markdown to a DOCX Blob and then download it.

```APIDOC
## Browser Entry Points

### `convertMarkdownToDocx(markdown: string, options?: object): Promise<Blob>`

Converts a Markdown string into a DOCX Blob.

### `downloadDocx(blob: Blob, filename: string): Promise<void>`

Initiates a file download for a given DOCX Blob with a specified filename.
```

--------------------------------

### Convert Markdown to Buffer in Express

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/conversion-functions.md

Demonstrates how to use `convertMarkdownToBuffer` within an Express.js route to send a generated DOCX file as an HTTP response.

```typescript
app.post("/api/export", async (req, res) => {
  const buffer = await convertMarkdownToBuffer(req.body.markdown);
  res.contentType("application/vnd.openxmlformats-officedocument.wordprocessingml.document");
  res.send(buffer);
});
```

--------------------------------

### Simple Markdown to DOCX Conversion

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/cli.md

Use this command for a basic conversion of a markdown file to a docx file.

```bash
md-to-docx README.md README.docx
```

--------------------------------

### Complete Options JSON Configuration

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/cli.md

An extensive JSON configuration for detailed document styling, including font, headings, paragraph alignment, line spacing, table of contents, and code highlighting.

```json
{
  "documentType": "report",
  "style": {
    "fontFamily": "Calibri",
    "heading1Size": 32,
    "heading2Size": 28,
    "paragraphSize": 24,
    "paragraphAlignment": "JUSTIFIED",
    "lineSpacing": 1.15
  },
  "toc": {
    "title": "Table of Contents",
    "minDepth": 1,
    "maxDepth": 3
  },
  "codeHighlighting": {
    "enabled": true,
    "showLanguageLabel": true,
    "theme": {
      "keyword": "FF7B72",
      "string": "A5D6FF",
      "number": "79C0FF",
      "comment": "8B949E"
    },
    "languages": ["typescript", "javascript", "python", "bash", "json"]
  },
  "maxInputLength": 1048576,
  "maxElements": 50000
}
```

--------------------------------

### Allow Any Remote Host

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/configuration.md

Enable fetching remote images from any host. Use with caution as it bypasses host restrictions.

```typescript
{
  imageHandling: {
    remote: { enabled: true },  // No allowedHosts = any host
  }
}
```

--------------------------------

### Package Exports Configuration

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/modules.md

This JSON configuration defines the main entry point for the md-to-docx package, specifying type definitions and JavaScript module paths for different import methods.

```json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}
```

--------------------------------

### CLI Mode Conversion

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/skills/md-to-docx/SKILL.md

Use the command line interface to convert Markdown files to DOCX. You can specify input and output files, and optionally provide an options file for customization.

```APIDOC
## CLI Mode

Use these commands:

```bash
npx @mohtasham/md-to-docx input.md output.docx
md-to-docx input.md output.docx
md-to-docx input.md output.docx --options options.json
md-to-docx input.md output.docx -o options.json
md-to-docx --help
```

CLI contract:
- Required positional args: `<input.md> <output.docx>`
- Optional options file: `--options <options.json>` or `-o <options.json>`
- Options JSON can include the same shapes as the API: `style`, `template`, `sections`, and `textReplacements`
- Help flags: `-h` or `--help`
- On success, expect: `DOCX created at: <absolute-path>`
```

--------------------------------

### Configure Code Highlighting with Custom Theme

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/configuration.md

Enable code highlighting and customize the theme by specifying colors for different elements and showing the language label.

```typescript
{
  codeHighlighting: {
    enabled: true,
    showLanguageLabel: true,
    theme: {
      default: "C9D1D9",
      background: "0D1117",
      border: "30363D",
      keyword: "FF7B72",
      string: "A5D6FF",
      number: "79C0FF",
      comment: "8B949E",
      "title.function": "D2A8FF",
    }
  }
}
```

--------------------------------

### Options Interface

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

The `Options` interface provides a comprehensive set of configurations for customizing the DOCX generation process, including document type, styling, table of contents, and more.

```APIDOC
## Options

```typescript
interface Options {
  documentType?: "document" | "report";
  style?: Style;
  toc?: TocOptions;
  maxInputLength?: number;
  maxElements?: number;
  signal?: AbortSignal;
  template?: DocumentSection;
  sections?: DocumentSection[];
  codeHighlighting?: CodeHighlightOptions;
  textReplacements?: TextReplacement[];
  imageHandling?: ImageHandlingOptions;
}
```

### Style
Text sizes and spacing options for document elements.

| Option                                        | Type                  | Description                              |
| --------------------------------------------- | --------------------- | ---------------------------------------- |
| `fontFamily`                                  | `string`              | Base font family                         |
| `fontFamilly`                                 | `string` (deprecated) | Alias for `fontFamily`                   |
| `titleSize`                                   | `number`              | Title size (half-points)                 |
| `heading1Size` … `heading6Size`               | `number`              | Per-level heading sizes                  |
| `paragraphSize`                               | `number`              | Paragraph size                           |
| `listItemSize`                                | `number`              | List item size                           |
| `codeBlockSize`                               | `number`              | Code block size                          |
| `inlineCodeSize`                              | `number`              | Inline code size                         |
| `inlineCodeColor`                             | `string`              | Inline code text color, RRGGBB           |
| `inlineCodeBackground`                        | `string`              | Inline code background, RRGGBB           |
| `blockquoteSize`                              | `number`              | Blockquote size                          |
| `tocFontSize`                                 | `number`              | TOC entry size (fallback for all levels) |
| `tocHeading1FontSize` … `tocHeading6FontSize` | `number`              | Per-level TOC entry size                 |
| `tocHeading1Bold` … `tocHeading6Bold`         | `boolean`             | Per-level TOC entry bold flag            |
| `tocHeading1Italic` … `tocHeading6Italic`     | `boolean`             | Per-level TOC entry italic flag          |

Spacing & layout

| Option             | Type       | Description                           |
| ------------------ | ---------- | ------------------------------------- |
| `headingSpacing`   | `number`   | Space before/after headings           |
| `paragraphSpacing` | `number`   | Space before/after paragraphs         |
| `lineSpacing`      | `number`   | Line spacing multiplier (e.g. `1.15`) |
| `tableLayout`      | `"autofit" | "fixed"`                              |

Alignment & direction

| Option                                    | Type    | Description         |
| ----------------------------------------- | ------- | ------------------- |
| `paragraphAlignment`                      | `"LEFT" | "RIGHT"`              |
| `blockquoteAlignment`                     | `"LEFT" | "RIGHT"`              |
| `headingAlignment`                        | `"LEFT" | "RIGHT"`              |
| `heading1Alignment` … `heading6Alignment` | Same    | Overrides per level |
| `direction`                               | `"LTR"  | "RTL"`              |

### TocOptions
Configuration for the Table of Contents.

| Field      | Type     | Description                                  |
| ---------- | -------- | -------------------------------------------- |
| `title`    | `string` | TOC title. Defaults to `Table of Contents`.  |
| `minDepth` | `number` | Minimum included heading level, from 1 to 6. |
| `maxDepth` | `number` | Maximum included heading level, from 1 to 6. |
```

--------------------------------

### CLI Error: Missing Arguments

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/cli.md

This error occurs when the required input and output file paths are not provided. Ensure both <input.md> and <output.docx> are specified.

```bash
Error: Expected exactly 2 positional arguments: <input.md> <output.docx>
```

--------------------------------

### Configure Code Highlighting with Language Whitelist

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/configuration.md

Enable code highlighting and specify a whitelist of languages to be highlighted. Unsupported or unlisted languages will be rendered as plain text.

```typescript
{
  codeHighlighting: {
    enabled: true,
    languages: ["typescript", "javascript", "python", "bash", "sql", "json"],
  }
}
```

--------------------------------

### Create Multi-Section Documents

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/README.md

Define global styles, template defaults, and per-section overrides for headers, footers, page numbering, and styles. Precedence is global > template > section.

```typescript
const blob = await convertMarkdownToDocx("", {
  style: { fontFamily: "Trebuchet MS", paragraphSize: 24 },
  template: {
    page: { margin: { top: 1440, right: 1080, bottom: 1440, left: 1080 } },
    pageNumbering: { display: "current", alignment: "CENTER" },
  },
  sections: [
    {
      markdown: "# My Report\n\nPrepared for ACME",
      footers: { default: null },
      pageNumbering: { display: "none" },
      style: { paragraphAlignment: "CENTER", paragraphSize: 28 },
    },
    {
      markdown: "[TOC]\n\n# Executive Summary\n\n…",
      titlePage: true,
      type: "NEXT_PAGE",
      headers: {
        default: { text: "Executive Summary", alignment: "RIGHT" },
        first: { text: "Executive Summary (First)", alignment: "RIGHT" },
      },
      footers: {
        default: {
          text: "Page",
          pageNumberDisplay: "currentAndSectionTotal",
          alignment: "RIGHT",
        },
      },
      pageNumbering: { start: 1, formatType: "decimal" },
      style: { paragraphAlignment: "JUSTIFIED" },
    },
    {
      markdown: "# Appendix\n\n…",
      type: "ODD_PAGE",
      page: { size: { orientation: "LANDSCAPE" } },
      pageNumbering: { start: 1, formatType: "upperRoman" },
      style: { paragraphSize: 22 },
    },
  ],
});
```

--------------------------------

### Batch Markdown to DOCX Conversion Script

Source: https://github.com/mohtashammurshid/md-to-docx/blob/main/_autodocs/api-reference/cli.md

A bash script to automate the conversion of all markdown files in the current directory to docx format.

```bash
#!/bin/bash
for md_file in *.md; do
  docx_file="${md_file%.md}.docx"
  echo "Converting $md_file → $docx_file"
  md-to-docx "$md_file" "$docx_file"
done
```