docx-convert
/docx-convert
Zamienia pliki Word DOCX na Markdown (GFM) i odwrotnie, z obsługą renderowania wzorów matematycznych.
- Autor
- duc01226 ↗
- Repozytorium
- EasyPlatform ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 20.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 21
- Skrypty
- 16
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 20.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 16 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/convert.cjs, tests/dispatcher.test.cjs, to-docx/scripts/convert.cjs, to-docx/scripts/lib/config-loader.cjs, to-docx/scripts/lib/converter.cjs, to-docx/scripts/lib/output-handler.cjs, to-docx/tests/converter.test.cjs, to-docx/tests/run-tests.cjs
Co robi i kiedy
Zamienia pliki Word DOCX na Markdown (GFM) i odwrotnie, z obsługą renderowania wzorów matematycznych.
Oryginalny opis (EN)
[Document Processing] Use when converting between Word DOCX and Markdown (GFM, math rendering). --to={markdown|docx}.
Jak działa
- Quick Summary
- Contents
- Directions
- Installation Required
- Quick Start
- CLI Options
- Features
- Conversion Pipeline (--to markdown)
- Output
- Compatibility (--to docx)
Podgląd SKILL.md
---
name: docx-convert
version: 2.0.0
description: '[Document Processing] Use when converting between Word DOCX and Markdown (GFM, math rendering). --to={markdown|docx}.'
disable-model-invocation: true
---
## Quick Summary
**Goal:** Convert Word DOCX to Markdown, or Markdown to Word DOCX, through one entry point.
**Workflow:**
1. **Pick a direction** — `--to markdown` (DOCX in, Markdown out) or `--to docx` (Markdown in, DOCX out)
2. **Install that direction** — each one has its own `package.json`; install only the one you need
3. **Convert** — run `scripts/convert.cjs --to <direction>` with the direction's own options
4. **Output** — the converter returns JSON with the success status and output path
**Key Rules:**
- `--to` is required. There is no default direction — converting the wrong way silently is worse than an error.
- Every other argument is passed straight to the chosen converter, so each direction keeps its own CLI.
- Dependencies are per direction: `--to markdown` never pulls in the DOCX writer, and vice versa.
**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).**
## Contents
- [Quick Summary](#quick-summary)
- [docx-convert](#docx-convert)
- [Directions](#directions)
- [Installation Required](#installation-required)
- [Quick Start](#quick-start)
- [CLI Options](#cli-options)
- [Features](#features)
- [Conversion Pipeline (`--to markdown`)](#conversion-pipeline---to-markdown)
- [Output](#output)
- [Compatibility (`--to docx`)](#compatibility---to-docx)
- [Limitations](#limitations)
- [Troubleshooting](#troubleshooting)
- [Tests](#tests)
- [Closing Reminders](#closing-reminders)
# docx-convert
Convert Microsoft Word (.docx) files to GitHub-Flavored Markdown, and Markdown files to editable
Word documents with tables, code blocks, images and LaTeX math.
## Directions
| Flag | Converts | Lives in | Dependencies |
| --------------- | --------------- | -------------- | ---------------------------------------- |
| `--to markdown` | DOCX → Markdown | `to-markdown/` | `mammoth`, `turndown`, `turndown-plugin-gfm` |
| `--to docx` | Markdown → DOCX | `to-docx/` | `markdown-docx`, `gray-matter` |
## Installation Required
**Each direction installs separately.** Install only the one you need:
```bash
# DOCX -> Markdown
cd .claude/skills/docx-convert/to-markdown
npm install
# Markdown -> DOCX
cd .claude/skills/docx-convert/to-docx
npm install
```
`ck init` (which runs `install.sh`) handles every skill at once.
## Quick Start
```bash
# DOCX -> Markdown
node .claude/skills/docx-convert/scripts/convert.cjs --to markdown --input ./document.docx
# DOCX -> Markdown, extracting images to a folder instead of inlining base64
node .claude/skills/docx-convert/scripts/convert.cjs --to markdown -i ./doc.docx --images ./images/
# Markdown -> DOCX
node .claude/skills/docx-convert/scripts/convert.cjs --to docx --input ./README.md
# Markdown -> DOCX with a custom theme
node .claude/skills/docx-convert/scripts/convert.cjs --to docx -i ./doc.md --theme ./theme.json
```
`--to=markdown` and `--to markdown` are equivalent. A missing or unknown `--to` prints the valid
directions and exits 1.
## CLI Options
### Dispatcher
| Option | Description | Default |
| -------- | ------------------------------------------- | ---------- |
| `--to` | Conversion direction: `markdown` or `docx` | (required) |
### `--to markdown` (DOCX → Markdown)
| Option | Short | Description | Default |
| ---------- | ----- | ------------------------------ | ------------- |
| `--input` | `-i` | Input DOCX file path | (required) |
| `--output` | `-o` | Output markdown file path | `{input}.md` |
| `--images` | | Directory for extracted images | inline base64 |
| `--help` | `-h` | Show help message | |
### `--to docx` (Markdown → DOCX)
| Option | Short | Description | Default |
| ---------- | ----- | ------------------- | -------------- |
| `--input` | `-i` | Input markdown file | (required) |
| `--output` | `-o` | Output DOCX path | `{input}.docx` |
| `--theme` | `-t` | Custom theme JSON | built-in |
| `--title` | | Document title | filename |
| `--help` | `-h` | Show help | |
Run `scripts/convert.cjs --to <direction> --help` to see a direction's full help.
## Features
**DOCX → Markdown**
- **GFM Tables:** Word tables become markdown tables
- **Images:** embedded images extracted (base64 inline, or written to a folder)
- **Lists:** ordered and unordered lists preserved
- **Code Blocks:** monospace text converted to code blocks
- **Links and Headings:** hyperlinks and heading levels maintained
**Markdown → DOCX**
- **GFM Support:** tables, strikethrough, task lists
- **Code Blocks:** syntax preserved with a monospace font
- **Images:** local and URL images embedded
- **Math:** LaTeX equations rendered by default (`$...$`, `$$...$$`)
- **Frontmatter:** YAML metadata supplies the title
- **No System Dependencies:** pure JavaScript, no Chrome needed
Both directions work on Windows, macOS and Linux.
## Conversion Pipeline (`--to markdown`)
```
DOCX → mammoth → HTML → turndown → Markdown
```
The two-stage conversion follows mammoth's official recommendation for best results.
## Output
Both directions return JSON on success:
```json
{
"success": true,
"input": "/path/to/input.docx",
"output": "/path/to/output.md",
"stats": {
"images": 3,
"tables": 2,
"headings": 5
}
}
```
`--to docx` omits `stats`. On failure both return `{ "success": false, "error": "..." }` and exit 1.
## Compatibility (`--to docx`)
Generated DOCX files open in Microsoft Word (2007+), Google Docs, LibreOffice Writer and Apple Pages.
## Limitations
- Complex layouts (columns, text boxes) may not preserve structure
- Merged table cells produce basic markdown tables
- Comments and track changes are stripped
- Some formatting (fonts, colors) is lost in conversion
## Troubleshooting
**Missing dependencies:** the error output carries a `hint` with the exact `cd … && npm install`
command for the direction you invoked.
## Tests
```bash
cd .claude/skills/docx-convert && node tests/dispatcher.test.cjs # routing and --to validation
cd .claude/skills/docx-convert/to-markdown && node tests/run-tests.cjs
cd .claude/skills/docx-convert/to-docx && node tests/run-tests.cjs
```
---
> **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting. This prevents context loss from long files. Keep task depth proportional to the work.
## Closing Reminders
**IMPORTANT MUST ATTENTION Goal:** Convert Word DOCX to Markdown, or Markdown to Word DOCX, through one entry point — `scripts/convert.cjs --to {markdown|docx}`.
**IMPORTANT MUST ATTENTION** `--to` is required — never guess the direction for the user
**IMPORTANT MUST ATTENTION** each direction installs its own dependencies; the error `hint` names the exact directory
**IMPORTANT MUST ATTENTION** break work into small todo tasks using `TaskCreate` BEFORE starting
**IMPORTANT MUST ATTENTION** search codebase for 3+ similar patterns before creating new code
**IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act)
**IMPORTANT MUST ATTENTION** add a final review todo task to verify work quality
**[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.
Pliki w paczce (21)
- SKILL.md 8 KB
- scripts/convert.cjs 3 KB
- tests/dispatcher.test.cjs 4 KB
- to-docx/package.json 1 KB
- to-docx/assets/default-theme.json 1 KB
- to-docx/scripts/convert.cjs 5 KB
- to-docx/scripts/lib/config-loader.cjs 2 KB
- to-docx/scripts/lib/converter.cjs 3 KB
- to-docx/scripts/lib/output-handler.cjs 2 KB
- to-docx/tests/converter.test.cjs 4 KB
- to-docx/tests/run-tests.cjs 1 KB
- to-docx/tests/test-framework.cjs 2 KB
- to-docx/tests/fixtures/sample.md 1 KB
- to-markdown/package.json 1 KB
- to-markdown/scripts/convert.cjs 5 KB
- to-markdown/scripts/lib/converter.cjs 4 KB
- to-markdown/scripts/lib/html-to-markdown.cjs 2 KB
- to-markdown/scripts/lib/output-handler.cjs 2 KB
- to-markdown/tests/converter.test.cjs 4 KB
- to-markdown/tests/run-tests.cjs 1 KB
- to-markdown/tests/test-framework.cjs 3 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · duc01226/EasyPlatform | 100 | MIT |
| duc01226/EasyPlatform | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki e7ad523df3f6 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100docx-delivery
Zamienia Markdown, tekst, raporty lub zadania w edytowalny dokument Word (.docx) i sprawdza wynik, gdy trzeba dostarczyć gotowy plik. - 95Docx
Przetwarza dokumenty Word (.docx), czyli tworzy, odczytuje i poprawia pliki Worda. - 90markdown-to-docx
Zamienia dokumenty Markdown na pliki Word (.docx) z nagłówkami, tabelami, listami, obrazami i cytatami. - 95Docx
Obsługuje pliki Word (.docx) przy tworzeniu, odczycie i poprawianiu dokumentów biurowych. - 95doc-to-markdown
Zamienia dokumenty Word .doc i .docx na czysty Markdown przy użyciu MinerU, do czytania lub edycji. - 100docx-generation
Przygotowuje raport DOCX z Markdownu, zamienia tabele i listy, a przy edycji istniejącego pliku zachowuje jego strukturę i style.