[Share] Pandoc export script — Better Notes → Word (.docx) with image & link support

[Stream-L]

Description

我用LLM结合Better Notes源码开发了一个 Pandoc 导出脚本，适用于 Zotero + Better Notes —— 它可以将 Better Notes 中的笔记导出为格式统一、美观的 Word (.docx) 文档。脚本支持：

• Markdown 转换 + Pandoc 导出
• 图片自动嵌入
• Zotero 引用链接（可选为超链接或纯文本）
• 应用用户自定义 Word 模板，以统一字体、段落、标题样式 （修改脚本中用户配置区域 (USER CONFIGURATION)的模板路径）
• 单个笔记导出 / 批量导出

如果你也想要自定义 Better Notes 笔记导出的Word样式，这个脚本也许能帮你节省手动排版的时间。欢迎大家测试改进。
特别是pandoc其实支持丰富的格式转换，但是当前脚本仅实现了简单的word文档导出， 期待新的作品。

---

Hello everyone!

I developed a Pandoc export script by combining an LLM with the source code of Better Notes. It’s designed for Zotero + Better Notes, and lets you export notes from Better Notes into a clean, well‑formatted Word (.docx) document. The script supports:

• Markdown conversion + export via Pandoc
• Automatic embedding of images
• Zotero link support (optionally as clickable hyperlinks or plain text)
• Applying a user‑defined Word template (by modifying the template path in the script’s USER CONFIGURATION) to enforce consistent font, paragraph and heading styles
• Exporting a single note or exporting multiple notes in batch

If you want to customize the style of Word documents exported from Better Notes, this script might save you a lot of time on manual formatting. You are welcome to test it and propose improvements.

Because Pandoc actually supports rich format conversion, the current script only implements a simple Word document export — I look forward to more advanced contributions and further works from the community.

Event

None

Operation

Script

Data

/**
 * Pandoc Export Script for Zotero Better Notes
 * 
 * 功能：将 Zotero 笔记导出为 Word (docx) 文档，支持图片和引用链接
 * 
 * 作者：Stream-L
 * 日期：2025-12-01
 * 版本：2.0
  */

// ============================================================================
//  用户配置区域 (USER CONFIGURATION)
//  ============================================================================
const USER_CONFIG = {
    // Pandoc 可执行文件搜索路径列表
    // 脚本会依次检查这些路径，直到找到可用的 Pandoc
    pandocPaths: [
        "C:\\Program Files\\Pandoc\\pandoc.exe",
        "C:\\Program Files (x86)\\Pandoc\\pandoc.exe",
        "pandoc", // 尝试系统 PATH
    ],

    // Word 模板路径 (.docx) 需要自行修改否则为默认模板
    // 模板中的样式（字体、段落格式等）将被应用到输出文档
    templatePath: "C:\\Users\\STREAM\\Documents\\template\\pandoc\\不编号templates_报告自用.docx",

    // 导出选项
    options: {
        // 链接样式: "hyperlink" 或 "text"
        // "hyperlink" - 生成可点击的超链接
        // "text" - 仅保留文本，去除链接
        linkStyle: "hyperlink",
        
        // 是否处理图片（解析 Better Notes 的图片格式）
        processImages: true,
        
        // 调试模式（打印更多日志）
        debug: true
    }
};

// ============================================================================
// 脚本主体 - 请勿修改以下代码
// ============================================================================

// 阻止脚本多次执行
if (typeof item !== "undefined" && item) return;

const Zotero = require("Zotero");
const window = require("window");
const { Services } = ChromeUtils.import("resource://gre/modules/Services.jsm");

// 获取选中的条目
let selectedItems = [];
if (typeof items !== "undefined" && items.length > 0) {
    selectedItems = items;
} else if (typeof item !== "undefined") {
    selectedItems = [item];
} else {
    window.alert("请先选择要处理的条目");
    return;
}

const CONFIG = {
    templatePath: USER_CONFIG.templatePath,
    pandocPath: null,
    ...USER_CONFIG.options
};

// ============================================================================
// 核心函数
// ============================================================================

/**
 * 查找 Pandoc 可执行文件
 */
async function findPandoc() {
    const localAppData = Services.env.get("LOCALAPPDATA");
    const searchPaths = [
        ...USER_CONFIG.pandocPaths,
        `${localAppData}\\Pandoc\\pandoc.exe`
    ];

    for (const path of searchPaths) {
        if (!path) continue;
        
        if (path === "pandoc") continue; // 跳过，最后尝试
        
        if (await IOUtils.exists(path)) {
            Zotero.debug(`[Pandoc Export] 找到 Pandoc: ${path}`);
            return path;
        }
    }

    if (USER_CONFIG.pandocPaths.includes("pandoc")) {
        return "pandoc";
    }

    throw new Error(
        "无法找到 Pandoc 可执行文件。\n\n" +
        "请使用以下方法之一安装：\n" +
        "1. Winget: winget install Pandoc.Pandoc\n" +
        "2. Chocolatey: choco install pandoc\n" +
        "3. 官网下载: https://pandoc.org/installing.html\n\n" +
        "安装后请重新运行此脚本。"
    );
}

/**
 * 选择保存文件路径
 */
function pickSaveFile(defaultName) {
    return new Promise((resolve) => {
        const nsIFilePicker = Components.interfaces.nsIFilePicker;
        const fp = Components.classes["@mozilla.org/filepicker;1"]
            .createInstance(nsIFilePicker);
        
        fp.init(window, "保存 Word 文档", nsIFilePicker.modeSave);
        fp.appendFilter("Word 文档 (*.docx)", "*.docx");
        fp.defaultString = defaultName;
        fp.defaultExtension = "docx";
        
        fp.open((result) => {
            if (result === nsIFilePicker.returnOK || result === nsIFilePicker.returnReplace) {
                let path = fp.file.path;
                if (!path.toLowerCase().endsWith(".docx")) {
                    path += ".docx";
                }
                resolve(path);
            } else {
                resolve(null);
            }
        });
    });
}

/**
 * 选择输出目录
 */
function pickDirectory() {
    return new Promise((resolve) => {
        const nsIFilePicker = Components.interfaces.nsIFilePicker;
        const fp = Components.classes["@mozilla.org/filepicker;1"]
            .createInstance(nsIFilePicker);
        
        fp.init(window, "选择输出目录", nsIFilePicker.modeGetFolder);
        
        fp.open((result) => {
            if (result === nsIFilePicker.returnOK) {
                resolve(fp.file.path);
            } else {
                resolve(null);
            }
        });
    });
}

/**
 * 获取笔记标题
 */
function getNoteTitle(noteItem) {
    const note = noteItem.getNote();
    const parser = new DOMParser();
    const doc = parser.parseFromString(note, "text/html");
    
    const h1 = doc.querySelector("h1, h2, h3");
    if (h1 && h1.textContent.trim()) {
        return sanitizeFilename(h1.textContent.trim());
    }
    
    const text = doc.body.textContent.trim();
    if (text) {
        return sanitizeFilename(text.substring(0, 50));
    }
    
    return "untitled_note";
}

/**
 * 清理文件名
 */
function sanitizeFilename(name) {
    return name
        .replace(/[<>:"/\\|?*]/g, "_")
        .replace(/\s+/g, " ")
        .trim()
        .substring(0, 100);
}

/**
 * 笔记转 Markdown
 */
async function noteToMarkdown(noteItem) {
    const api = Zotero.BetterNotes?.api;
    if (api && api.convert && api.convert.note2md) {
        let markdown = await api.convert.note2md(noteItem, Zotero.getTempDirectory().path, {
            keepNoteLink: true,
            withYAMLHeader: false,
        });
        
        markdown = await processMarkdownContent(markdown);
        return markdown;
    }
    
    return await processNoteHtml(noteItem);
}

/**
 * 处理 Markdown 内容（图片和链接）
 */
async function processMarkdownContent(markdown) {
    // 1. 递归移除 span 标签
    let prev = "";
    while (markdown !== prev) {
        prev = markdown;
        markdown = markdown.replace(/<span\s+[^>]*>([\s\S]*?)<\/span>/gi, "$1");
    }

    // 2. 处理链接
    markdown = markdown.replace(/<a\s+(?:[^>]*?\s+)?href=["'"](zotero:\/\/[^"'"]+)["'"][^>]*>([\s\S]*?)<\/a>/gi, (match, url, text) => {
        if (CONFIG.linkStyle === "text") {
            return text;
        }
        return `[${text}](${url})`;
    });

    // 3. 处理图片
    const replacements = [];
    const storagePath = Zotero.getStorageDirectory().path;

    // Markdown 图片语法
    const mdImgRegex = /!\[(.*?)\]\((attachments\/([^)]+))\)/g;
    let match;
    while ((match = mdImgRegex.exec(markdown)) !== null) {
        const fullMatch = match[0];
        const altText = match[1];
        const filename = match[3];
        
        let key = null;
        const keyMatch = altText.match(/data-attachment-key=["'"]([^"'"]+)["'"]/);
        if (keyMatch) {
            key = keyMatch[1];
        } else {
            key = filename.split('.')[0];
        }

        if (key) {
            replacements.push({ fullMatch, key, alt: "image" });
        }
    }

    // HTML img 标签
    const htmlImgRegex = /<img\s+[^>]*data-attachment-key=["'"]([^"'"]+)["'"][^>]*>/gi;
    while ((match = htmlImgRegex.exec(markdown)) !== null) {
        replacements.push({
            fullMatch: match[0],
            key: match[1],
            alt: "image"
        });
    }

    // 执行图片路径替换
    for (const rep of replacements) {
        let realPath = null;
        const itemDir = PathUtils.join(storagePath, rep.key);
        
        if (await IOUtils.exists(itemDir)) {
            const children = await IOUtils.getChildren(itemDir);
            for (const child of children) {
                if (child.toLowerCase().match(/\.(png|jpg|jpeg|gif|bmp|webp|svg)$/)) {
                    realPath = child;
                    break;
                }
            }
        }

        if (realPath) {
            realPath = realPath.replace(/\\/g, '/');
            const newImage = `![${rep.alt}](${realPath})`;
            markdown = markdown.replace(rep.fullMatch, newImage);
            Zotero.debug(`[Pandoc] 图片替换: ${rep.key} -> ${realPath}`);
        } else {
            Zotero.debug(`[Pandoc] 未找到图片: ${rep.key}`);
        }
    }

    return markdown;
}

/**
 * 处理笔记 HTML（回退方案）
 */
async function processNoteHtml(noteItem) {
    const note = noteItem.getNote();
    const parser = new DOMParser();
    const doc = parser.parseFromString(note, "text/html");
    
    const images = doc.querySelectorAll('img[data-attachment-key]');
    for (const img of images) {
        const key = img.getAttribute('data-attachment-key');
        if (key) {
            const storagePath = Zotero.getStorageDirectory().path;
            const exts = ['.png', '.jpg', '.jpeg', '.gif', '.webp'];
            
            for (const ext of exts) {
                const imagePath = PathUtils.join(storagePath, key, key + ext);
                if (await IOUtils.exists(imagePath)) {
                    img.setAttribute('src', imagePath);
                    break;
                }
            }
        }
    }
    
    return simpleHtmlToMarkdown(doc.body);
}

/**
 * 简单的 HTML 转 Markdown
 */
function simpleHtmlToMarkdown(element) {
    let result = "";
    
    function process(node, depth = 0) {
        if (node.nodeType === Node.TEXT_NODE) {
            return node.textContent;
        }
        
        if (node.nodeType !== Node.ELEMENT_NODE) {
            return "";
        }
        
        const tag = node.tagName.toLowerCase();
        let content = "";
        
        for (const child of node.childNodes) {
            content += process(child, depth + (tag === 'ul' || tag === 'ol' ? 1 : 0));
        }
        
        switch (tag) {
            case "h1": return `# ${content.trim()}\n\n`;
            case "h2": return `## ${content.trim()}\n\n`;
            case "h3": return `### ${content.trim()}\n\n`;
            case "p": return `${content.trim()}\n\n`;
            case "strong":
            case "b": return `**${content}**`;
            case "em":
            case "i": return `*${content}*`;
            case "code": return `\`${content}\``;
            case "a":
                const href = node.getAttribute("href") || "";
                const text = content.trim() || href;
                if (CONFIG.linkStyle === "text") return text;
                return `[${text}](${href})`;
            case "li":
                const indent = "  ".repeat(Math.max(0, depth - 1));
                return `${indent}- ${content.trim()}\n`;
            case "br": return "\n";
            default: return content;
        }
    }
    
    result = process(element);
    return result.replace(/\n{3,}/g, "\n\n");
}

/**
 * 运行 Pandoc
 */
async function runPandoc(inputPath, outputPath) {
    const tempDir = Zotero.getTempDirectory().path;
    const errorLogPath = PathUtils.join(tempDir, `pandoc_error_${Zotero.Utilities.randomString(6)}.log`);
    const batPath = PathUtils.join(tempDir, `pandoc_run_${Zotero.Utilities.randomString(6)}.bat`);
    
    // 构建命令
    let cmd = `"${CONFIG.pandocPath}" "${inputPath}" -o "${outputPath}" --wrap=none`;
    
    if (CONFIG.templatePath && await IOUtils.exists(CONFIG.templatePath)) {
        cmd += ` --reference-doc "${CONFIG.templatePath}"`;
    }
    
    cmd += ` 2>"${errorLogPath}"`;

    // 创建批处理文件
    const batContent = "@echo off\r\n" +
        "chcp 65001 > nul\r\n" +
        cmd + "\r\n" +
        "exit /b %errorlevel%\r\n";
    
    const encoder = new TextEncoder();
    await IOUtils.write(batPath, encoder.encode(batContent));
    
    Zotero.debug(`[Pandoc] 批处理: ${batPath}`);
    Zotero.debug(`[Pandoc] 命令: ${cmd}`);
    
    return new Promise(async (resolve, reject) => {
        try {
            const cmdFile = Components.classes["@mozilla.org/file/local;1"]
                .createInstance(Components.interfaces.nsIFile);
            cmdFile.initWithPath("C:\\Windows\\System32\\cmd.exe");
            
            const process = Components.classes["@mozilla.org/process/util;1"]
                .createInstance(Components.interfaces.nsIProcess);
            
            process.init(cmdFile);
            process.run(true, ["/c", batPath], 2);
            
            const exitValue = process.exitValue;
            Zotero.debug(`[Pandoc] 退出码: ${exitValue}`);
            
            // 读取错误日志
            let errorLog = "";
            try {
                if (await IOUtils.exists(errorLogPath)) {
                    const errorBytes = await IOUtils.read(errorLogPath);
                    const decoder = new TextDecoder("utf-8");
                    errorLog = decoder.decode(errorBytes);
                }
            } catch (e) {}
            
            // 清理临时文件
            try {
                await IOUtils.remove(batPath, { ignoreAbsent: true });
                await IOUtils.remove(errorLogPath, { ignoreAbsent: true });
            } catch (e) {}
            
            if (exitValue === 0) {
                const outputExists = await IOUtils.exists(outputPath);
                if (outputExists) {
                    resolve();
                } else {
                    reject(new Error(`Pandoc 执行完成但输出文件未生成\n${errorLog || ''}`));
                }
            } else if (exitValue === 9009) {
                reject(new Error(
                    "无法找到 Pandoc 可执行文件。\n\n" +
                    "安装方法：\n" +
                    "1. Winget: winget install Pandoc.Pandoc\n" +
                    "2. Chocolatey: choco install pandoc\n" +
                    "3. 官网: https://pandoc.org/installing.html\n\n" +
                    "安装后在脚本顶部配置路径。"
                ));
            } else {
                reject(new Error(`Pandoc 失败 (退出码: ${exitValue})\n\n${errorLog}`));
            }
        } catch (error) {
            try {
                await IOUtils.remove(batPath, { ignoreAbsent: true });
                await IOUtils.remove(errorLogPath, { ignoreAbsent: true });
            } catch (e) {}
            reject(error);
        }
    });
}

/**
 * 导出单个笔记（内部函数，不弹窗）
 */
async function exportNoteInternal(noteItem, outputPath) {
    const tempDir = Zotero.getTempDirectory().path;
    
    // 转换为 Markdown
    const markdown = await noteToMarkdown(noteItem);
    
    // 保存临时文件
    const mdPath = PathUtils.join(tempDir, `${Zotero.Utilities.randomString(8)}.md`);
    await Zotero.File.putContentsAsync(mdPath, markdown);
    
    // 调用 Pandoc
    await runPandoc(mdPath, outputPath);
    
    // 清理
    await IOUtils.remove(mdPath, { ignoreAbsent: true });
}

/**
 * 显示成功提示
 */
function showSuccess(path) {
    const result = window.confirm(
        `笔记已成功导出到:\n${path}\n\n点击"确定"打开文件夹`
    );
    
    if (result) {
        Zotero.File.reveal(path);
    }
}

// ============================================================================
// 主入口
// ============================================================================

async function main() {
    // 1. 查找 Pandoc
    try {
        CONFIG.pandocPath = await findPandoc();
    } catch (e) {
        window.alert(e.message);
        return;
    }

    // 2. 收集笔记
    const noteItems = [];
    for (const selectedItem of selectedItems) {
        if (selectedItem.itemType === "note") {
            noteItems.push(selectedItem);
        } else if (selectedItem.isRegularItem && selectedItem.isRegularItem()) {
            const notes = selectedItem.getNotes();
            for (const noteId of notes) {
                noteItems.push(Zotero.Items.get(noteId));
            }
        }
    }
    
    if (noteItems.length === 0) {
        window.alert("请先选择一个或多个笔记条目");
        return;
    }
    
    // 3. 导出
    if (noteItems.length === 1) {
        // 单个笔记
        const noteItem = noteItems[0];
        const title = getNoteTitle(noteItem);
        const outputPath = await pickSaveFile(`${title}.docx`);
        
        if (!outputPath) return;
        
        try {
            await exportNoteInternal(noteItem, outputPath);
            showSuccess(outputPath);
        } catch (error) {
            Zotero.logError(error);
            window.alert(`导出失败: ${error.message}`);
        }
    } else {
        // 批量导出
        const outputDir = await pickDirectory();
        if (!outputDir) return;
        
        const results = [];
        for (const noteItem of noteItems) {
            try {
                const title = getNoteTitle(noteItem);
                const outputPath = PathUtils.join(outputDir, `${title}.docx`);
                await exportNoteInternal(noteItem, outputPath);
                results.push({ success: true, path: outputPath });
            } catch (error) {
                results.push({ success: false, error: error.message });
            }
        }
        
        const successCount = results.filter(r => r.success).length;
        const failCount = results.length - successCount;
        
        if (successCount > 0) {
            const firstSuccess = results.find(r => r.success);
            const openFolder = window.confirm(
                `批量导出完成\n成功: ${successCount} 个\n失败: ${failCount} 个\n\n点击"确定"打开文件夹`
            );
            if (openFolder && firstSuccess) {
                Zotero.File.reveal(firstSuccess.path);
            }
        } else {
            window.alert(`导出失败，所有 ${failCount} 个笔记均失败`);
        }
    }
}

// 运行
main().catch(error => {
    Zotero.logError(error);
    window.alert(`导出失败: ${error.message}`);
});

Anything else

No response