markit-ai 0.3.0 → 0.5.0

package/dist/commands/convert.d.ts

@@ -2,4 +2,5 @@ import type { OutputOptions } from "../utils/output.js";
 export declare function convert(source: string, options: OutputOptions & {
     output?: string;
     prompt?: string;
+    imageDir?: string;
 }): Promise<void>;

package/dist/commands/convert.js

@@ -1,4 +1,6 @@
-import { writeFileSync } from "node:fs";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { loadConfig } from "../config.js";
 import { Markit } from "../markit.js";
 import { loadAllPlugins } from "../plugins/loader.js";
@@ -23,6 +25,8 @@ export async function convert(source, options) {
     }
     const llmFunctions = createLlmFunctions(config, options.prompt);
     const markit = new Markit(llmFunctions, plugins);
+    // Auto-create a temp dir for images if not explicitly provided
+    const imageDir = options.imageDir || mkdtempSync(join(tmpdir(), "markit-images-"));
     try {
         let result;
         const isStdin = source === "-";
@@ -36,7 +40,7 @@ export async function convert(source, options) {
                 process.exit(EXIT_ERROR);
             }
             const buffer = await readStdin();
-            result = await markit.convert(buffer, {});
+            result = await markit.convert(buffer, { imageDir });
         }
         else if (isUrl) {
             // Progress hint for URL fetches (stderr so it doesn't pollute piped output)
@@ -46,7 +50,7 @@ export async function convert(source, options) {
             result = await markit.convertUrl(source);
         }
         else {
-            result = await markit.convertFile(source);
+            result = await markit.convertFile(source, { imageDir });
         }
         const label = isStdin ? "stdin" : source;
         // Write to file or stdout

package/dist/commands/formats.js

@@ -23,6 +23,26 @@ const BUILTIN_FORMATS = [
         extensions: [".mp3", ".wav", ".m4a", ".flac"],
         builtin: true,
     },
+    {
+        name: "Pages",
+        extensions: [".pages"],
+        builtin: true,
+    },
+    {
+        name: "Keynote",
+        extensions: [".key"],
+        builtin: true,
+    },
+    {
+        name: "Numbers",
+        extensions: [".numbers"],
+        builtin: true,
+    },
+    {
+        name: "GitHub",
+        extensions: ["github.com/*", "gist.github.com/*"],
+        builtin: true,
+    },
     { name: "ZIP", extensions: [".zip"], builtin: true },
     {
         name: "Plain text",

package/dist/converters/docx.d.ts

@@ -2,5 +2,5 @@ import type { ConversionResult, Converter, StreamInfo } from "../types.js";
 export declare class DocxConverter implements Converter {
     name: string;
     accepts(streamInfo: StreamInfo): boolean;
-    convert(input: Buffer, _streamInfo: StreamInfo): Promise<ConversionResult>;
+    convert(input: Buffer, streamInfo: StreamInfo): Promise<ConversionResult>;
 }

package/dist/converters/docx.js

@@ -1,3 +1,5 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import mammoth from "mammoth";
 import { createTurndown, normalizeTablesHtml } from "../utils/turndown.js";
 const EXTENSIONS = [".docx"];
@@ -16,10 +18,40 @@ export class DocxConverter {
         }
         return false;
     }
-    async convert(input, _streamInfo) {
-        const { value: html } = await mammoth.convertToHtml({ buffer: input });
+    async convert(input, streamInfo) {
+        const imageDir = streamInfo.imageDir;
+        if (imageDir) {
+            mkdirSync(imageDir, { recursive: true });
+        }
+        let imageCount = 0;
+        const convertImage = imageDir
+            ? mammoth.images.imgElement((image) => {
+                imageCount++;
+                const ext = (image.contentType?.split("/")[1] || "png").replace("jpeg", "jpg");
+                const filename = `image_${imageCount}.${ext}`;
+                const filepath = join(imageDir, filename);
+                return image.read("base64").then((base64) => {
+                    writeFileSync(filepath, Buffer.from(base64, "base64"));
+                    return { src: filepath, alt: `image_${imageCount}` };
+                });
+            })
+            : mammoth.images.imgElement((image) => {
+                imageCount++;
+                const contentType = image.contentType || "image/png";
+                return image.read("base64").then((base64) => {
+                    return {
+                        src: `data:${contentType};base64,${base64.slice(0, 0)}`,
+                        alt: `image_${imageCount}`,
+                    };
+                });
+            });
+        const { value: html } = await mammoth.convertToHtml({ buffer: input }, { convertImage });
         const turndown = createTurndown();
-        const markdown = turndown.turndown(normalizeTablesHtml(html));
+        let markdown = turndown.turndown(normalizeTablesHtml(html));
+        // Replace data URI images with comment placeholders when no imageDir
+        if (!imageDir) {
+            markdown = markdown.replace(/!\[([^\]]*)\]\(data:[^)]*\)/g, "<!-- image: $1 -->");
+        }
         return { markdown: markdown.trim() };
     }
 }

package/dist/converters/epub.js

@@ -23,6 +23,7 @@ export class EpubConverter {
             ignoreAttributes: false,
             attributeNamePrefix: "@_",
             textNodeName: "#text",
+            processEntities: { maxTotalExpansions: 1_000_000 },
         });
         // Find content.opf path from container.xml
         const containerXml = await zip

package/dist/converters/github.d.ts

@@ -0,0 +1,18 @@
+import type { ConversionResult, Converter, MarkitOptions, StreamInfo } from "../types.js";
+/**
+ * Matches GitHub URLs and fetches clean markdown content directly
+ * from raw endpoints or the GitHub API — no HTML scraping needed.
+ *
+ * Supported patterns:
+ *   - Repos:   github.com/owner/repo          → raw README.md
+ *   - Files:   github.com/owner/repo/blob/…   → raw file content
+ *   - Gists:   gist.github.com/owner/id       → raw gist content
+ *   - Issues:  github.com/owner/repo/issues/N  → API (title + body)
+ *   - PRs:     github.com/owner/repo/pull/N    → API (title + body)
+ */
+export declare class GitHubConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convertUrl(url: string, _options?: MarkitOptions): Promise<ConversionResult>;
+    convert(_input: Buffer, streamInfo: StreamInfo): Promise<ConversionResult>;
+}

package/dist/converters/github.js

@@ -0,0 +1,148 @@
+const GITHUB_HOSTS = new Set([
+    "github.com",
+    "www.github.com",
+    "gist.github.com",
+]);
+/**
+ * Matches GitHub URLs and fetches clean markdown content directly
+ * from raw endpoints or the GitHub API — no HTML scraping needed.
+ *
+ * Supported patterns:
+ *   - Repos:   github.com/owner/repo          → raw README.md
+ *   - Files:   github.com/owner/repo/blob/…   → raw file content
+ *   - Gists:   gist.github.com/owner/id       → raw gist content
+ *   - Issues:  github.com/owner/repo/issues/N  → API (title + body)
+ *   - PRs:     github.com/owner/repo/pull/N    → API (title + body)
+ */
+export class GitHubConverter {
+    name = "github";
+    accepts(streamInfo) {
+        if (!streamInfo.url)
+            return false;
+        try {
+            const { hostname } = new URL(streamInfo.url);
+            return GITHUB_HOSTS.has(hostname);
+        }
+        catch {
+            return false;
+        }
+    }
+    async convertUrl(url, _options) {
+        const parsed = new URL(url);
+        if (parsed.hostname === "gist.github.com") {
+            return fetchGist(parsed);
+        }
+        const segments = parsed.pathname.split("/").filter(Boolean);
+        // Need at least owner/repo
+        if (segments.length < 2) {
+            throw new Error(`Unsupported GitHub URL: ${url}`);
+        }
+        const [owner, repo, type, ...rest] = segments;
+        // github.com/owner/repo/blob/ref/path → raw file
+        if (type === "blob" && rest.length >= 2) {
+            const ref = rest[0];
+            const filePath = rest.slice(1).join("/");
+            return fetchRawFile(owner, repo, ref, filePath);
+        }
+        // github.com/owner/repo/issues/N or /pull/N
+        if ((type === "issues" || type === "pull") && rest[0]) {
+            const number = Number.parseInt(rest[0], 10);
+            if (!Number.isNaN(number)) {
+                return fetchIssueOrPr(owner, repo, number);
+            }
+        }
+        // github.com/owner/repo (no subpath or tree/wiki/etc) → README
+        if (!type) {
+            return fetchReadme(owner, repo);
+        }
+        throw new Error(`Unsupported GitHub URL pattern: ${url}`);
+    }
+    async convert(_input, streamInfo) {
+        // GitHub URLs are handled entirely via convertUrl.
+        // If we end up here, the URL was already fetched by the default path —
+        // just delegate to convertUrl.
+        if (streamInfo.url) {
+            return this.convertUrl(streamInfo.url);
+        }
+        throw new Error("GitHub converter requires a URL");
+    }
+}
+// ---------------------------------------------------------------------------
+// Fetchers
+// ---------------------------------------------------------------------------
+async function fetchReadme(owner, repo) {
+    const url = `https://raw.githubusercontent.com/${owner}/${repo}/HEAD/README.md`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch README: ${res.status} ${res.statusText}`);
+    }
+    const markdown = (await res.text()).trim();
+    const title = extractFirstHeading(markdown) ?? `${owner}/${repo}`;
+    return { markdown, title };
+}
+async function fetchRawFile(owner, repo, ref, filePath) {
+    const url = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${filePath}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch file: ${res.status} ${res.statusText}`);
+    }
+    const content = (await res.text()).trim();
+    const filename = filePath.split("/").pop() ?? filePath;
+    // If it's markdown, return as-is. Otherwise wrap in a code block.
+    if (filePath.endsWith(".md") || filePath.endsWith(".mdx")) {
+        const title = extractFirstHeading(content) ?? filename;
+        return { markdown: content, title };
+    }
+    const ext = filename.includes(".") ? filename.split(".").pop() : "";
+    const markdown = `# ${filename}\n\n\`\`\`${ext}\n${content}\n\`\`\``;
+    return { markdown, title: filename };
+}
+async function fetchGist(parsed) {
+    const segments = parsed.pathname.split("/").filter(Boolean);
+    // gist.github.com/owner/id
+    const [owner, id] = segments;
+    if (!owner || !id) {
+        throw new Error(`Unsupported gist URL: ${parsed.href}`);
+    }
+    const url = `https://gist.githubusercontent.com/${owner}/${id}/raw`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch gist: ${res.status} ${res.statusText}`);
+    }
+    const content = (await res.text()).trim();
+    const title = `gist:${id}`;
+    return { markdown: content, title };
+}
+async function fetchIssueOrPr(owner, repo, number) {
+    const url = `https://api.github.com/repos/${owner}/${repo}/issues/${number}`;
+    const res = await fetch(url, {
+        headers: { Accept: "application/vnd.github.v3+json" },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch issue/PR: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    const title = data.title ?? `#${number}`;
+    const parts = [`# ${title}`];
+    // Metadata line
+    const meta = [];
+    if (data.user?.login)
+        meta.push(`@${data.user.login}`);
+    if (data.state)
+        meta.push(data.state);
+    if (data.labels?.length) {
+        meta.push(data.labels.map((l) => l.name).join(", "));
+    }
+    if (meta.length > 0)
+        parts.push(meta.join(" · "));
+    if (data.body?.trim())
+        parts.push(data.body.trim());
+    return { markdown: parts.join("\n\n"), title };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function extractFirstHeading(markdown) {
+    const match = markdown.match(/^#\s+(.+)$/m);
+    return match?.[1]?.trim();
+}

package/dist/converters/iwork.d.ts

@@ -0,0 +1,20 @@
+import type { ConversionResult, Converter, StreamInfo } from "../types.js";
+/**
+ * Converts Apple iWork files (Pages, Keynote, Numbers) to markdown.
+ *
+ * All three formats are ZIP archives containing an XML file:
+ *   - Pages:   index.xml   (sf:p paragraphs with named styles)
+ *   - Keynote: index.apxl  (key:slide elements with sf:p text)
+ *   - Numbers: index.xml   (sf:t text cells + sf:n number cells)
+ */
+export declare class IWorkConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, streamInfo: StreamInfo): Promise<ConversionResult>;
+    private convertPages;
+    private convertKeynote;
+    private convertNumbers;
+    private extractGrid;
+    private convertNumbersFallback;
+    private readIndex;
+}

package/dist/converters/iwork.js

@@ -0,0 +1,391 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import JSZip from "jszip";
+const EXTENSIONS = [".pages", ".key", ".numbers"];
+const SF = "http://developer.apple.com/namespaces/sf";
+const SFA = "http://developer.apple.com/namespaces/sfa";
+const KEY = "http://developer.apple.com/namespaces/keynote2";
+/**
+ * Converts Apple iWork files (Pages, Keynote, Numbers) to markdown.
+ *
+ * All three formats are ZIP archives containing an XML file:
+ *   - Pages:   index.xml   (sf:p paragraphs with named styles)
+ *   - Keynote: index.apxl  (key:slide elements with sf:p text)
+ *   - Numbers: index.xml   (sf:t text cells + sf:n number cells)
+ */
+export class IWorkConverter {
+    name = "iwork";
+    accepts(streamInfo) {
+        if (streamInfo.extension && EXTENSIONS.includes(streamInfo.extension)) {
+            return true;
+        }
+        return false;
+    }
+    async convert(input, streamInfo) {
+        const zip = await JSZip.loadAsync(input);
+        const ext = streamInfo.extension;
+        if (ext === ".pages")
+            return this.convertPages(zip, streamInfo);
+        if (ext === ".key")
+            return this.convertKeynote(zip, streamInfo);
+        if (ext === ".numbers")
+            return this.convertNumbers(zip);
+        throw new Error(`Unsupported iWork format: ${ext}`);
+    }
+    // ---------------------------------------------------------------------------
+    // Pages
+    // ---------------------------------------------------------------------------
+    async convertPages(zip, streamInfo) {
+        const xml = await this.readIndex(zip, "index.xml");
+        const root = parseXml(xml);
+        const imageDir = streamInfo.imageDir;
+        if (imageDir)
+            mkdirSync(imageDir, { recursive: true });
+        let imageCount = 0;
+        const lines = [];
+        let title;
+        for (const p of iterAll(root, SF, "p")) {
+            const text = collectText(p).trim();
+            if (!text)
+                continue;
+            const style = p.getAttribute("sf:style") || "";
+            const prefix = paragraphPrefix(style);
+            if (!title && text.length > 0)
+                title = text;
+            lines.push(`${prefix}${text}`);
+        }
+        // Extract images
+        for (const name of Object.keys(zip.files)) {
+            if (!name.match(/\.(png|jpg|jpeg|gif|webp|tiff|bmp)$/i))
+                continue;
+            if (name.startsWith("QuickLook/"))
+                continue;
+            imageCount++;
+            const imgName = name.split("/").pop() || `image_${imageCount}`;
+            if (imageDir) {
+                const file = zip.file(name);
+                if (file) {
+                    const buf = await file.async("nodebuffer");
+                    const filepath = join(imageDir, imgName);
+                    writeFileSync(filepath, buf);
+                    lines.push(`![${imgName}](${filepath})`);
+                }
+            }
+            else {
+                lines.push(`<!-- image: ${imgName} -->`);
+            }
+        }
+        return { markdown: lines.join("\n\n"), title };
+    }
+    // ---------------------------------------------------------------------------
+    // Keynote
+    // ---------------------------------------------------------------------------
+    async convertKeynote(zip, streamInfo) {
+        const xml = await this.readIndex(zip, "index.apxl");
+        const root = parseXml(xml);
+        const imageDir = streamInfo.imageDir;
+        if (imageDir)
+            mkdirSync(imageDir, { recursive: true });
+        const sections = [];
+        let title;
+        const slides = [...iterAll(root, KEY, "slide")];
+        for (let i = 0; i < slides.length; i++) {
+            const slide = slides[i];
+            const slideLines = [`<!-- Slide ${i + 1} -->`];
+            const paragraphs = [...iterAll(slide, SF, "p")];
+            let isTitle = true;
+            for (const p of paragraphs) {
+                const text = collectText(p).trim();
+                if (!text)
+                    continue;
+                if (isTitle) {
+                    slideLines.push(`# ${text}`);
+                    if (!title)
+                        title = text;
+                    isTitle = false;
+                }
+                else {
+                    slideLines.push(text);
+                }
+            }
+            sections.push(slideLines.join("\n"));
+        }
+        // Extract media images
+        let imageCount = 0;
+        for (const name of Object.keys(zip.files)) {
+            if (!name.match(/\.(png|jpg|jpeg|gif|webp|tiff|bmp)$/i))
+                continue;
+            if (name.startsWith("QuickLook/"))
+                continue;
+            imageCount++;
+            const imgName = name.split("/").pop() || `image_${imageCount}`;
+            if (imageDir) {
+                const file = zip.file(name);
+                if (file) {
+                    const buf = await file.async("nodebuffer");
+                    const filepath = join(imageDir, imgName);
+                    writeFileSync(filepath, buf);
+                    sections.push(`![${imgName}](${filepath})`);
+                }
+            }
+            else {
+                sections.push(`<!-- image: ${imgName} -->`);
+            }
+        }
+        return { markdown: sections.join("\n\n"), title };
+    }
+    // ---------------------------------------------------------------------------
+    // Numbers
+    // ---------------------------------------------------------------------------
+    async convertNumbers(zip) {
+        const xml = await this.readIndex(zip, "index.xml");
+        const root = parseXml(xml);
+        // Find grid elements (tables)
+        const grids = [...iterAll(root, SF, "grid")];
+        if (grids.length === 0) {
+            // Fallback: extract all text and number cells
+            return this.convertNumbersFallback(root);
+        }
+        const sections = [];
+        for (const grid of grids) {
+            const rows = this.extractGrid(grid);
+            if (rows.length === 0)
+                continue;
+            const maxCols = Math.max(...rows.map((r) => r.length));
+            for (const row of rows) {
+                while (row.length < maxCols)
+                    row.push("");
+            }
+            const [header, ...body] = rows;
+            const lines = [];
+            lines.push(`| ${header.join(" | ")} |`);
+            lines.push(`| ${header.map(() => "---").join(" | ")} |`);
+            for (const row of body) {
+                lines.push(`| ${row.join(" | ")} |`);
+            }
+            sections.push(lines.join("\n"));
+        }
+        return { markdown: sections.join("\n\n") };
+    }
+    extractGrid(grid) {
+        const datasource = findFirst(grid, SF, "datasource");
+        if (!datasource)
+            return [];
+        const rows = [];
+        let currentRow = [];
+        let colCount = 0;
+        let totalCells = 0;
+        const allValues = [];
+        // Get column count from grid attributes (raw attribute names)
+        const numCols = Number.parseInt(grid.getAttribute("sf:numcols") || "0", 10);
+        for (const child of datasource.children) {
+            const tag = child.tagName;
+            let value = "";
+            if (tag === `${SF}:t`) {
+                // Text cell
+                const ct = findFirst(child, SF, "ct");
+                value = ct?.getAttribute("sfa:s") || collectText(child).trim();
+            }
+            else if (tag === `${SF}:n`) {
+                // Number cell
+                value = child.getAttribute("sf:v") || "";
+            }
+            else if (tag === `${SF}:b`) {
+                // Boolean cell
+                value = child.getAttribute("sf:v") === "1" ? "TRUE" : "FALSE";
+            }
+            else if (tag === `${SF}:d`) {
+                // Date cell
+                value = child.getAttribute("sf:v") || "";
+            }
+            else if (tag === `${SF}:du`) {
+                // Duration cell
+                value = child.getAttribute("sf:v") || "";
+            }
+            else if (tag === `${SF}:e`) {
+                // Empty cell
+                value = "";
+            }
+            else {
+                continue;
+            }
+            currentRow.push(value);
+            allValues.push(value);
+            colCount++;
+            totalCells++;
+            if (numCols > 0 && colCount >= numCols) {
+                rows.push(currentRow);
+                currentRow = [];
+                colCount = 0;
+            }
+        }
+        if (currentRow.length > 0)
+            rows.push(currentRow);
+        // If the grid used default dimensions and produced only one row,
+        // the data probably doesn't fill the full grid width. Fall back to
+        // treating the cells as a 2-column key/value list or single column.
+        if (rows.length <= 1 && totalCells > 0 && totalCells < numCols) {
+            // Re-layout: try 2 columns if even, otherwise single column
+            const cols = totalCells % 2 === 0 ? 2 : 1;
+            const relaid = [];
+            for (let i = 0; i < allValues.length; i += cols) {
+                relaid.push(allValues.slice(i, i + cols));
+            }
+            return relaid;
+        }
+        return rows;
+    }
+    convertNumbersFallback(root) {
+        const values = [];
+        for (const t of iterAll(root, SF, "t")) {
+            const ct = findFirst(t, SF, "ct");
+            const val = ct?.getAttribute("sfa:s") || "";
+            if (val)
+                values.push(val);
+        }
+        for (const n of iterAll(root, SF, "n")) {
+            const val = n.getAttribute("sf:v") || "";
+            if (val)
+                values.push(val);
+        }
+        return { markdown: values.join("\n") };
+    }
+    // ---------------------------------------------------------------------------
+    // Helpers
+    // ---------------------------------------------------------------------------
+    async readIndex(zip, filename) {
+        const file = zip.file(filename);
+        if (!file) {
+            throw new Error(`Invalid iWork file: missing ${filename}`);
+        }
+        return file.async("string");
+    }
+}
+/**
+ * Minimal XML parser that preserves namespace prefixes in tag names
+ * and extracts text content and attributes.
+ */
+function parseXml(xml) {
+    // Use a simple recursive descent approach
+    const root = createElement("root");
+    const stack = [root];
+    // Match tags and text
+    const tagRe = /<(\/?)([a-zA-Z0-9_:.-]+)((?:\s+[a-zA-Z0-9_:.-]+\s*=\s*"[^"]*")*)\s*(\/?)>/g;
+    let lastIndex = 0;
+    let match = tagRe.exec(xml);
+    while (match !== null) {
+        const [fullMatch, isClose, tagName, attrs, isSelfClose] = match;
+        const textBefore = xml.slice(lastIndex, match.index);
+        lastIndex = match.index + fullMatch.length;
+        // Add text to current element
+        if (textBefore.trim()) {
+            const current = stack[stack.length - 1];
+            if (current.children.length > 0) {
+                current.children[current.children.length - 1].tail += textBefore.trim();
+            }
+            else {
+                current.text += textBefore.trim();
+            }
+        }
+        if (isClose) {
+            // Closing tag
+            stack.pop();
+        }
+        else {
+            // Opening tag
+            const el = createElement(expandTag(tagName, xml));
+            parseAttributes(attrs, el);
+            stack[stack.length - 1].children.push(el);
+            if (!isSelfClose) {
+                stack.push(el);
+            }
+        }
+        match = tagRe.exec(xml);
+    }
+    return root;
+}
+function createElement(tagName) {
+    return {
+        tagName,
+        children: [],
+        text: "",
+        tail: "",
+        attributes: {},
+        getAttribute(name) {
+            return this.attributes[name] ?? null;
+        },
+    };
+}
+function parseAttributes(attrStr, el) {
+    const attrRe = /([a-zA-Z0-9_:.-]+)\s*=\s*"([^"]*)"/g;
+    let m = attrRe.exec(attrStr);
+    while (m !== null) {
+        el.attributes[m[1]] = m[2];
+        m = attrRe.exec(attrStr);
+    }
+}
+/**
+ * Expand namespace prefix in tag name to full URI.
+ * e.g. "sf:p" with xmlns:sf="..." → "{uri}p"
+ * For simplicity, we use the known Apple namespaces.
+ */
+function expandTag(tag, _xml) {
+    const nsMap = {
+        sf: SF,
+        sfa: SFA,
+        sl: "http://developer.apple.com/namespaces/sl",
+        key: KEY,
+    };
+    const colon = tag.indexOf(":");
+    if (colon === -1)
+        return tag;
+    const prefix = tag.slice(0, colon);
+    const local = tag.slice(colon + 1);
+    const uri = nsMap[prefix];
+    return uri ? `${uri}:${local}` : tag;
+}
+function collectText(el) {
+    let result = el.text;
+    for (const child of el.children) {
+        result += collectText(child);
+        result += child.tail;
+    }
+    return result;
+}
+function* iterAll(el, ns, localName) {
+    const fullTag = `${ns}:${localName}`;
+    if (el.tagName === fullTag)
+        yield el;
+    for (const child of el.children) {
+        yield* iterAll(child, ns, localName);
+    }
+}
+function findFirst(el, ns, localName) {
+    for (const found of iterAll(el, ns, localName)) {
+        return found;
+    }
+    return null;
+}
+/**
+ * Map iWork paragraph style names to markdown heading prefixes.
+ */
+function paragraphPrefix(style) {
+    if (!style)
+        return "";
+    const lower = style.toLowerCase();
+    if (lower.includes("title"))
+        return "# ";
+    if (lower.includes("subtitle"))
+        return "## ";
+    if (lower.includes("heading-1") || lower.includes("heading 1"))
+        return "## ";
+    if (lower.includes("heading-2") || lower.includes("heading 2"))
+        return "### ";
+    if (lower.includes("heading-3") || lower.includes("heading 3"))
+        return "#### ";
+    if (lower.includes("heading-4") || lower.includes("heading 4"))
+        return "##### ";
+    if (lower.includes("caption"))
+        return "*";
+    return "";
+}

package/dist/converters/pptx.d.ts

@@ -2,7 +2,7 @@ import type { ConversionResult, Converter, StreamInfo } from "../types.js";
 export declare class PptxConverter implements Converter {
     name: string;
     accepts(streamInfo: StreamInfo): boolean;
-    convert(input: Buffer, _streamInfo: StreamInfo): Promise<ConversionResult>;
+    convert(input: Buffer, streamInfo: StreamInfo): Promise<ConversionResult>;
     private extractText;
     private extractTable;
 }

package/dist/converters/pptx.js

@@ -1,3 +1,5 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { XMLParser } from "fast-xml-parser";
 import JSZip from "jszip";
 const EXTENSIONS = [".pptx"];
@@ -14,12 +16,13 @@ export class PptxConverter {
             return true;
         return false;
     }
-    async convert(input, _streamInfo) {
+    async convert(input, streamInfo) {
         const zip = await JSZip.loadAsync(input);
         const parser = new XMLParser({
             ignoreAttributes: false,
             attributeNamePrefix: "@_",
             textNodeName: "#text",
+            processEntities: { maxTotalExpansions: 1_000_000 },
         });
         // Get slide order from presentation.xml
         const presXml = await zip.file("ppt/presentation.xml")?.async("string");
@@ -66,7 +69,12 @@ export class PptxConverter {
             });
             slidePaths.push(...slideFiles);
         }
+        const imageDir = streamInfo.imageDir;
+        if (imageDir) {
+            mkdirSync(imageDir, { recursive: true });
+        }
         const sections = [];
+        let imageCount = 0;
         for (let i = 0; i < slidePaths.length; i++) {
             const slideXml = await zip.file(slidePaths[i])?.async("string");
             if (!slideXml)
@@ -75,6 +83,17 @@ export class PptxConverter {
             const spTree = slide["p:sld"]?.["p:cSld"]?.["p:spTree"];
             if (!spTree)
                 continue;
+            // Parse slide-level rels for image references
+            const slideRelsPath = `${slidePaths[i].replace("slides/slide", "slides/_rels/slide")}.rels`;
+            const slideRelsXml = await zip.file(slideRelsPath)?.async("string");
+            const slideRelMap = new Map();
+            if (slideRelsXml) {
+                const slideRels = parser.parse(slideRelsXml);
+                const relItems = toList(slideRels?.Relationships?.Relationship);
+                for (const r of relItems) {
+                    slideRelMap.set(r["@_Id"], r["@_Target"]);
+                }
+            }
             const slideLines = [`<!-- Slide ${i + 1} -->`];
             const shapes = spTree["p:sp"];
             const shapeList = Array.isArray(shapes) ? shapes : shapes ? [shapes] : [];
@@ -91,6 +110,55 @@ export class PptxConverter {
                     slideLines.push(text);
                 }
             }
+            // Extract embedded images
+            const pics = toList(spTree["p:pic"]);
+            for (const pic of pics) {
+                const blipFill = pic["p:blipFill"];
+                const rEmbed = blipFill?.["a:blip"]?.["@_r:embed"];
+                if (!rEmbed)
+                    continue;
+                const target = slideRelMap.get(rEmbed);
+                if (!target)
+                    continue;
+                // Resolve relative target against slide directory
+                const imagePath = target.startsWith("/")
+                    ? target.slice(1)
+                    : `ppt/slides/${target}`;
+                // Normalize path (e.g. ppt/slides/../media/image1.png → ppt/media/image1.png)
+                const normalizedPath = imagePath
+                    .split("/")
+                    .reduce((parts, seg) => {
+                    if (seg === "..")
+                        parts.pop();
+                    else
+                        parts.push(seg);
+                    return parts;
+                }, [])
+                    .join("/");
+                const imageFile = zip.file(normalizedPath);
+                if (!imageFile)
+                    continue;
+                imageCount++;
+                const name = pic["p:nvSpPr"]?.["p:cNvPr"]?.["@_name"] ||
+                    pic["p:nvPicPr"]?.["p:cNvPr"]?.["@_name"] ||
+                    `image_${imageCount}`;
+                if (imageDir) {
+                    try {
+                        const ext = normalizedPath.split(".").pop() || "png";
+                        const filename = `slide${i + 1}_${imageCount}.${ext}`;
+                        const filepath = join(imageDir, filename);
+                        const buf = await imageFile.async("nodebuffer");
+                        writeFileSync(filepath, buf);
+                        slideLines.push(`![${name}](${filepath})`);
+                    }
+                    catch {
+                        slideLines.push(`<!-- image: ${name} (slide ${i + 1}) -->`);
+                    }
+                }
+                else {
+                    slideLines.push(`<!-- image: ${name} (slide ${i + 1}) -->`);
+                }
+            }
             // Tables
             const graphicFrames = spTree["p:graphicFrame"];
             const gfList = Array.isArray(graphicFrames)
@@ -214,3 +282,8 @@ export class PptxConverter {
         return lines.join("\n");
     }
 }
+function toList(val) {
+    if (!val)
+        return [];
+    return Array.isArray(val) ? val : [val];
+}

package/dist/converters/xlsx.js

@@ -20,6 +20,7 @@ export class XlsxConverter {
             ignoreAttributes: false,
             attributeNamePrefix: "@_",
             textNodeName: "#text",
+            processEntities: { maxTotalExpansions: 1_000_000 },
         });
         // Parse shared strings
         const ssXml = await zip.file("xl/sharedStrings.xml")?.async("string");

package/dist/index.d.ts

@@ -3,9 +3,11 @@ export { AudioConverter } from "./converters/audio.js";
 export { CsvConverter } from "./converters/csv.js";
 export { DocxConverter } from "./converters/docx.js";
 export { EpubConverter } from "./converters/epub.js";
+export { GitHubConverter } from "./converters/github.js";
 export { HtmlConverter } from "./converters/html.js";
 export { ImageConverter } from "./converters/image.js";
 export { IpynbConverter } from "./converters/ipynb.js";
+export { IWorkConverter } from "./converters/iwork.js";
 export { JsonConverter } from "./converters/json.js";
 export { PdfConverter } from "./converters/pdf/index.js";
 export { PlainTextConverter } from "./converters/plain-text.js";

package/dist/index.js

@@ -2,9 +2,11 @@ export { AudioConverter } from "./converters/audio.js";
 export { CsvConverter } from "./converters/csv.js";
 export { DocxConverter } from "./converters/docx.js";
 export { EpubConverter } from "./converters/epub.js";
+export { GitHubConverter } from "./converters/github.js";
 export { HtmlConverter } from "./converters/html.js";
 export { ImageConverter } from "./converters/image.js";
 export { IpynbConverter } from "./converters/ipynb.js";
+export { IWorkConverter } from "./converters/iwork.js";
 export { JsonConverter } from "./converters/json.js";
 export { PdfConverter } from "./converters/pdf/index.js";
 export { PlainTextConverter } from "./converters/plain-text.js";

package/dist/main.js

@@ -18,6 +18,7 @@ program
     .option("-q, --quiet", "Raw markdown only, no decoration")
     .option("-p, --prompt <text>", "Extra instructions for image description")
     .option("-o, --output <file>", "Write to file instead of stdout")
+    .option("-i, --image-dir <dir>", "Extract images to this directory")
     .addHelpText("after", `
 Examples:
   $ markit report.pdf                  Convert a PDF to markdown
@@ -42,7 +43,8 @@ program
         json: globals.json,
         quiet: globals.quiet,
         output: opts.output,
-        prompt: opts.prompt,
+        prompt: globals.prompt,
+        imageDir: globals.imageDir,
     });
 });
 program
@@ -144,6 +146,7 @@ program.on("command:*", async (args) => {
         quiet: globals.quiet,
         output: globals.output,
         prompt: globals.prompt,
+        imageDir: globals.imageDir,
     });
 });
 // No args → show concise help

package/dist/markit.d.ts

@@ -7,7 +7,7 @@ export declare class Markit {
     /**
      * Convert a local file to markdown.
      */
-    convertFile(path: string): Promise<ConversionResult>;
+    convertFile(path: string, extra?: Partial<StreamInfo>): Promise<ConversionResult>;
     /**
      * Convert a URL to markdown.
      */

package/dist/markit.js

@@ -4,9 +4,11 @@ import { AudioConverter } from "./converters/audio.js";
 import { CsvConverter } from "./converters/csv.js";
 import { DocxConverter } from "./converters/docx.js";
 import { EpubConverter } from "./converters/epub.js";
+import { GitHubConverter } from "./converters/github.js";
 import { HtmlConverter } from "./converters/html.js";
 import { ImageConverter } from "./converters/image.js";
 import { IpynbConverter } from "./converters/ipynb.js";
+import { IWorkConverter } from "./converters/iwork.js";
 import { JsonConverter } from "./converters/json.js";
 import { PdfConverter } from "./converters/pdf/index.js";
 import { PlainTextConverter } from "./converters/plain-text.js";
@@ -32,6 +34,8 @@ export class Markit {
             new XlsxConverter(),
             new EpubConverter(),
             new IpynbConverter(),
+            new IWorkConverter(),
+            new GitHubConverter(),
             new WikipediaConverter(),
             new RssConverter(),
             new CsvConverter(),
@@ -56,12 +60,13 @@ export class Markit {
     /**
      * Convert a local file to markdown.
      */
-    async convertFile(path) {
+    async convertFile(path, extra) {
         const buffer = readFileSync(path);
         const streamInfo = {
             localPath: path,
             extension: extname(path).toLowerCase(),
             filename: basename(path),
+            ...extra,
         };
         return this.convert(buffer, streamInfo);
     }
@@ -69,6 +74,18 @@ export class Markit {
      * Convert a URL to markdown.
      */
     async convertUrl(url) {
+        // Let converters with a URL-specific hook handle it first
+        const streamInfo = { url };
+        for (const converter of this.converters) {
+            if (!converter.convertUrl || !converter.accepts(streamInfo))
+                continue;
+            try {
+                return await converter.convertUrl(url, this.options);
+            }
+            catch {
+                // Fall through to default fetch path
+            }
+        }
         const response = await fetch(url, {
             headers: {
                 Accept: "text/markdown, text/html;q=0.9, text/plain;q=0.8, */*;q=0.1",
@@ -84,13 +101,13 @@ export class Markit {
         const urlPath = new URL(url).pathname;
         const ext = extname(urlPath).toLowerCase();
         const buffer = Buffer.from(await response.arrayBuffer());
-        const streamInfo = {
+        const fetchedInfo = {
             url,
             mimetype: mimetype.trim(),
             extension: ext || undefined,
             filename: basename(urlPath) || undefined,
         };
-        return this.convert(buffer, streamInfo);
+        return this.convert(buffer, fetchedInfo);
     }
     /**
      * Convert a buffer with stream info to markdown.

package/dist/types.d.ts

@@ -25,6 +25,12 @@ export interface Converter {
     name: string;
     /** Quick check: can this converter handle the given stream? */
     accepts(streamInfo: StreamInfo): boolean;
+    /**
+     * Optional URL-first hook. When present, called before the default fetch
+     * so the converter can handle URL fetching itself (e.g. rewrite to a raw
+     * content URL or call an API).
+     */
+    convertUrl?(url: string, options?: MarkitOptions): Promise<ConversionResult>;
     /** Convert the source to markdown */
     convert(input: Buffer, streamInfo: StreamInfo, options?: MarkitOptions): Promise<ConversionResult>;
 }

package/dist/utils/turndown.js

@@ -51,8 +51,14 @@ export function createTurndown() {
  * - Strip <p> tags inside <td>/<th> cells
  */
 export function normalizeTablesHtml(html) {
-    // Strip <p> tags inside table cells
-    let result = html.replace(/<(td|th)([^>]*)>\s*<p>([\s\S]*?)<\/p>\s*<\/(td|th)>/gi, "<$1$2>$3</$4>");
+    // Strip <p> tags inside table cells, joining multiple paragraphs with <br>
+    let result = html.replace(/<(td|th)([^>]*)>([\s\S]*?)<\/(td|th)>/gi, (_match, tag, attrs, inner, closeTag) => {
+        const stripped = inner
+            .replace(/^\s*<p>/i, "")
+            .replace(/<\/p>\s*$/i, "")
+            .replace(/<\/p>\s*<p>/gi, " ");
+        return `<${tag}${attrs}>${stripped}</${closeTag}>`;
+    });
     // Add thead to tables that lack it
     result = result.replace(/<table([^>]*)>\s*(?:<tbody>\s*)?(<tr[\s\S]*?<\/tr>)([\s\S]*?)<\/(?:tbody>\s*<\/)?table>/gi, (_match, attrs, firstRow, rest) => {
         const theadRow = firstRow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markit-ai",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Convert anything to markdown. PDF, DOCX, PPTX, XLSX, HTML, EPUB, Jupyter, RSS, images, audio, URLs, and more. Pluggable converters, built-in LLM providers for image description and audio transcription. Works as a CLI and as a library.",
   "type": "module",
   "main": "dist/index.js",