시작

pandoc과 zotero.lua 설치

컴퓨터마다 한 번만 합니다. pandoc 설치, zotero.lua 넣기, 한 줄 확인의 세 단계이고, 확인 줄이 통과하면 Word 내보내기 준비가 끝납니다.

flowchart LR
  A["명령 창 열기"] --> B["1. pandoc 설치"]
  B --> C["창을 닫고 새로 열기"]
  C --> D["2. zotero.lua 넣기"]
  D --> E["3. 한 줄 확인"]
  E -->|통과| F["Word 내보내기"]
  E -->|오류| G["한 번에 점검과 증상표"]
  %% @key: E

#먼저 알아 둘 것

• pandoc은 Obsidian 플러그인이 아니라 컴퓨터에 설치하는 프로그램입니다. Obsidian의 pandoc 플러그인은 필요 없습니다.
• Lua는 따로 설치하지 않습니다. pandoc이 Lua 5.4를 품고 있습니다. brew install lua, Lua 설치 프로그램, LuaRocks 모두 필요 없습니다.
• 직접 받는 Lua 파일은 zotero.lua 하나입니다. 키트 폴더에 생기는 cmds-zotero-word.lua, cmds-zotero-docx.lua는 내보낼 때마다 플러그인이 씁니다. 옮기거나 따로 받지 않습니다. .lua 파일은 더블클릭해서 여는 파일이 아닙니다.
• 명령은 macOS는 터미널, Windows는 PowerShell에 붙여 넣습니다. 두 운영체제의 줄은 서로 다르고, 섞어 쓰면 실패합니다.
• 관리자 권한은 필요 없습니다. macOS의 .pkg 설치 파일이 Mac 암호를 묻는 것만 예외입니다.

#운영체제별 한눈에

PowerShell 7(pwsh)에서도 Windows 줄을 씁니다. Linux는 macOS 줄을 씁니다. 배포판 패키지의 pandoc은 오래된 경우가 많으니 pandoc 릴리스의 .deb나 압축 파일을 권합니다.

pandoc은 폴더 없이 이름만 적힌 필터(zotero.lua)를 지금 있는 폴더에서 먼저 찾고, 없으면 사용자 데이터 폴더의 filters 하위 폴더에서 찾습니다. 사용자 데이터 폴더는 pandoc --version의 User data directory 줄에 나옵니다. 아래 설치 줄은 모두 그 filters 폴더에 zotero.lua를 넣습니다.

#1. pandoc 설치

#macOS

Homebrew를 쓰고 있으면(brew --version에 버전이 나오면):

brew install pandoc

Homebrew가 없으면(zsh: command not found: brew) Homebrew를 새로 깔 필요 없이 설치 파일을 씁니다. 먼저 칩을 확인합니다.

uname -m

arm64이면 Apple 칩(M1, M2…), x86_64이면 Intel입니다. pandoc 릴리스에서 arm64는 pandoc-<버전>-arm64-macOS.pkg, x86_64는 pandoc-<버전>-x86_64-macOS.pkg를 받아 엽니다. 설치 중에 Mac 암호를 묻습니다.

#Windows

PowerShell에 붙여 넣습니다. 약관 동의를 미리 넣어 두었으니 묻지 않고 설치합니다.

winget install --id JohnMacFarlane.Pandoc -e --source winget --accept-package-agreements --accept-source-agreements

winget을 인식하지 못한다고 나오면(오래된 Windows 10, 일부 회사 PC) pandoc 릴리스에서 pandoc-<버전>-windows-x86_64.msi를 받아 열고 Next로 끝까지 갑니다. ARM(Snapdragon) 노트북도 이 파일을 씁니다.

#설치한 뒤

열려 있던 터미널(PowerShell) 창을 모두 닫고 새로 엽니다. 설치 전에 연 창은 새 pandoc을 찾지 못합니다. 새 창에서 확인합니다.

pandoc --version

pandoc이 여러 개 깔려 있으면 먼저 잡힌 것이 쓰입니다. macOS which -a pandoc, Windows where.exe pandoc으로 목록을 봅니다(같은 경로가 두 번 나오는 것은 괜찮습니다). 맨 위가 Anaconda 같은 다른 프로그램에 딸려 온 오래된 pandoc이면 막힐 때를 봅니다.

#2. zotero.lua 넣기

Better BibTeX가 배포하는 pandoc 필터를 필터 폴더에 내려받습니다. 브라우저로 받으면 글자로 열리거나 이름에 .txt가 붙으니 명령을 씁니다. 아무것도 출력하지 않고 다음 줄로 넘어가면 성공입니다. 같은 줄을 다시 실행하면 최신판으로 바뀝니다.

macOS, Linux (터미널):

mkdir -p ~/.local/share/pandoc/filters && curl -fsSL -o ~/.local/share/pandoc/filters/zotero.lua https://retorque.re/zotero-better-bibtex/exporting/zotero.lua

Windows (PowerShell). 내보내기 보고 창이 보여 주는 줄과 같습니다.

New-Item -ItemType Directory -Force "$env:APPDATA\pandoc\filters" | Out-Null; Invoke-WebRequest -Uri https://retorque.re/zotero-better-bibtex/exporting/zotero.lua -OutFile "$env:APPDATA\pandoc\filters\zotero.lua"

#위 줄이 안 될 때

Windows에서 Invoke-WebRequest가 빨간 오류를 낼 때(보안 채널, 연결, 프록시): Windows에 들어 있는 curl.exe로 받습니다. curl이 아니라 curl.exe라고 씁니다. Windows PowerShell 5.1에서 curl은 Invoke-WebRequest의 다른 이름입니다.

curl.exe -fsSL --create-dirs -o "$env:APPDATA\pandoc\filters\zotero.lua" https://retorque.re/zotero-better-bibtex/exporting/zotero.lua

macOS에서 mkdir: … Permission denied가 날 때: 예전에 관리자 권한으로 돌린 도구가 ~/.local을 다른 소유자로 만들어 둔 경우입니다. pandoc은 ~/.local/share/pandoc이 없으면 예전 위치 ~/.pandoc을 쓰므로 그곳에 넣습니다.

mkdir -p ~/.pandoc/filters && curl -fsSL -o ~/.pandoc/filters/zotero.lua https://retorque.re/zotero-better-bibtex/exporting/zotero.lua

내려받기 자체가 막힐 때(회사나 학교 보안망, curl: (60) SSL certificate problem, curl: (6) Could not resolve host): 브라우저로 받아 옮깁니다.

1. 브라우저로 https://retorque.re/zotero-better-bibtex/exporting/zotero.lua를 엽니다. 글자가 화면에 나옵니다.
2. ⌘S(Windows는 Ctrl+S)로 다운로드 폴더에 zotero.lua라는 이름으로 저장합니다. Safari는 형식을 페이지 소스로 고릅니다.
3. 이름이 zotero.lua.txt가 아닌지 봅니다. Windows는 탐색기 → 보기 → 표시 → 파일 확장명을 켜야 보입니다. .txt가 붙었으면 지웁니다.
4. 필터 폴더로 옮깁니다.

macOS:

mkdir -p ~/.local/share/pandoc/filters && mv ~/Downloads/zotero.lua ~/.local/share/pandoc/filters/

Windows:

New-Item -ItemType Directory -Force "$env:APPDATA\pandoc\filters" | Out-Null; Move-Item "$HOME\Downloads\zotero.lua" "$env:APPDATA\pandoc\filters\" -Force

필터 폴더를 눈으로 보려면 macOS는 Finder에서 ⇧⌘G → ~/.local/share/pandoc/filters, Windows는 Win+R → %APPDATA%\pandoc\filters → 확인입니다.

#3. 한 줄 확인

macOS와 Windows가 같은 줄입니다.

echo test | pandoc --lua-filter zotero.lua -t plain

통과하면 두 줄이 나옵니다. 5904ae6 자리는 필터 판마다 다른 영문·숫자 일곱 자입니다.

zotero-live-citations 5904ae6
test

#한 번에 점검

막히면 아래 줄을 붙여 넣고 출력 전체를 캡처해 질문과 함께 보냅니다. 읽기만 하고 아무것도 바꾸지 않습니다.

macOS (터미널):

echo "macOS $(sw_vers -productVersion) $(uname -m) $SHELL"; which -a pandoc; pandoc --version | sed -n '1p;/Scripting/p;/data directory/p'; ls ~/.local/share/pandoc/filters/zotero.lua ~/.pandoc/filters/zotero.lua 2>&1; echo test | pandoc --lua-filter zotero.lua -t plain

Windows (PowerShell):

"Windows $([Environment]::OSVersion.Version) PowerShell $($PSVersionTable.PSVersion) 코드페이지 $((Get-ItemProperty HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage).ACP)"; (Get-Command pandoc -All -ErrorAction SilentlyContinue).Source; pandoc --version | Select-String '^pandoc |Scripting|data directory'; Test-Path "$env:APPDATA\pandoc\filters\zotero.lua"; echo test | pandoc --lua-filter zotero.lua -t plain

읽는 법:

• macOS의 ls 줄은 두 경로 가운데 하나만 있으면 됩니다. 다른 하나의 No such file or directory는 괜찮습니다.
• Windows의 True는 zotero.lua가 제자리에 있다는 뜻입니다. False면 2를 다시 합니다.
• Windows의 코드페이지 949는 한국어 Windows입니다. 다른 숫자(예: 1252)이면 Windows 경로의 글자를 봅니다. 버전이 10.0.22000 이상이면 Windows 11입니다.

#Windows 경로의 글자

Windows의 pandoc은 Lua 필터 파일을 열 때 경로를 시스템 로캘(유니코드를 지원하지 않는 프로그램용 언어)의 문자 집합으로 바꿉니다. 그 문자 집합에 없는 글자가 경로에 있으면 필터를 열지 못합니다. macOS에는 이 문제가 없습니다.

경로가 쓰이는 곳은 두 군데입니다.

• zotero.lua의 자리: 사용자 이름이 들어간 C:\Users\<이름>\AppData\Roaming\pandoc\filters
• 키트 필터(cmds-zotero-word.lua, cmds-zotero-docx.lua)의 자리: 볼트 경로와 노트 제목이 들어간 …\CMDS Zotero exports\<노트> (Word)

고치는 법:

• 볼트 경로나 노트 제목이 원인이면: 키트를 볼트 밖에 씁니다. 설정 → CMDS Zotero → Bibliography and references에서 Allow export kits outside the vault를 켜고, Export kit folder에 ~/Documents/CMDS Zotero exports를 적은 뒤 Save configuration의 Save를 누릅니다. 원고의 이미지는 볼트에서 그대로 찾습니다(이모지가 든 볼트 경로로 확인). 노트 제목의 이모지나 악센트 글자는 키트 폴더 이름에 그대로 들어가니 제목에서 뺍니다.
• 시스템 로캘이 한국어가 아니면: 설정 → 시간 및 언어 → 언어 및 지역 → 관리 언어 설정 → 시스템 로캘 변경 → 한국어(대한민국) → 다시 시작.
• 사용자 이름 자체에 이모지나 악센트 글자가 있으면 위 두 가지로 풀리지 않습니다. 문제 신고로 알려 주세요.

#막힐 때

Word 쪽 증상(@키: not found, <Do Zotero Refresh: …> 등)은 문제 해결에 있습니다.

#확인한 환경

2026-10-29, Better BibTeX zotero.lua 판 5904ae6으로 확인했습니다.

PowerShell 7, Windows 10, 영문 로캘 Windows, Intel Mac, .pkg와 .msi 설치는 직접 확인하지 않았습니다. 영문 로캘에서 한글 경로가 실패하는 것은 위와 같은 원리(필터 경로를 시스템 코드 페이지로 바꿈)에서 나온 결론입니다.