@mdgate/converters 0.6.7 → 0.6.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +178 -45
  2. package/package.json +33 -33
package/README.md CHANGED
@@ -1,63 +1,196 @@
1
1
  # @mdgate/converters
2
2
 
3
- Official mdgate converter bundle: every format converter in one install.
3
+ **Real-world files to Markdown, in pure TypeScript.**
4
4
 
5
- [Try the in-browser demo](https://demo.mdgate.dev). Full docs live in the
6
- [repository README](https://github.com/mdgate/converters#readme).
5
+ [`@mdgate/converters`](https://github.com/mdgate/converters/tree/main/packages/converters) is the complete deterministic reader: one `toMarkdown(bytes)` for PDF, Word, Excel, PowerPoint, OpenDocument, Apple iWork, HWP, WPS, email, OneNote, Visio, ebooks, archives, and more.
6
+
7
+ Works in **Node.js, Cloudflare Workers, Edge runtimes, and browsers**.
8
+
9
+ **No Python. No native addons. No WASM. No third-party runtime dependencies.**
10
+
11
+ ```bash
12
+ npm install @mdgate/converters
13
+ ```
14
+
15
+ ```ts
16
+ import { toMarkdown } from '@mdgate/converters';
17
+
18
+ const markdown = await toMarkdown(bytes, {
19
+ path: 'report.docx',
20
+ });
21
+ ```
22
+
23
+ The input is bytes. The output is Markdown.
24
+
25
+ [Convert a file in your browser](https://convert.mdgate.dev). Full docs live in the [repository README](https://github.com/mdgate/converters#readme).
26
+
27
+ ---
28
+
29
+ ## Why [`@mdgate/converters`](https://github.com/mdgate/converters/tree/main/packages/converters)
30
+
31
+ A JavaScript application that needs to read real-world files quickly becomes a collection of unrelated parsers.
32
+
33
+ This package puts them behind one interface:
34
+
35
+ ```text
36
+ Uint8Array → Markdown
37
+ ```
38
+
39
+ `toMarkdown` is `create(all())`. `all()` registers every converter that needs no configuration. Raster images, audio, and video need callbacks, so they are exported but not included in `all()`.
40
+
41
+ ---
42
+
43
+ ## One format
44
+
45
+ If your application only needs one format, install only that converter.
46
+
47
+ ```bash
48
+ npm install @mdgate/pdf
49
+ ```
50
+
51
+ ```ts
52
+ import { toMarkdown } from '@mdgate/pdf';
53
+
54
+ const markdown = await toMarkdown(bytes);
55
+ ```
56
+
57
+ ---
58
+
59
+ ## Your own set
60
+
61
+ ```ts
62
+ import { create } from '@mdgate/core';
63
+ import { pdf } from '@mdgate/pdf';
64
+ import { docx } from '@mdgate/docx';
65
+ import { xlsx } from '@mdgate/xlsx';
66
+
67
+ const read = create([
68
+ pdf(),
69
+ docx(),
70
+ xlsx(),
71
+ ]);
72
+ ```
73
+
74
+ Or start from `all()` and add media callbacks:
75
+
76
+ ```ts
77
+ import { all, create, image } from '@mdgate/converters';
78
+ import { ai } from '@mdgate/ai';
79
+
80
+ const media = ai({
81
+ baseURL: 'https://api.example.com/v1',
82
+ apiKey: process.env.API_KEY!,
83
+ model: 'your-model',
84
+ });
85
+
86
+ const read = create([
87
+ ...all(),
88
+ image(media.convertImage),
89
+ ]);
90
+ ```
91
+
92
+ ---
93
+
94
+ ## Node.js
95
+
96
+ ```ts
97
+ import { readFile } from 'node:fs/promises';
98
+ import { toMarkdown } from '@mdgate/converters';
99
+
100
+ const bytes = new Uint8Array(await readFile('report.docx'));
101
+ const markdown = await toMarkdown(bytes, {
102
+ path: 'report.docx',
103
+ });
104
+ ```
105
+
106
+ The optional `path` is a format hint. The converter never reads that path from disk.
107
+
108
+ ---
109
+
110
+ ## Cloudflare Workers and Edge runtimes
7
111
 
8
112
  ```ts
9
113
  import { toMarkdown } from '@mdgate/converters';
10
114
 
11
- const markdown = await toMarkdown(bytes, { path: 'notes.docx' });
115
+ export default {
116
+ async fetch(request: Request) {
117
+ const bytes = new Uint8Array(await request.arrayBuffer());
118
+ const markdown = await toMarkdown(bytes, {
119
+ path: request.headers.get('x-filename') ?? undefined,
120
+ });
121
+
122
+ return new Response(markdown, {
123
+ headers: {
124
+ 'content-type': 'text/markdown; charset=utf-8',
125
+ },
126
+ });
127
+ },
128
+ };
12
129
  ```
13
130
 
14
- Or compose converters yourself:
131
+ ---
132
+
133
+ ## Browser
15
134
 
16
135
  ```ts
17
- import { all, create } from '@mdgate/converters';
136
+ import { toMarkdown } from '@mdgate/converters';
137
+
138
+ const file = input.files![0];
139
+ const bytes = new Uint8Array(await file.arrayBuffer());
18
140
 
19
- const convert = create(all());
141
+ const markdown = await toMarkdown(bytes, {
142
+ path: file.name,
143
+ });
20
144
  ```
21
145
 
22
- `all()` registers every converter that needs no configuration. `image()`,
23
- `audio()`, and `video()` need callbacks, so they are exported but not included
24
- in `all()`.
146
+ [Try it in your browser](https://convert.mdgate.dev)
25
147
 
26
- Only need one format? Install just that package instead — for example
27
- `@mdgate/docx` — and call its identical `toMarkdown`.
148
+ ---
149
+
150
+ ## Packages
28
151
 
29
152
  | Package | Handles |
30
153
  |---|---|
31
- | `@mdgate/converters` | Bundle: every format below, `toMarkdown`, `all()` |
32
- | `@mdgate/docx` | docx, docm |
33
- | `@mdgate/doc` | doc (binary Word) |
34
- | `@mdgate/rtf` | rtf |
35
- | `@mdgate/pptx` | pptx, pptm, ppsx, ppsm |
36
- | `@mdgate/ppt` | ppt, pps, pot (binary PowerPoint) |
37
- | `@mdgate/xlsx` | xlsx, xlsm, xlsb, xls |
38
- | `@mdgate/csv` | csv |
39
- | `@mdgate/text` | txt, md, and source files |
40
- | `@mdgate/data` | json, jsonl, xml, yaml |
41
- | `@mdgate/subtitle` | srt, vtt, webvtt, ass, lrc, sub, sbv, ttml, jss |
42
- | `@mdgate/html` | html, htm, html4, html5, xhtml, mhtml, mht |
43
- | `@mdgate/email` | eml, msg, mbox, emlx |
44
- | `@mdgate/ipynb` | ipynb (Jupyter) |
45
- | `@mdgate/odf` | odt, ods, odp |
46
- | `@mdgate/pages` | pages |
47
- | `@mdgate/numbers` | numbers |
48
- | `@mdgate/keynote` | key |
49
- | `@mdgate/epub` | epub, ibooks |
50
- | `@mdgate/pdf` | pdf |
51
- | `@mdgate/fb2` | fb2, fb2.zip |
52
- | `@mdgate/mobi` | mobi, azw, azw3, prc |
53
- | `@mdgate/latex` | tex, latex, ltx |
54
- | `@mdgate/visio` | vsd, vsdx, vss, vst, vssx, vstx |
55
- | `@mdgate/onenote` | one, onetoc2, onepkg |
56
- | `@mdgate/hwp` | hwp, hwpx, hwt, hwtx |
57
- | `@mdgate/wps` | wps, wpt, et, ett, dps, dpt |
58
- | `@mdgate/zip` | zip, zipx, jar |
59
- | `@mdgate/image` | jpeg\*, png\*, webp\*, gif\*, tiff\*, heic\*, bmp\*, svg, svgz |
60
- | `@mdgate/audio` | mp3\*, wav\*, m4a\*, aac\*, ogg\*, flac\*, weba\* |
61
- | `@mdgate/video` | mp4\*, m4v\*, mov\*, webm\*, mkv\*, avi\* |
62
-
63
- \* Needs a callback — vision for raster images (`image()`), transcription for audio (`audio()`), video understanding for `video()`. Not registered by `all()`. SVG converts locally.
154
+ | [`@mdgate/converters`](https://github.com/mdgate/converters/tree/main/packages/converters) | Bundle: every deterministic format below, `toMarkdown`, `all()` |
155
+ | [`@mdgate/docx`](https://github.com/mdgate/converters/tree/main/packages/docx) | docx, docm |
156
+ | [`@mdgate/doc`](https://github.com/mdgate/converters/tree/main/packages/doc) | doc (binary Word) |
157
+ | [`@mdgate/rtf`](https://github.com/mdgate/converters/tree/main/packages/rtf) | rtf |
158
+ | [`@mdgate/pptx`](https://github.com/mdgate/converters/tree/main/packages/pptx) | pptx, pptm, ppsx, ppsm |
159
+ | [`@mdgate/ppt`](https://github.com/mdgate/converters/tree/main/packages/ppt) | ppt, pps, pot (binary PowerPoint) |
160
+ | [`@mdgate/xlsx`](https://github.com/mdgate/converters/tree/main/packages/xlsx) | xlsx, xlsm, xlsb, xls |
161
+ | [`@mdgate/csv`](https://github.com/mdgate/converters/tree/main/packages/csv) | csv |
162
+ | [`@mdgate/text`](https://github.com/mdgate/converters/tree/main/packages/text) | txt, md, and source files |
163
+ | [`@mdgate/data`](https://github.com/mdgate/converters/tree/main/packages/data) | json, jsonl, xml, yaml |
164
+ | [`@mdgate/subtitle`](https://github.com/mdgate/converters/tree/main/packages/subtitle) | srt, vtt, webvtt, ass, lrc, sub, sbv, ttml, jss |
165
+ | [`@mdgate/html`](https://github.com/mdgate/converters/tree/main/packages/html) | html, htm, html4, html5, xhtml, mhtml, mht |
166
+ | [`@mdgate/email`](https://github.com/mdgate/converters/tree/main/packages/email) | eml, msg, mbox, emlx |
167
+ | [`@mdgate/ipynb`](https://github.com/mdgate/converters/tree/main/packages/ipynb) | ipynb (Jupyter) |
168
+ | [`@mdgate/odf`](https://github.com/mdgate/converters/tree/main/packages/odf) | odt, ods, odp, odg |
169
+ | [`@mdgate/pages`](https://github.com/mdgate/converters/tree/main/packages/pages) | pages |
170
+ | [`@mdgate/numbers`](https://github.com/mdgate/converters/tree/main/packages/numbers) | numbers |
171
+ | [`@mdgate/keynote`](https://github.com/mdgate/converters/tree/main/packages/keynote) | key |
172
+ | [`@mdgate/epub`](https://github.com/mdgate/converters/tree/main/packages/epub) | epub, ibooks |
173
+ | [`@mdgate/pdf`](https://github.com/mdgate/converters/tree/main/packages/pdf) | pdf |
174
+ | [`@mdgate/fb2`](https://github.com/mdgate/converters/tree/main/packages/fb2) | fb2, fb2.zip |
175
+ | [`@mdgate/mobi`](https://github.com/mdgate/converters/tree/main/packages/mobi) | mobi, azw, azw3, prc |
176
+ | [`@mdgate/latex`](https://github.com/mdgate/converters/tree/main/packages/latex) | tex, latex, ltx |
177
+ | [`@mdgate/visio`](https://github.com/mdgate/converters/tree/main/packages/visio) | vsd, vsdx, vss, vst, vssx, vstx |
178
+ | [`@mdgate/onenote`](https://github.com/mdgate/converters/tree/main/packages/onenote) | one, onetoc2, onepkg |
179
+ | [`@mdgate/hwp`](https://github.com/mdgate/converters/tree/main/packages/hwp) | hwp, hwpx, hwt, hwtx |
180
+ | [`@mdgate/wps`](https://github.com/mdgate/converters/tree/main/packages/wps) | wps, wpt, et, ett, dps, dpt |
181
+ | [`@mdgate/zip`](https://github.com/mdgate/converters/tree/main/packages/zip) | zip, zipx, jar |
182
+ | [`@mdgate/image`](https://github.com/mdgate/converters/tree/main/packages/image) | jpeg\*, png\*, webp\*, gif\*, tiff\*, heic\*, bmp\*, svg, svgz |
183
+ | [`@mdgate/audio`](https://github.com/mdgate/converters/tree/main/packages/audio) | mp3\*, wav\*, m4a\*, aac\*, ogg\*, flac\*, weba\* |
184
+ | [`@mdgate/video`](https://github.com/mdgate/converters/tree/main/packages/video) | mp4\*, m4v\*, mov\*, webm\*, mkv\*, avi\* |
185
+
186
+ \* Needs a callback: vision for raster images (`image()`), transcription for audio (`audio()`), video understanding for `video()`. Not registered by `all()`. SVG converts locally.
187
+
188
+ [`@mdgate/converters`](https://github.com/mdgate/converters/tree/main/packages/converters) is the complete reader in the open-source [`mdgate/converters`](https://github.com/mdgate/converters) project.
189
+
190
+ For AI agents, the same converter architecture can be used to extend `read_file` from text files to real-world document formats.
191
+
192
+ ---
193
+
194
+ ## License
195
+
196
+ MIT
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@mdgate/converters",
3
- "version": "0.6.7",
3
+ "version": "0.6.9",
4
4
  "description": "Official mdgate converter bundle",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
- "homepage": "https://demo.mdgate.dev",
7
+ "homepage": "https://convert.mdgate.dev",
8
8
  "repository": {
9
9
  "type": "git",
10
10
  "url": "git+https://github.com/mdgate/converters.git",
@@ -28,37 +28,37 @@
28
28
  "prepublishOnly": "bun run build"
29
29
  },
30
30
  "dependencies": {
31
- "@mdgate/audio": "0.6.7",
32
- "@mdgate/core": "0.6.7",
33
- "@mdgate/csv": "0.6.7",
34
- "@mdgate/data": "0.6.7",
35
- "@mdgate/doc": "0.6.7",
36
- "@mdgate/docx": "0.6.7",
37
- "@mdgate/email": "0.6.7",
38
- "@mdgate/epub": "0.6.7",
39
- "@mdgate/fb2": "0.6.7",
40
- "@mdgate/html": "0.6.7",
41
- "@mdgate/hwp": "0.6.7",
42
- "@mdgate/image": "0.6.7",
43
- "@mdgate/ipynb": "0.6.7",
44
- "@mdgate/keynote": "0.6.7",
45
- "@mdgate/latex": "0.6.7",
46
- "@mdgate/mobi": "0.6.7",
47
- "@mdgate/numbers": "0.6.7",
48
- "@mdgate/odf": "0.6.7",
49
- "@mdgate/onenote": "0.6.7",
50
- "@mdgate/pages": "0.6.7",
51
- "@mdgate/pdf": "0.6.7",
52
- "@mdgate/ppt": "0.6.7",
53
- "@mdgate/pptx": "0.6.7",
54
- "@mdgate/rtf": "0.6.7",
55
- "@mdgate/subtitle": "0.6.7",
56
- "@mdgate/text": "0.6.7",
57
- "@mdgate/video": "0.6.7",
58
- "@mdgate/visio": "0.6.7",
59
- "@mdgate/wps": "0.6.7",
60
- "@mdgate/xlsx": "0.6.7",
61
- "@mdgate/zip": "0.6.7"
31
+ "@mdgate/audio": "0.6.9",
32
+ "@mdgate/core": "0.6.9",
33
+ "@mdgate/csv": "0.6.9",
34
+ "@mdgate/data": "0.6.9",
35
+ "@mdgate/doc": "0.6.9",
36
+ "@mdgate/docx": "0.6.9",
37
+ "@mdgate/email": "0.6.9",
38
+ "@mdgate/epub": "0.6.9",
39
+ "@mdgate/fb2": "0.6.9",
40
+ "@mdgate/html": "0.6.9",
41
+ "@mdgate/hwp": "0.6.9",
42
+ "@mdgate/image": "0.6.9",
43
+ "@mdgate/ipynb": "0.6.9",
44
+ "@mdgate/keynote": "0.6.9",
45
+ "@mdgate/latex": "0.6.9",
46
+ "@mdgate/mobi": "0.6.9",
47
+ "@mdgate/numbers": "0.6.9",
48
+ "@mdgate/odf": "0.6.9",
49
+ "@mdgate/onenote": "0.6.9",
50
+ "@mdgate/pages": "0.6.9",
51
+ "@mdgate/pdf": "0.6.9",
52
+ "@mdgate/ppt": "0.6.9",
53
+ "@mdgate/pptx": "0.6.9",
54
+ "@mdgate/rtf": "0.6.9",
55
+ "@mdgate/subtitle": "0.6.9",
56
+ "@mdgate/text": "0.6.9",
57
+ "@mdgate/video": "0.6.9",
58
+ "@mdgate/visio": "0.6.9",
59
+ "@mdgate/wps": "0.6.9",
60
+ "@mdgate/xlsx": "0.6.9",
61
+ "@mdgate/zip": "0.6.9"
62
62
  },
63
63
  "publishConfig": {
64
64
  "access": "public"