CMDSPACE Obsidian Plugins
← 플러그인공개 릴리스 0.6.7

CMDS Zotero / 읽은 것을 노트로 가져오다

Zotero에서 읽은 것을
노트로 가져온다.

Zotero 리더로 읽고 표시한 논문을 문헌 노트로 보냅니다. 메타데이터, 하이라이트와 메모, Zotero 노트, 인용과 원문 링크를 모으고 내가 쓴 글은 그대로 둡니다.

사용설명서 ↓GitHub 소스 ↗

시작 전 준비

Obsidian 데스크톱 1.7.2+ / Zotero + Better BibTeX / 커뮤니티 플러그인에서 설치

먼저 알아둘 것

Zotero는 읽기 전용이며 최근 읽은 논문 목록은 Zotero가 실행 중일 때 보입니다.

문서 기준 2026-10-29소스 버전 0.6.7Markdown ↙

CMDS Zotero 사용설명서

Zotero에서 읽고 표시한 내용을 Obsidian 문헌 노트로 보냅니다. 메타데이터, 하이라이트와 메모, Zotero 노트, 인용과 원문 링크를 한 노트에 모으고, 사람이 쓴 글은 그대로 둡니다. Zotero는 읽기 전용으로 다룹니다.

버전과 공개 상태

2026-10-29에 공개한 CMDS Zotero 0.6.7 기준입니다. GitHub 릴리스에는 CI가 빌드하고 출처를 증명한 main.js, manifest.json, styles.css가 있습니다. 설정 → 커뮤니티 플러그인 → 탐색에서 설치하거나, 수동 설치나 BRAT로 설치합니다. 0.6.5는 새로 설치한 경우 인덱스를 번호 붙은 80. References 폴더 대신 문헌 노트 옆 References/Zotero/zotero-index.json에 만듭니다. 그 자리에 인덱스가 이미 있는 설치는 그대로 씁니다. 0.6.4는 커뮤니티 디렉터리 등록을 준비했습니다. Obsidian 1.13 이상에서도 설치된 스타일을 고르면 설정 칸이 바로 바뀌고, 현재 노트용 명령은 노트가 열려 있을 때만 나타납니다. 0.6.3은 옮긴 문헌 노트를 찾아내고, 새 노트 이름을 고정 토큰으로 정하고, 검색으로 일괄 가져오고, 모든 일괄 작업 전에 검토 목록을 보여 주고, 다른 Zotero 플러그인이 만든 노트를 넘겨받고(adopt), 노트별 갱신·재생성·frontmatter 새로 고침·옛 키 정리·병합 항목 재연결을 추가합니다. 같은 날 공개한 0.6.2는 인용 편집기, Zotero에 설치된 스타일과 로캘로 만드는 참고문헌, 인용 점검(Check citations), 참고문헌 구역, pandoc 내보내기 키트를 추가했습니다. 0.6.1은 노트 레이아웃 설정, 항목 내용 삽입, 더 풍부한 주석 사이드바, 필드 검색, Zotero 선택 항목 명령, 설정 진단을 추가했습니다. 0.6.0은 인덱스 갱신·시작·일괄 갱신을 빠르게 하고, 문제 있는 항목이 있어도 갱신을 이어 가며, 인용 선택기가 기다리게 하고, 설정 탭을 다시 정리하고, 에이전트 액션을 추가했습니다. 모든 변경은 변경 기록에 있습니다. 검증 환경은 Obsidian 1.14.4, Zotero 10.0.6, Better BibTeX 9.0.71, macOS입니다. 0.5 때 실제 서재로 최근 읽은 논문 목록, 문헌 노트 생성·갱신 4건, PDF 텍스트 추출 4건(스캔본 1건 포함), 인용문 위치 찾기를 확인했습니다. 그룹 라이브러리와 Windows/Linux는 실사용 검증 범위가 아닙니다. 0.6.1에서 올리면 기본 설정에서 네 가지가 달라 보입니다. 편집기에서 citekey 문제에 밑줄이 그어지고, 복사한 참고문헌은 스타일 자체의 순서를 따르고, Update all owned literature notes는 먼저 검토 목록을 보여 주고, 출력 폴더 밖으로 옮긴 문헌 노트는 옮긴 자리에서 갱신됩니다. 새 노트의 이름과 폴더는 0.6.1과 같습니다.

준비물과 용어

  • Obsidian 데스크톱 1.7.2 이상. 모바일은 지원하지 않습니다.
  • 실행 중인 Zotero와 Better BibTeX(BBT). 플러그인은 BBT의 로컬 JSON-RPC만 사용합니다.
  • 최근 읽은 논문 기능은 Zotero가 PDF를 리더로 열 때 남기는 읽기 기록을 씁니다. Zotero 10에서 확인했습니다.
  • 기본 로컬 주소 http://127.0.0.1:23119/better-bibtex. Zotero Web API 키, native Local API 설정 변경, SQLite 접근, 별도 PDF 도구는 필요 없습니다. citekey는 Example2026 같은 인용 라벨이며 영구 식별자가 아닙니다. 플러그인은 라이브러리 종류, 로컬 library ID, Zotero item key로 항목을 식별합니다. 첨부와 주석은 별도 키를 가지며 부모 항목이 곧 PDF는 아닙니다.

설치

커뮤니티 플러그인: 설정 → 커뮤니티 플러그인 → 탐색에서 CMDS Zotero를 검색해 설치한 뒤 활성화합니다.

수동 설치

  1. 최신 릴리스에서 main.js, manifest.json, styles.css를 받습니다.
  2. <vault>/.obsidian/plugins/cmds-zotero/ 폴더에 세 파일을 넣습니다.
  3. Obsidian을 다시 로드하고 설정 → 커뮤니티 플러그인에서 CMDS Zotero를 켭니다.

BRAT 설치: BRAT 플러그인에서 johnfkoo951/cmds-zotero를 베타 플러그인으로 추가합니다.

이전 버전에서 올리면 설정(data.json)과 인덱스는 그대로 쓰입니다. 업그레이드 전에 플러그인 폴더를 백업합니다. 옛 플러그인 cmds-link-zotero가 같은 인덱스 경로를 쓰고 있다면 꺼 두어야 인덱스를 갱신할 수 있습니다.

첫 성공: 최근 읽은 논문을 노트로 보내기

  1. Better BibTeX가 켜진 Zotero를 실행합니다.
  2. 설정 → CMDS Zotero에서 Output folder, Image folder, Index path를 볼트 상대경로로 정하고 Save configuration을 누릅니다. Test connection은 저장된 설정을 시험합니다.
  3. 명령 팔레트(Ctrl/Cmd+P)에서 Refresh citekey index를 한 번 실행합니다.
  4. Zotero 리더에서 논문 PDF를 열고 하이라이트나 메모를 남깁니다.
  5. Send recently read papers to notes를 실행하거나 펼친 책 모양 리본 아이콘을 누릅니다.
  6. 목록에서 논문마다 노트 상태를 확인합니다: No literature note yet(노트 없음), N new annotations not in the note(새 주석 N개), Note is up to date(최신), CMDS Zotero가 만들지 않은 노트(덮어쓰지 않음).
  7. 보낼 필요가 있는 논문은 미리 선택되어 있습니다. Send를 누르면 노트를 새로 만들거나 관리 구역만 갱신합니다.
  8. 행의 노트 버튼으로 결과를 열고 주석, 페이지 링크, 메타데이터를 Zotero와 비교합니다.
  9. 노트의 ## Synthesis나 ## Notes에 문장을 쓰고 Zotero에서 하이라이트를 하나 더 한 뒤 다시 보냅니다. 내가 쓴 문장은 그대로 있고 새 주석만 추가되면 첫 성공입니다.

Reading window는 7/30/90/365일 중에서 고릅니다. 기본값은 설정의 Recently read window(30일)입니다. 목록을 보려면 Zotero가 실행 중이어야 합니다.

문헌 노트 가져오기와 갱신

Import literature note는 자료를 골라 미리보기(경로, 구역별 상태, 충돌)를 연 뒤 적용합니다. 자료 선택 창은 최근 읽은 논문을 맨 위에 · read 3 days ago처럼 표시합니다. Open or import literature note는 자료의 노트를 열고, 볼트에 아직 노트가 없으면 가져오기 미리보기를 엽니다. 가져오기는 저장된 인덱스가 아니라 Zotero의 현재 데이터(그 항목의 export와 첨부·주석)로 노트를 렌더링합니다. 그래서 인덱스를 갱신하지 않아도 방금 단 하이라이트가 들어갑니다. citekey가 Zotero에서 바뀌었으면 item key로 다시 찾고, 다른 항목으로 대체하지 않습니다. Zotero가 꺼져 있으면 저장된 인덱스로 미리보기하고 그 사실을 알립니다. 처음 만드는 노트는 참고문헌 문장이 필요하므로 Zotero가 실행 중이어야 합니다.

새 노트의 위치. New note file name과 New note subfolder(설정 → Literature notes)는 고정 토큰 {citekey}, {title}, {shortTitle}, {year}, {firstAuthor}, {itemType}, {collection}으로 만듭니다. 예를 들어 하위 폴더 {itemType} 아래 {year} {shortTitle}처럼 정할 수 있습니다. 파일 이름에 쓸 수 없는 문자는 바꾸고 긴 이름은 줄이며, 미리보기가 결과 경로를 보여 줍니다. 기본값(@{citekey}, 하위 폴더 없음)은 이전과 같은 이름을 만들고, 기존 노트의 이름은 그대로 둡니다. 템플릿 언어가 아니라 고정된 토큰입니다.

옮긴 노트. 볼트 안 어디로 옮기거나 이름을 바꾼 문헌 노트도 식별 정보(zoteroID와 플러그인의 소유 표식)로 찾아, 다시 가져오지 않고 그 자리에서 갱신합니다. 소유 표식 없이 항목 이름만 담은 노트는 문헌 노트로 보지 않습니다. Diagnose setup은 출력 폴더 밖에 있는 문헌 노트를 보여 줍니다.

노트 하나 갱신. Update current literature note는 열린 노트의 갱신 미리보기를 엽니다. 이미 있는 노트라면 미리보기에 Refresh 묶음이 있습니다. Title and abstract, Bibliography entry, Metadata and links, Zotero notes, Annotations 중 끈 구역은 이번 갱신에서 그대로 둡니다.

검토 목록이 있는 일괄 작업. Update all owned literature notes, Update literature notes changed in Zotero, Import literature notes by search, Adopt existing literature notes는 먼저 검토 목록을 보여 줍니다. 노트마다 무엇을 할지(Create, Update, Adopt, 또는 이유가 붙은 Skip)와 선택 상자가 있고, Select all과 Select none으로 한꺼번에 고를 수 있습니다. 적용 버튼을 누르기 전에는 Zotero에서 아무것도 읽지 않고 아무것도 쓰지 않으며, Cancel은 아무것도 바꾸지 않습니다. 실행 중에는 진행 알림에 Cancel이 있고, 취소하면 남은 노트는 그대로 둡니다.

  • Update all owned literature notes는 선택한 노트의 관리 구역을 갱신하고 Updated, Partial(편집 구역 보존), Unchanged, Skipped로 보고합니다. 같은 식별을 가진 노트가 여럿이면 건너뛰고, 항목을 가리키지만 CMDS Zotero가 만들지 않은 노트는 넘겨받기(adopt)를 안내하며 건너뜁니다.
  • Update literature notes changed in Zotero는 노트를 마지막으로 쓴 뒤 항목이나 주석이 바뀐 노트만 같은 목록으로 보여 줍니다. Changed in Zotero since에서 Any time이나 날짜로 바꿀 수 있습니다. 날짜는 저장된 인덱스에서 오므로 먼저 인덱스를 갱신합니다. 날짜를 알 수 없는 노트를 바뀌지 않았다고 보지는 않습니다.
  • Import literature notes by search는 col:methods, tag:method, type:book, year:2020- 같은 필드 검색을 받아, 맞는 항목 중 아직 노트가 없는 것만 새로 만듭니다. 두 항목의 파일 이름이 같아지면 두 번째 항목은 첫 노트를 덮어쓰지 않고 건너뜁니다.
  • Zotero 애드온 Better Notes가 동기화하는 노트는 Better Notes가 갱신 내용을 덮어쓰므로 일괄 작업에서 건너뛰고, 하나씩 갱신할 때는 경고를 보여 줍니다.

다른 플러그인의 노트 넘겨받기. Adopt current note as literature note는 Zotero Integration이나 ZotLit이 만든 노트, 또는 citekey를 이름으로 쓰는 노트를 citekey, DOI, Zotero 링크로 항목과 맞춥니다(여러 항목이 맞으면 직접 고릅니다). 미리보기와 백업 뒤 빠진 식별 키를 한 줄씩 더하고 생성 구역을 내 글 아래에 덧붙이며, 내가 쓴 내용은 바꾸지 않습니다. Adopt existing literature notes는 검토 목록을 거쳐 볼트에서 맞는 모든 노트에 같은 일을 합니다. DOI로만 맞은 노트는 선택이 해제된 채로 나옵니다. type이 paper-hub, paper-analysis, raw-source인 노트, 10. Raw Sources 아래 노트, Bookends나 Better Notes의 노트, 이미 CMDS Zotero가 소유한 노트는 거절합니다.

노트 복구. Rebuild current literature note는 노트를 백업한 뒤 생성 구역을 다시 렌더링하고, 손상·중복·누락된 마커를 고칩니다. 내가 쓴 줄은 모두 남고, 편집했거나 분리(detach)한 중복 블록도 내용이 그대로 남습니다.

Frontmatter와 식별. 다음 명령은 열린 노트에 작동합니다. 모두 줄 단위 미리보기를 보여 주고(-와 +로 표시한 줄만 바뀝니다), 먼저 노트를 백업 폴더에 복사하며, 쓰기 전·중·후에 노트가 바뀌지 않았는지 확인합니다.

  • Refresh frontmatter of current note from Zotero는 노트에 이미 있는 플러그인 메타데이터 키만 갱신합니다. zoteroID와 tags는 건드리지 않고 키를 새로 더하지 않습니다.
  • Remove legacy keys from current note는 0.3과 0.4가 쓰던 키를 지웁니다. Report notes with legacy Zotero keys는 그런 키가 남은 노트를 아무것도 바꾸지 않고 보여 줍니다.
  • Relink current note to merged Zotero item: Zotero에서 노트의 항목이 다른 항목으로 병합되었을 때, 노트를 남은 항목에 다시 연결합니다. 인덱스가 완전할 때만 작동하며, 후보가 여럿이면 직접 고릅니다.

노트 구조와 보존 규칙

새 노트의 frontmatter에는 type: zotero, zoteroID, zoteroSelectURI, zotero-key, citekey, doi, title, authors, year, tags와 zotero_title 같은 zotero_* 필드가 들어갑니다. frontmatter는 처음 한 번만 만들고 이후에는 사용자 소유입니다. 갱신은 frontmatter를 바꾸지 않으며, 위의 frontmatter 명령만 미리보기를 거쳐 바꿉니다. 본문은 다음 순서입니다.

  • 제목과 초록(overview), 참고문헌(citation)
  • ## Synthesis: 사용자 영역(**Contribution**::, **Related**::)
  • 메타데이터와 링크(metadata): 저자, 학술지, DOI, URL, 태그, 컬렉션, Zotero 관련 항목, Zotero와 PDF 열기 링크
  • ## Zotero notes(notes): Zotero 자식 노트를 제목·목록·링크를 살린 Markdown으로 넣습니다. 코드 블록은 그대로 둡니다.
  • ## Notes: 사용자 영역
  • ## Annotations: 주석마다 블록 하나. Zotero의 읽기 순서대로 놓이고, 나중에 앞쪽 페이지에 단 주석도 제자리에 들어갑니다. 하이라이트, 밑줄, 이미지, 메모, 손그림(ink)을 구분하며 페이지 링크는 Zotero 리더의 해당 위치를 엽니다.

관리 구역은 <!-- cmds-zotero:<id>:<해시> -->와 <!-- /cmds-zotero:<id> --> 사이입니다. 관리 구역을 고치면 그 구역만 **편집됨(보존)**으로 남고 나머지는 갱신됩니다. 미리보기에서 구역마다 다음 중 하나를 고릅니다.

  • Keep this time: 이번에는 그대로 둡니다.
  • Detach: 그 블록을 영구히 내 것으로 만듭니다. 다시 렌더링하지 않습니다.
  • Reset from Zotero: Zotero 내용으로 되돌립니다. 이전 노트는 .cmds-zotero/backups/notes/에 백업합니다. 마커가 손상되었거나, 중복되었거나, CMDS Zotero가 만들지 않은 노트이거나, 같은 식별을 가진 노트가 여럿이면 쓰지 않고 이유와 줄 번호를 보여 줍니다. 손상된 마커는 Rebuild current literature note로 고칠 수 있습니다. Zotero에서 지운 주석의 블록은 노트에서 지우지 않습니다.

인용, 참고문헌, 사이드바

인용 넣기

  • Insert citation from Zotero: BBT의 Cite As You Write 선택기로 인용을 넣습니다. 기본 형식은 [@citekey]입니다. 선택기가 열려 있는 동안 취소 버튼이 있는 알림이 뜨고, Picker wait(10분)까지 기다립니다. 그사이 다른 노트로 옮기면 인용을 노트 대신 클립보드에 넣습니다.
  • 편집기에서 [@ 뒤에 citekey·제목·저자·연도 일부를 입력하면 로컬 자동완성이 나옵니다. 캐시된 인덱스를 읽으므로 키 입력마다 Zotero를 부르지 않습니다. 한글은 조합형·분리형 어느 쪽으로 입력해도 찾고, 악센트는 무시합니다(é는 e와 맞음). Enter는 인용을, Shift+Enter는 서술형 @key를, Mod+Enter는 문헌 노트 링크를 넣습니다.
  • 새 인용은 커서의 인용에 합쳐집니다. [@kim2020] 바로 뒤에서 [@를 입력하거나 Zotero 선택기, Zotero 선택 항목, 자료 선택 창으로 인용하면 키를 반복하지 않고 [@kim2020; @lee2021]이 됩니다.
  • pandoc의 접두어, 위치(locator), 접미어를 이해합니다(예: [see @kim2020, pp. 33–35; also -@lee2021, ch. 1]). Edit citation locator는 커서에 있는 인용의 위치를 고칩니다.
  • 한국어 문장에서는 @key 바로 뒤에 조사를 붙이지 않습니다(조사까지 citekey로 읽힘). @key 는처럼 띄우거나 대괄호 뒤에 붙입니다. "구요한 외(2005)"처럼 한국어 저자를 쓰려면 이름을 직접 쓰고 연도만 인용합니다: 구요한 외[-@key]는. 스타일은 "외"를 만들지 않습니다. 각주식 스타일에서는 [@key]만 씁니다. 실제로 그린 예시는 웹 설명서의 인용 쓰기에 있습니다.
  • Insert citation from the literature index는 인덱스에서 자료를 골라 Default citation format 형식으로 넣습니다. 형식마다 명령도 따로 있습니다: Insert pandoc citation([@key]), Insert narrative citation(@key), Insert citekey wikilink([[@key]]), Insert author-date citation text((Kim & Lee, 2020), 인덱스로 만든 근사치), Insert Zotero item link, Insert literature note link. 템플릿이 아니라 고정된 형식입니다.
  • 자료 선택 창과 자동완성은 필드를 이해합니다: author:, title:, year:2019-2021, tag:, col:<컬렉션 경로>, lib:, type:, has:pdf|note|annotations(앞에 -를 붙이면 제외, 공백이 있는 값은 따옴표).
  • Insert item content from Zotero는 자료의 Zotero 노트·참고문헌·메타데이터·초록·링크·주석을 사용자 소유 텍스트로 현재 노트에 넣습니다.
  • Paste Zotero links as citations(기본 끔): Zotero 항목 링크(zotero://select/…)를 붙여 넣거나 끌어 놓으면 라이브러리와 item key로 맞춰 기본 형식의 인용을 넣습니다. 인덱스가 모르는 링크는 그대로 붙여 넣습니다.

편집기 안의 인용

  • 인덱스에 없거나, 여러 항목이 함께 쓰거나, 예전 키인 citekey에는 밑줄을 긋습니다(Mark citekey problems, 기본 켬). 인덱스를 불러오기 전에는 표시하지 않고, 불완전한 인덱스로는 키를 '없음'으로 표시하지 않습니다.
  • Citation hover preview는 제목·저자·연도·참고문헌 카드를 보여 주고, Show citations as author-date는 읽기 보기와 실시간 미리보기에서 [@kim2020, p. 3]을 "(Kim & Lee, 2020, p. 3)"처럼 보여 줍니다. 둘 다 기본으로 꺼져 있고 노트 텍스트는 바꾸지 않습니다.
  • Mod+click on a citation으로 인용을 Mod+클릭했을 때 문헌 노트나 위치 쪽의 PDF를 열게 할 수 있습니다(기본 끔). 오른쪽 클릭 메뉴는 커서가 아니라 클릭한 인용에 작동합니다.
  • Citation actions at cursor는 커서에 있는 인용으로 할 수 있는 동작을 모아 보여 줍니다. 같은 동작이 각각 명령으로도 있습니다: Open literature note for citation at cursor(노트가 없으면 가져오기 미리보기 제안), Open PDF at citation locator(인덱스가 쪽 라벨을 알면 위치의 쪽 라벨을 Zotero의 쪽 라벨과 맞추고, 알림으로 어떻게 쪽을 찾았는지 알려 줌), Copy PDF page link for citation at cursor, 그리고 이 노트 본문에서 예전 키로 된 인용을 모두 미리 보여 주고 실행 취소 한 번으로 되돌릴 수 있게 바꾸는 Fix renamed citekey in this note.
  • 여러 항목이 함께 쓰는 citekey는 실패하지 않고 어느 항목인지 묻습니다.

참고문헌과 참고 목록

  • Bibliography style: Choose style(설정 → Bibliography and references)과 명령 Choose bibliography style from installed styles는 Zotero의 styles 폴더에 있는 스타일을 읽기 전용으로 보여 줍니다(~/Zotero가 아니면 Zotero data directory를 정합니다). Better BibTeX가 렌더링하지 못하는 스타일은 이유와 함께 거절합니다. 직접 입력한 스타일이나 로캘도 Save configuration을 누를 때 같은 방식으로 확인합니다.
  • Bibliography locale은 참고문헌 용어와 날짜의 언어·지역을 정합니다(예: ko-KR, de-DE). 비워 두면 스타일의 기본값을 씁니다.
  • 노트의 csl과 lang frontmatter는 그 노트의 스타일과 로캘을 정합니다. 참고문헌 사이드바, Insert bibliography, 복사한 참고문헌, 참고문헌 구역, 내보내기 키트에 적용됩니다. csl: apa.csl은 파일 이름으로 설치된 스타일과 맞춥니다. lang은 원고가 아니라 참고문헌 용어의 언어입니다. 한국어 원고라도 영어 문헌을 영어 양식으로 적으면 en-US를 씁니다. ko-KR은 영어 양식 안의 용어만 바꿔("Eds."는 "편집자", "et al."은 "기타") 둘이 섞입니다. csl과 lang의 세 가지 예는 웹 설명서의 참고문헌과 Word에 있습니다.
  • Open references sidebar: 현재 노트의 [@key], @key, 인용 위키링크를 모아 참고문헌과 미해결 상태를 보여 줍니다. Zotero가 꺼져 있어도 저장된 참고문헌(.cmds-zotero/bibliography.json)으로 표시합니다. 인용은 pandoc과 같은 방식으로 셉니다. 코드, HTML 주석, %% 주석 안의 인용, 이스케이프한 \@, 이메일 주소는 빼고, -@key와 nocite의 키는 셉니다. 행마다 이전·다음 위치로 이동할 수 있고, 편집기에서는 Go to next occurrence of the citation at cursor와 Go to previous occurrence of the citation at cursor로 같은 일을 합니다.
  • Check citations in current note는 인덱스에 없는 키, 여러 항목이 쓰는 키, 예전 키, 문헌 노트가 없는 키, nocite 키를 저장된 인덱스로 보여 줍니다. 각 위치를 노트에서 열 수 있습니다.
  • Copy bibliography for current note(참고문헌 사이드바의 버튼도 같음)는 서식 있는 HTML과 일반 텍스트를 함께 클립보드에 넣으므로 워드프로세서에 서식째 붙습니다. 순서는 Bibliography order로 정합니다: 스타일이 정한 순서(기본), 처음 인용한 순서, 가나다·알파벳순.
  • Insert or update references section은 미리보기를 거쳐 노트 끝에 플러그인 소유 블록을 씁니다. 처음 넣기 전에 노트를 백업합니다. 편집하지 않은 블록은 그 자리에서 갱신하고, 편집한 블록은 그대로 두며, 여는 마커를 <!-- cmds-zotero-references:detached -->로 바꾸면 영구히 내 것이 됩니다.
  • Insert bibliography: 자료 하나의 CSL 참고문헌을 편집기에 넣습니다.
  • Open annotations sidebar: 현재 문헌 노트, Zotero에서 선택한 항목, 커서의 citekey, 고정한 자료의 주석을 보여 줍니다. 색·유형·태그·첨부로 거르고 정렬·묶기, Zotero에서 최신 주석 가져오기, 카드를 노트로 끌어 넣기, 카드의 More actions 메뉴를 쓸 수 있습니다. Search annotations는 색인된 모든 주석을 검색해 콜아웃이나 인용문으로 넣습니다.

pandoc으로 내보내기

  • Export pandoc kit for current note는 Export kit folder(기본 CMDS Zotero exports) 안에 노트마다 하위 폴더를 만들어 씁니다. 정리한 노트 사본(문헌 링크는 [@key]로, 콜아웃은 인용 블록으로 바꾸고 주석과 마커는 지움), 인용한 자료의 CSL-JSON, pandoc defaults 파일, .docx에 로컬 경로가 남지 않게 하는 작은 필터가 들어가고(사본의 프론트매터는 문서에 필요한 항목만 남김), pandoc 명령줄은 클립보드에 복사합니다. 원래 노트는 바꾸지 않고, 플러그인이 pandoc을 실행하지도 않습니다. 내가 고친 이전 키트는 덮어쓰지 않고 새 폴더를 제안합니다.
  • Export Word kit with live Zotero citations for current note(0.6.6)는 같은 폴더에 <노트> (Word)를 만들어 정리한 사본, defaults 파일, 작은 필터를 씁니다. 복사된 명령을 Zotero를 켠 채 실행하면 .docx의 인용이 Zotero 필드로 들어갑니다. Word의 Zotero 탭에서 Refresh를 한 번 누르면 그다음부터 인용 추가, 갱신, 스타일 변경을 Word에서 합니다. 노트의 스타일은 Zotero에 설치돼 있어야 하고, Better BibTeX의 zotero.lua가 pandoc 필터 폴더에 있어야 합니다(없으면 보고 창에 설치 명령이 나옵니다). 자세한 내용은 pandoc-docx.md §0b.
  • Copy CSL-JSON for cited sources와 Write pandoc bibliography sidecar for current note: 현재 노트가 인용한 자료를 CSL-JSON으로 복사하거나 .cmds-zotero/bibliography/<노트>.json에 저장하고, frontmatter에 넣을 bibliography: 줄을 알려 줍니다.
  • 키트와 내보내기 과정은 pandoc/DOCX 가이드에 단계별로 있습니다.

전체 명령어

명령 기능
Send recently read papers to notes Zotero에서 최근 읽은 논문과 노트 상태를 보고 노트로 보냄
Import literature note 자료 하나를 미리보기 뒤 가져오기·갱신
Open or import literature note 자료의 노트를 열거나, 없으면 가져오기 미리보기
Update current literature note 열린 노트의 갱신 미리보기, 갱신할 구역 선택 가능
Update all owned literature notes 검토 목록 뒤 플러그인이 만든 노트의 관리 구역 일괄 갱신
Update literature notes changed in Zotero Update all과 같되 항목이나 주석이 바뀐 노트만
Import literature notes by search 검토 목록 뒤 필드 검색에 맞는 항목의 노트 생성
Adopt current note as literature note 다른 Zotero 플러그인의 노트를 내 글은 그대로 둔 채 CMDS Zotero 노트로 넘겨받기
Adopt existing literature notes 검토 목록 뒤 볼트에서 맞는 노트를 모두 넘겨받기
Rebuild current literature note 백업 뒤 생성 구역 재렌더링과 마커 복구
Refresh frontmatter of current note from Zotero 미리보기 뒤 노트에 있는 플러그인 메타데이터 키 갱신
Remove legacy keys from current note 미리보기 뒤 0.3·0.4가 쓰던 키 삭제
Report notes with legacy Zotero keys 옛 키가 남은 노트 목록; 아무것도 바꾸지 않음
Relink current note to merged Zotero item Zotero가 병합한 항목으로 노트 다시 연결
Refresh citekey index BBT에서 인덱스 전체 갱신
Search literature 자료를 고르고 동작(열기, 가져오기, 링크 복사 등) 선택
Insert citation from Zotero Zotero 선택기로 인용 삽입, 취소 가능
Insert citation from the literature index 인덱스에서 골라 기본 형식으로 인용 삽입
Insert pandoc citation, Insert narrative citation, Insert citekey wikilink, Insert author-date citation text, Insert Zotero item link, Insert literature note link 해당 형식으로 인용 삽입
Citation actions at cursor 커서 인용에 대한 동작 목록
Edit citation locator 커서 인용의 위치(locator) 수정
Open literature note for citation at cursor 인용한 자료의 노트나 가져오기 미리보기 열기
Open PDF at citation locator 위치의 쪽으로 PDF 열기
Copy PDF page link for citation at cursor 그 PDF 쪽 링크 복사
Fix renamed citekey in this note 미리보기 뒤 이 노트의 예전 citekey 바꾸기
Go to next / previous occurrence of the citation at cursor 같은 인용의 위치 사이 이동
Check citations in current note 없는·모호한·예전·노트 없는 키 목록
Insert bibliography 자료 하나의 참고문헌 삽입
Copy bibliography for current note 인용한 자료의 참고문헌을 서식·일반 텍스트로 복사
Insert or update references section 노트 끝의 관리형 참고문헌 블록 작성·갱신
Choose bibliography style from installed styles Zotero styles 폴더에서 스타일을 골라 BBT로 확인
Export pandoc kit for current note 내보내기용 정리 사본·CSL-JSON·pandoc defaults 작성
Export Word kit with live Zotero citations for current note Word에서 Zotero 필드로 이어 쓰는 .docx용 정리 사본·pandoc defaults 작성
Copy CSL-JSON for cited sources 현재 노트 인용의 CSL-JSON 복사
Write pandoc bibliography sidecar for current note pandoc용 참고문헌 파일 저장
Open references sidebar 현재 노트 인용 검토
Open annotations sidebar 주석 검토와 삽입
Open source PDF at page PDF를 파일 위치 기준 쪽으로 열기
Open link under cursor 커서의 Zotero 링크나 [@citekey] 열기
Find notes citing a source 현재·과거 citekey를 쓴 노트 찾기
Find literature across vaults 허용한 다른 볼트의 같은 자료 노트 찾기
Copy Zotero item link (Hookmark-compatible) Zotero 항목 Markdown 링크 복사
Copy literature note identity link (rename-safe) 노트 이름이 바뀌어도 열리는 링크 복사
Copy Obsidian file link (Hookmark-native) 문헌 노트의 obsidian://open 주소 복사
Diagnose index and links 연결, 인덱스, 식별 진단
Diagnose setup 보고 전용 설정 점검과 복사 가능한 보고서
Insert item content from Zotero 자료의 Zotero 노트·인용·메타데이터·초록·링크·주석을 현재 노트에 삽입(사용자 소유 텍스트)
Search annotations 색인된 모든 주석을 검색해 콜아웃이나 인용문으로 삽입
Open / Import / Cite Zotero selection 명령을 실행할 때 Zotero에서 선택한 항목을 읽어 열기·가져오기·인용
Copy Zotero action script Zotero 메뉴에서 노트를 여는 Actions & Tags 스크립트 복사(설정)
Annotations sidebar: … 주석 사이드바의 따라가기 모드·고정·해제·최신 가져오기

PDF 쪽 번호는 1부터 시작하는 파일 위치이지 인쇄된 쪽 번호가 아닙니다.

설정

설정은 영역별 구역으로 나뉘며, 요청 한도와 에이전트 전용 References headings는 Advanced 아래에 있습니다. 입력하는 동안 값을 검사합니다. 스위치와 선택 상자는 바꾸는 즉시 저장됩니다(0.6.7). 글자로 입력한 값은 Save configuration을 눌러야 저장되고, 그 전에는 이전 값이 쓰입니다.

구역 설정 기본값과 의미
Connection Server endpoint http://127.0.0.1:23119/better-bibtex; localhost 주소만 허용
Connection Test connection 저장된 주소로 BBT 연결 시험
Literature index Index path References/Zotero/zotero-index.json(0.6.5 이전 기본값 80. References/zotero-index.json은 인덱스가 이미 있으면 유지)
Literature index Maximum index age 60분(1–10080); 지나면 다음 조회 때 백그라운드 갱신
Literature index Refresh saved index 지금 인덱스 갱신
Citations Citation trigger Bracket: [@ 뒤에 자동완성; At sign: 단독 @ 뒤에도; Off
Citations Citation format pandoc; Zotero 인용 선택기의 형식
Citations Picker wait 600초(30–1800); 인용 선택을 기다리는 시간
Citations Default citation format Pandoc citation([@key]); 인덱스에서 넣는 인용과 붙여 넣은 Zotero 링크의 형식
Citations Mark citekey problems 켬; 없는·모호한·예전 citekey에 밑줄
Citations Citation hover preview 끔; 제목·저자·연도·참고문헌 카드
Citations Show citations as author-date 끔; 읽기 보기와 실시간 미리보기에서 저자-연도로 표시, 텍스트는 그대로
Citations Mod+click on a citation Nothing; 또는 Literature note, PDF(위치의 쪽)
Citations Paste Zotero links as citations 끔; 붙여 넣거나 끌어 놓은 Zotero 항목 링크를 인용으로
Literature notes Output folder References/Zotero; 새 문헌 노트 위치
Literature notes New note file name @{citekey}; 고정 토큰 {citekey}, {title}, {shortTitle}, {year}, {firstAuthor}, {itemType}, {collection}
Literature notes New note subfolder 비움(출력 폴더 바로 아래); 같은 토큰, 단계 사이는 /
Literature notes Image folder References/Zotero/images; 이미지 주석 사본 위치
Literature notes Excluded tags obscite; 노트와 주석 태그에 넣지 않을 Zotero 태그, 한 줄에 하나
Note layout Abstract, Bibliography entry, Metadata fields, Links, Zotero notes, Synthesis scaffold 켬; 끄면 빈 생성 블록으로 자리만 유지
Note layout Fields by item type 끔; Zotero 항목 유형에 맞는 메타데이터 필드
Note layout Join continued highlights 끔; 코멘트가 +로 시작하는 하이라이트를 앞의 것에 합침
Note layout Zotero rich text 끔; Zotero의 기울임·굵게·줄바꿈을 Markdown으로
Note layout Annotation tags Plain; 또는 Obsidian 태그(#tag)
Note layout Synthesis lines, Annotations heading, callout types 0.6.0 노트 그대로; 테마에 맞게 이름 변경
Annotations Heading highlight color Gray; 이 색 하이라이트는 제목이 됨(None이면 모두 콜아웃)
Annotations Follow the Zotero selection 끔; 창에 초점이 올 때, 또는 사이드바가 선택 항목을 보여 주는 동안 몇 초마다
Annotations Selection check interval 10초(3–30)
Bibliography and references Bibliography style apa; Zotero에 설치된 CSL 스타일 ID, 저장할 때 BBT로 확인; 노트의 csl이 우선
Bibliography and references Choose an installed style Choose style로 설치된 스타일을 보고 고른 스타일을 확인
Bibliography and references Bibliography locale 비움(스타일 기본값); 예: ko-KR; 노트의 lang이 우선
Bibliography and references Bibliography order 스타일이 정한 순서; 또는 처음 인용한 순서, 가나다·알파벳순
Bibliography and references Zotero data directory ~/Zotero; Zotero의 styles 폴더가 있는 폴더, 읽기 전용
Bibliography and references Allow export kits outside the vault 꺼짐. 켜면 Export kit folder에 절대경로나 ~/ 경로를 쓸 수 있음(0.6.6)
Bibliography and references Export kit folder CMDS Zotero exports; 내보내기 키트 위치, 노트마다 하위 폴더
Bibliography and references Run pandoc after export 꺼짐. 켜면 키트에 pandoc을 실행하고 .docx를 엶(0.6.6)
Bibliography and references Pandoc path 비우면 흔한 설치 폴더, 그다음 시스템 검색 경로
Bibliography and references Link exports in Hookmark 꺼짐. 켜면(macOS) .docx와 노트를 Hookmark로 연결(0.6.6)
Bibliography and references References sidebar follows the active note 켬; 끄면 Refresh를 누를 때까지 보던 노트를 유지
Recently read Recently read window 30일(7/30/90/365); 최근 읽은 논문 목록과 자료 선택 창 정렬
Connected vaults Peer vaults 한 줄에 볼트 이름 | 절대 경로; 다른 볼트 노트 찾기용
Advanced Request timeout 20초(1–180)
Advanced Attachment timeout 60초(1–180); 이미지 렌더링이 필요한 첨부는 더 걸릴 수 있음
Advanced Parallel requests 2(1–8); 내보내기·참고문헌·읽기 기록 요청을 동시에 보내는 수
Advanced Refresh requests 4(1–8); 인덱스 갱신 중 동시에 보내는 요청 수, Zotero가 느려지면 낮춤
Advanced References headings 에이전트 cites가 References 구역으로 볼 제목; 기본 References, Bibliography, Works Cited, 참고 문헌, 참고 자료

PDF 텍스트와 에이전트

AI 에이전트와 스크립트는 같은 기능을 CLI로 씁니다. CLI는 실행 중인 Obsidian의 플러그인에 작업을 맡기고, 가능한 읽기 작업은 Obsidian 없이 인덱스 파일로 답합니다.

node scripts/ingest.mjs --vault "Research" --action recent --days 30
node scripts/ingest.mjs --vault "Research" --action import --citekey Example2026
node scripts/ingest.mjs --vault "Research" --action import --citekey Example2026 --apply
node scripts/ingest.mjs --vault "Research" --action pdf-text --citekey Example2026 --pages 1-3
node scripts/ingest.mjs --vault "Research" --action locate --citekey Example2026 --quote "quoted text"
  • recent는 읽은 날짜와 노트 상태(none, behind, current, foreign, duplicate)를 돌려줍니다.
  • import는 --apply가 없으면 미리보기만 합니다. 하드 충돌은 note-conflict로 거절합니다. Zotero에서 실시간으로 읽지 못하면 --allow-stale 없이는 쓰지 않습니다.
  • pdf-text는 Obsidian에 내장된 pdf.js로 텍스트를 뽑아 비공개 캐시(.cmds-zotero/pdf-text/)에 저장합니다. 한·중·일 글꼴용 문자 지도를 함께 씁니다. 텍스트 레이어가 없는 스캔본은 textLayer: none과 OCR 권장 경고를 냅니다. 페이지마다 반복되는 워터마크는 본문으로 세지 않습니다.
  • locate는 인용문이 있는 쪽을 찾아 Zotero 리더 링크와 함께 돌려줍니다.
  • annotations(0.6)는 논문의 주석을 첨부별·읽기 순서로 돌려주며 --color, --type, --tag, --attachment로 거릅니다. --fresh는 지금의 Zotero를 읽고 --today는 오늘 연 논문을 고릅니다.
  • citing(0.6)은 이전 citekey까지 포함해 논문을 인용한 노트를 줄 번호·발췌와 함께 보여 줍니다.
  • resolve --stdin(0.6)은 한 줄에 JSON 하나씩, 최대 500건을 한 번에 조회합니다.
  • 읽기 전용 환경에서는 scripts/ingest-ro.mjs를 씁니다. 쓰기와 --apply를 거절합니다. 에이전트는 관리 구역을 직접 고치지 않고, 자기 요약은 ## Synthesis나 ## Notes에 씁니다. 전체 규약은 에이전트 계약에 있습니다.

교차 볼트와 Hookmark

Peer vaults에 등록한 다른 볼트의 노트 지도를 읽기 전용으로 읽고 Find literature across vaults로 이동합니다. 같은 citekey라도 다른 볼트에서는 다른 자료일 수 있으므로 식별을 확인합니다. Hookmark 링크 명령은 링크를 클립보드에 복사할 뿐입니다. 북마크는 Link exports in Hookmark(기본 꺼짐, macOS)를 켰을 때만 만듭니다. pandoc이 끝난 뒤 .docx와 원고 노트를 북마크 두 개로 만들어 서로 연결합니다.

데이터와 개인정보

  • 로컬 BBT에 메타데이터, 인용, 참고문헌, 첨부와 주석, 읽기 기록을 요청합니다. Zotero 설정, 데이터베이스, citekey, 라이브러리 기록은 바꾸지 않습니다.
  • 이미지 주석을 가져오거나 주석 사이드바·Search annotations에서 콜아웃으로 넣으면 볼트 밖의 Zotero 캐시 이미지를 읽어 이미지 폴더에 복사합니다. 설치된 스타일이 필요할 때(스타일 고르기, csl로 스타일을 지정한 노트, pandoc 내보내기 키트) Zotero styles 폴더의 .csl 파일을 읽기 전용으로 읽습니다.
  • 볼트에 쓰는 것은 설정, 인덱스, 문헌 노트, 이미지 사본, 요청한 내보내기 키트, .cmds-zotero/ 아래의 비공개 파일(참고문헌·노트 지도·백업·PDF 텍스트 캐시)입니다. 플러그인은 .cmds-zotero/.gitignore를 먼저 만들어 이 폴더가 git에 올라가지 않게 합니다. PDF 텍스트 캐시는 논문 전문이므로 공유하지 않습니다.
  • 인덱스와 노트 지도에는 서지정보, 개인 경로, 주석이 들어갈 수 있습니다. 공개 저장소에 올리지 않습니다.
  • 에이전트 요청과 Diagnose setup·Diagnose index and links 명령을 처리할 때, 볼트가 Git 저장소이면 비공개 파일이 git에서 무시되는지 알리려고 git을 읽기 전용(ls-files, check-ignore)으로 실행합니다. 선택 설정(모두 기본 꺼짐)을 켠 경우에만 내보내기 때 다른 프로그램을 띄웁니다. Run pandoc after export는 키트에 pandoc을 실행하고 .docx를 열며, Link exports in Hookmark는 osascript로 Hookmark 북마크를 만듭니다. 모두 셸 없이, 시간 제한을 두고 실행합니다. 그 밖의 프로그램은 실행하지 않습니다.
  • 텔레메트리, 자체 HTTP 서버, 자동 업데이트는 없습니다.

문제 해결

증상 확인할 것
최근 읽은 논문이 비어 있음 Zotero 실행 여부, 기간(Reading window), PDF를 Zotero 리더로 열었는지
새 하이라이트가 노트에 없음 Zotero 실행 여부; 꺼져 있으면 저장된 인덱스로 렌더링됨
노트가 "not created by CMDS Zotero"로 거절됨 다른 플러그인이 만든 노트; 덮어쓰지 않음. 출력 폴더나 파일명을 확인하거나 Adopt current note as literature note로 넘겨받기
가져오기 차단(손상된 마커) 미리보기의 줄 번호에서 마커를 고치거나, Reset을 쓰거나, Rebuild current literature note 실행
Update all owned literature notes가 바로 시작하지 않고 목록을 보여 줌 0.6.3부터 모든 일괄 작업은 먼저 검토 목록을 보여 줌; 원하는 행을 선택하고 적용 버튼을 누름
노트가 Better Notes 동기화 노트라며 건너뜀 Better Notes가 갱신 내용을 덮어씀; 그 노트만 따로 갱신하면 쓰기 전에 경고함
Update literature notes changed in Zotero가 방금 주석을 단 노트를 건너뜀 날짜는 저장된 인덱스에서 옴; 먼저 Refresh citekey index 실행
참고문헌 스타일이 거절됨 Better BibTeX가 렌더링하지 못함, 메시지에 이유가 있음; Zotero에 스타일이 설치되었는지, Zotero data directory와 Bibliography locale 확인
편집기에서 citekey에 밑줄이 그어짐 인덱스에 없거나, 여러 항목이 쓰거나, 예전 키임: 인덱스를 갱신하거나 Check citations in current note, Fix renamed citekey in this note 실행; 표시를 숨기려면 Mark citekey problems 끄기
내보내기 키트가 새 폴더를 제안함 이전 키트의 파일을 고쳤음; 고친 키트는 덮어쓰지 않음
인덱스 갱신이 거부됨 옛 플러그인 cmds-link-zotero가 켜져 있는지
연결 실패 Zotero·BBT 실행과 localhost 주소, 시간 제한; Diagnose setup 실행
인용 선택기가 "No citation was picked"를 알림 선택기를 닫았거나 Picker wait가 지남; 명령을 다시 실행
최근 읽은 논문에서 Zotero 10이 필요하다고 함 읽기 기록은 Zotero 10 이상에서만 제공됨
PDF가 다른 쪽으로 열림 인쇄 쪽 번호가 아닌 파일 위치 기준인지
pdf-text가 빈 결과 textLayer 값; none이면 스캔본이므로 OCR 필요

옛 플러그인 ID에서 이전

cmds-link-zotero에서 옮길 때는 Obsidian을 끄고 scripts/migrate-local.mjs를 dry-run → check → apply 순서로 씁니다. 백업 폴더는 볼트와 저장소 밖의 새 비공개 폴더로 정합니다.

node scripts/migrate-local.mjs --vault /path/to/vault --backup /path/to/private-backups/migration-001 --mode dry-run
node scripts/migrate-local.mjs --vault /path/to/vault --backup /path/to/private-backups/migration-001 --mode check
node scripts/migrate-local.mjs --vault /path/to/vault --backup /path/to/private-backups/migration-001 --mode apply --expect CHECK_FINGERPRINT

rollback 모드로 되돌릴 수 있으며, 배포 이후 바뀐 파일은 덮어쓰지 않고 거부합니다. 이전 뒤에는 새 ID만 켜져 있는지 확인하고 인덱스를 다시 만듭니다.

업데이트, 지원, 라이선스

웹 설명서 | 저장소 | 릴리스 | 문제 신고 | 변경 이력 문제를 신고할 때는 플러그인·Obsidian·Zotero·BBT 버전과 OS, 개인정보를 지운 진단 결과를 적습니다. 실제 인덱스, 개인 경로, 주석 원문, PDF 텍스트 캐시는 올리지 않습니다. Yohan Koo (CMDSPACE), https://cmdspace.work. MIT, LICENSE.

맨 위로 ↑
← PluginsPublic release 0.6.7

CMDS Zotero / Bring what you read into notes

What you read in Zotero,
in your notes.

Send papers you read and marked up in Zotero's reader to literature notes: metadata, highlights and comments, Zotero notes, citations and links back to the source, while the text you write stays yours.

User guide ↓GitHub source ↗

Before you start

Obsidian desktop 1.7.2+ / Zotero + Better BibTeX / install from Community plugins

Know the boundaries

Zotero is read-only, and the recently read list needs Zotero running.

Documentation checked 2026-10-29Source version 0.6.7Markdown ↙

CMDS Zotero user guide

Send what you read and mark up in Zotero to Obsidian literature notes. Metadata, highlights and comments, Zotero notes, citations and links back to the source end up in one note, and the text you write yourself stays untouched. Zotero is treated as read-only.

Version and release status

This guide covers CMDS Zotero 0.6.7, released on 2026-10-29. The GitHub release carries main.js, manifest.json and styles.css, built and attested by CI. Install it from Settings → Community plugins → Browse, manually, or with BRAT. 0.6.5 builds the index of a new install at References/Zotero/zotero-index.json, next to the literature notes, instead of a numbered 80. References folder; an install that already has an index there keeps it. 0.6.4 readied the plugin for the Community directory: choosing an installed style now updates the settings field on Obsidian 1.13 and later, and commands for the current note appear only while a note is open. 0.6.3 finds literature notes you moved, names new notes from fixed tokens, imports by search, shows a review list before every batch, adopts notes made by other Zotero plugins, and adds per-note update, rebuild, frontmatter refresh, legacy-key cleanup and merged-item relink. 0.6.2, released the same day, added a citation editor, bibliographies in Zotero's installed styles and locales, Check citations, a references section and a pandoc export kit. 0.6.1 added note layout settings, Insert item content, a richer annotations sidebar, fielded search, Zotero selection commands and Diagnose setup. 0.6.0 made refreshes, startup and batch updates faster, keeps refreshes going past bad items, lets the citation picker wait for you, reorganises the settings tab and adds agent actions; the changelog lists every change. It was verified with Obsidian 1.14.4, Zotero 10.0.6 and Better BibTeX 9.0.71 on macOS. Checks of 0.5 on a real library covered the recently read list, creating and updating four literature notes, PDF text extraction for four papers (one of them a scan) and quote location. Group libraries and Windows/Linux are outside the verified scope. Coming from 0.6.1, four things look different with the default settings: citekey problems are underlined in the editor, a copied bibliography keeps the style's own order, Update all owned literature notes first shows a review list, and literature notes you moved out of the output folder are updated where they are. New notes keep the names and folders 0.6.1 gave them.

Requirements and terms

  • Obsidian desktop 1.7.2 or later. Mobile is not supported.
  • A running Zotero with Better BibTeX (BBT). The plugin talks only to BBT's local JSON-RPC.
  • Recently read papers use the reading history Zotero records when a PDF opens in its reader; this was verified on Zotero 10.
  • The default local endpoint is http://127.0.0.1:23119/better-bibtex. No Zotero Web API key, native Local API setting, SQLite access or separate PDF tool is needed. A citekey such as Example2026 is a citation label, not a permanent identifier. The plugin identifies an item by library type, local library ID and Zotero item key. Attachments and annotations have their own keys; a parent item is not a PDF.

Installation

Community plugins: open Settings → Community plugins → Browse, search for CMDS Zotero, select Install, then Enable.

Manual

  1. Download main.js, manifest.json and styles.css from the latest release.
  2. Put the three files in <vault>/.obsidian/plugins/cmds-zotero/.
  3. Reload Obsidian and enable CMDS Zotero under Settings → Community plugins.

BRAT: add johnfkoo951/cmds-zotero as a beta plugin in BRAT.

Upgrading keeps your settings (data.json) and index. Back up the plugin folder first. If the old cmds-link-zotero plugin shares the index path, disable it, or index refreshes are refused.

First success: send recently read papers to notes

  1. Start Zotero with Better BibTeX enabled.
  2. In Settings → CMDS Zotero, set Output folder, Image folder and Index path (vault-relative) and press Save configuration. Test connection tests the saved settings.
  3. Run Refresh citekey index once from the command palette (Ctrl/Cmd+P).
  4. Open a paper's PDF in Zotero's reader and add a highlight or a comment.
  5. Run Send recently read papers to notes, or click the open-book ribbon icon.
  6. Each row shows the state of its literature note: No literature note yet, N new annotations not in the note, Note is up to date, or a note CMDS Zotero did not create (never overwritten).
  7. Papers that need sending are preselected. Send creates the note or refreshes only its managed sections.
  8. Open the result with the row's note button and compare annotations, page links and metadata with Zotero.
  9. Write a sentence under ## Synthesis or ## Notes, add another highlight in Zotero and send again. Your sentence stays and only the new annotation is added: that is the first success.

The Reading window offers 7, 30, 90 or 365 days; the default is the Recently read window setting (30 days). Zotero must be running for the list.

Importing and updating literature notes

Import literature note lets you pick a source, shows a preview (path, per-section states, conflicts) and applies it. The picker lists recently read papers first, labelled like · read 3 days ago. Open or import literature note opens the source's note, or shows the import preview when the vault has none yet. Imports render from Zotero's current data (that item's export plus its attachments and annotations), not from the saved index, so highlights made a minute ago are included without refreshing the index. If the citekey changed in Zotero, the item is found again by item key; another item is never substituted. With Zotero closed, the preview uses the saved index and says so. Creating a new note needs bibliography text, so Zotero must be running for a first import.

Where new notes go. New note file name and New note subfolder (Settings → Literature notes) are built from the fixed tokens {citekey}, {title}, {shortTitle}, {year}, {firstAuthor}, {itemType} and {collection}, for example {year} {shortTitle} in the subfolder {itemType}. Characters that cannot be in file names are replaced, long names are shortened, and the preview shows the resulting path. The defaults (@{citekey}, no subfolder) keep the earlier names, and existing notes keep theirs. These are fixed tokens, not a template language.

Moved notes. A literature note you move or rename anywhere in the vault is found by its identity (its zoteroID together with the plugin's owner marker) and updated where it is, instead of being imported again. A note that only names the item, without the owner marker, is not treated as the literature note. Diagnose setup lists literature notes outside the output folder.

Updating one note. Update current literature note opens the update preview for the open note. For an existing note the preview has a Refresh group: switch off Title and abstract, Bibliography entry, Metadata and links, Zotero notes or Annotations, and those sections stay exactly as they are in this update.

Batches with a review list. Update all owned literature notes, Update literature notes changed in Zotero, Import literature notes by search and Adopt existing literature notes first show a review list: what happens to each note (Create, Update, Adopt, or Skip with the reason) and a box per row, with Select all and Select none. Nothing is read from Zotero or written before you press the apply button, and Cancel changes nothing. While the batch runs, a progress notice offers Cancel; the rest is then left as it was.

  • Update all owned literature notes refreshes the managed sections of every ticked note and reports Updated, Partial (edited sections preserved), Unchanged and Skipped. Several notes with one identity are skipped, and notes that link the item but were not created by CMDS Zotero are skipped with a hint to adopt them.
  • Update literature notes changed in Zotero opens the same list for notes whose item or annotations changed since the note was last written. Changed in Zotero since switches to Any time or a date. The dates come from the saved index, so refresh the index first; an unknown date is never treated as unchanged.
  • Import literature notes by search takes a fielded search such as col:methods, tag:method, type:book or year:2020- and creates notes only for matching items that have none yet. If two items would get the same file name, the second is skipped rather than written over the first.
  • Notes synced by the Zotero add-on Better Notes are skipped by batches, because Better Notes would overwrite the update; a single update shows a warning instead.

Adopting notes from other plugins. Adopt current note as literature note takes a note made by Zotero Integration or ZotLit, or one named by citekey, and matches it to its item by citekey, DOI or Zotero link (when several items match, you choose). After a preview and a backup it adds the missing identity keys line by line and appends the generated sections below your text; nothing you wrote is changed. Adopt existing literature notes does the same for every matching note in the vault, after the review list; a match by DOI alone starts unticked. Notes whose type is paper-hub, paper-analysis or raw-source, notes under 10. Raw Sources, notes that belong to Bookends or Better Notes, and notes CMDS Zotero already owns are refused.

Repairing a note. Rebuild current literature note backs up the note, renders the generated sections again and repairs damaged, duplicate and missing markers. Every line you wrote stays; an edited or detached duplicate keeps its text.

Frontmatter and identity. These commands work on the open note. Each shows a line-by-line preview (only the lines marked - and + change), copies the note to the backup folder first, and checks that the note did not change before, during and after the write.

  • Refresh frontmatter of current note from Zotero updates only the plugin's metadata keys the note already has. It never touches zoteroID or tags and adds no keys.
  • Remove legacy keys from current note removes the keys that versions 0.3 and 0.4 wrote. Report notes with legacy Zotero keys lists the notes that still carry them, without changing anything.
  • Relink current note to merged Zotero item: when Zotero merged the note's item into another one, it points the note to the surviving item. It works only with a complete index; with several candidates you choose.

Note layout and preservation

A new note's frontmatter holds type: zotero, zoteroID, zoteroSelectURI, zotero-key, citekey, doi, title, authors, year, tags and the zotero_* fields such as zotero_title. Frontmatter is written once and is yours afterwards. Updates never change it; only the frontmatter commands above do, after a preview. The body follows this order:

  • Title and abstract (overview), bibliography text (citation)
  • ## Synthesis: your area (**Contribution**::, **Related**::)
  • Metadata and links (metadata): creators, journal, DOI, URL, tags, collections, related Zotero items, links that open Zotero and the PDF
  • ## Zotero notes (notes): Zotero child notes as Markdown with headings, lists and links kept; code blocks pass through unchanged
  • ## Notes: your area
  • ## Annotations: one block per annotation, in Zotero's reading order, so an annotation added later on an earlier page still lands in place. Highlights, underlines, images, comments and ink drawings are distinguished, and page links open that spot in Zotero's reader.

Managed sections sit between <!-- cmds-zotero:<id>:<hash> --> and <!-- /cmds-zotero:<id> -->. If you edit one, only that section is kept as edited (preserved) while the rest of the note updates. In the preview you choose per section:

  • Keep this time: leave it as it is for this update.
  • Detach: make the block permanently yours; it is never rendered again.
  • Reset from Zotero: replace it with Zotero's content; the previous note is first backed up to .cmds-zotero/backups/notes/. Damaged or duplicate markers, a note CMDS Zotero did not create, or several notes with one identity block the write, with the reason and line number shown; Rebuild current literature note repairs damaged markers. Blocks for annotations deleted in Zotero are never removed from the note.

Citations, bibliographies and sidebars

Inserting citations

  • Insert citation from Zotero uses BBT's Cite As You Write picker; the default format is [@citekey]. A notice with a Cancel button shows while the picker is open, and the command waits up to Picker wait (10 minutes). If you switch notes meanwhile, the citation goes to the clipboard instead.
  • Typing part of a citekey, title, author or year after [@ in the editor opens local completion. It reads the cached index, so Zotero is not called on every keystroke. Korean is found whether it is typed composed or decomposed, and accents are ignored (é matches e). Enter inserts the citation, Shift+Enter a narrative @key, Mod+Enter a link to the literature note.
  • A new citation joins the one at the cursor: typing [@ right after [@kim2020], or citing from Zotero's picker, the Zotero selection or the literature picker, gives [@kim2020; @lee2021] without repeating a key.
  • Pandoc prefixes, locators and suffixes are understood, as in [see @kim2020, pp. 33–35; also -@lee2021, ch. 1]. Edit citation locator changes the locator of the citation at the cursor.
  • In Korean sentences, do not attach a particle right after @key: pandoc reads it as part of the citekey. Add a space (@key 는) or attach the particle after a bracket. To write a Korean author as "구요한 외(2005)", write the name and cite only the year: 구요한 외[-@key]는; styles do not produce "외". With a note style, use [@key] only. Rendered examples are on the Korean docs site.
  • Insert citation from the literature index picks a source from the index and inserts it in the Default citation format. Each format also has its own command: Insert pandoc citation ([@key]), Insert narrative citation (@key), Insert citekey wikilink ([[@key]]), Insert author-date citation text ((Kim & Lee, 2020), an approximation from the index), Insert Zotero item link and Insert literature note link. These are fixed formats, not templates.
  • Pickers and completion understand fields: author:, title:, year:2019-2021, tag:, col:<collection path>, lib:, type: and has:pdf|note|annotations, each negatable with -; quote values with spaces.
  • Insert item content from Zotero inserts a source's Zotero notes, bibliography entry, metadata, abstract, links or annotations into the current note as text you own.
  • Paste Zotero links as citations (off by default): pasting or dropping Zotero item links (zotero://select/…) inserts a citation in the default format, matched by library and item key. Links the index does not know are pasted as they are.

Citations in the editor

  • Citekeys the index does not have, that several items carry, or that are a former key of an item are underlined (Mark citekey problems, on by default). Nothing is marked before the index loads, and an incomplete index never marks a key as unknown.
  • Citation hover preview shows a card with title, authors, year and bibliography entry, and Show citations as author-date shows [@kim2020, p. 3] as "(Kim & Lee, 2020, p. 3)" in reading view and live preview. Both are off by default and never change the note text.
  • Mod+click on a citation can open the literature note or the PDF at the locator page (off by default). Right-click menu entries act on the clicked citation, not on the cursor.
  • Citation actions at cursor lists what you can do with the citation under the cursor. The same actions are separate commands: Open literature note for citation at cursor (offers the import preview when there is no note), Open PDF at citation locator (the locator's page label is matched to Zotero's page labels when the index knows them; the notice says how the page was found), Copy PDF page link for citation at cursor, and Fix renamed citekey in this note, which previews every citation of the former key in this note's body and replaces them in one undo step.
  • A citekey that several items carry asks which item you mean instead of failing.

Bibliographies and references

  • Bibliography style: Choose style (Settings → Bibliography and references) and the command Choose bibliography style from installed styles list the styles in Zotero's styles folder, read-only (set Zotero data directory if it is not ~/Zotero). A style Better BibTeX cannot render is refused with the reason. A style or locale typed by hand is checked the same way when you press Save configuration.
  • Bibliography locale sets the language and region of bibliography terms and dates, for example ko-KR or de-DE; empty keeps the style's default.
  • A note's own csl and lang frontmatter set the style and locale for that note: its references sidebar, Insert bibliography, copied bibliography, references section and export kit. csl: apa.csl is matched to an installed style by file name. lang sets the language of the bibliography terms, not of the manuscript: a Korean manuscript citing English sources in English style keeps en-US, while ko-KR only translates the terms inside the English style ("Eds." becomes "편집자", "et al." becomes "기타"). Three csl/lang recipes are on the Korean docs site.
  • Open references sidebar collects [@key], @key and citation wikilinks in the current note and shows their bibliography and unresolved states. With Zotero closed it uses saved bibliography text (.cmds-zotero/bibliography.json). It counts citations the way pandoc does: citations in code, HTML comments and %% comments, an escaped \@ and e-mail addresses are left out; -@key and keys in nocite are counted. Each row jumps to the previous or next occurrence, and Go to next occurrence of the citation at cursor and Go to previous occurrence of the citation at cursor do the same from the editor.
  • Check citations in current note lists unknown, ambiguous and former keys, keys without a literature note and nocite keys, from the saved index; each occurrence opens in the note.
  • Copy bibliography for current note (also a button in the references sidebar) puts formatted (HTML) and plain text on the clipboard, so it pastes formatted into word processors. Bibliography order decides the order: as the style orders it (default), order of first citation, or alphabetical.
  • Insert or update references section writes a plugin-owned block at the end of the note after a preview; the note is backed up before the first insert. An unedited block is updated in place, an edited one is kept as it is, and changing its opening marker to <!-- cmds-zotero-references:detached --> keeps it as yours for good.
  • Insert bibliography inserts one source's CSL bibliography text.
  • Open annotations sidebar shows the annotations of the current literature note, the item selected in Zotero, the citekey at the cursor or a pinned source. Filter by colour, type, tag or attachment, sort and group, fetch the latest annotations from Zotero, drag a card into a note, or use a card's More actions menu. Search annotations searches every indexed annotation and inserts it as a callout or quote.

Exporting with pandoc

  • Export pandoc kit for current note writes into Export kit folder (default CMDS Zotero exports), one subfolder per note: a cleaned copy of the note (literature links become [@key], callouts become blockquotes, comments and markers are removed), the cited sources as CSL-JSON, a pandoc defaults file and a small filter that keeps local paths out of the .docx. The copy's frontmatter keeps only the fields meant for the document. The pandoc command line goes to the clipboard. The source note is not changed, the plugin never runs pandoc, and an earlier kit you changed is never overwritten; a new folder is offered instead.
  • Export Word kit with live Zotero citations for current note (0.6.6) writes <note> (Word) in the same folder: the cleaned copy, a defaults file and a small filter. Run the copied command while Zotero is open; the .docx holds Zotero fields, so in Word you press Refresh in the Zotero tab once and then add citations, refresh and change the style there. The note's style must be installed in Zotero, and Better BibTeX's zotero.lua must be in pandoc's filters folder (the report shows the install line). See pandoc-docx.md §0b.
  • Copy CSL-JSON for cited sources and Write pandoc bibliography sidecar for current note copy the current note's cited sources as CSL-JSON, or save them to .cmds-zotero/bibliography/<note>.json and show the bibliography: line for the frontmatter.
  • The pandoc/DOCX guide explains the kit and the export step by step.

All commands

Command What it does
Send recently read papers to notes Shows papers recently read in Zotero with their note states and sends them
Import literature note Previews and imports or updates one source
Open or import literature note Opens a source's note, or shows the import preview when there is none
Update current literature note Previews an update of the open note, with a choice of sections to refresh
Update all owned literature notes Refreshes managed sections of every note the plugin created, after a review list
Update literature notes changed in Zotero Like Update all, limited to notes whose item or annotations changed
Import literature notes by search Creates notes for the items matching a fielded search, after a review list
Adopt current note as literature note Turns a note from another Zotero plugin into a CMDS Zotero note, keeping your text
Adopt existing literature notes Adopts every matching note in the vault, after a review list
Rebuild current literature note Re-renders the generated sections and repairs markers, after a backup
Refresh frontmatter of current note from Zotero Updates the plugin's metadata keys the note already has, after a preview
Remove legacy keys from current note Removes the keys 0.3 and 0.4 wrote, after a preview
Report notes with legacy Zotero keys Lists notes that still carry legacy keys; changes nothing
Relink current note to merged Zotero item Points the note to the item Zotero merged it into
Refresh citekey index Rebuilds the index from BBT
Search literature Picks a source and an action (open, import, copy links and more)
Insert citation from Zotero Inserts a citation from Zotero's picker, with Cancel
Insert citation from the literature index Inserts a citation in the default format from the index
Insert pandoc citation, Insert narrative citation, Insert citekey wikilink, Insert author-date citation text, Insert Zotero item link, Insert literature note link Inserts a citation in that format
Citation actions at cursor Lists the actions for the citation under the cursor
Edit citation locator Changes the locator of the citation at the cursor
Open literature note for citation at cursor Opens the cited source's note, or the import preview
Open PDF at citation locator Opens the PDF at the locator's page
Copy PDF page link for citation at cursor Copies a link to that PDF page
Fix renamed citekey in this note Replaces a former citekey in this note, after a preview
Go to next / previous occurrence of the citation at cursor Jumps between occurrences of one citation
Check citations in current note Lists unknown, ambiguous, former and note-less keys
Insert bibliography Inserts one source's bibliography
Copy bibliography for current note Copies the cited sources' bibliography as formatted and plain text
Insert or update references section Writes or updates a managed references block at the end of the note
Choose bibliography style from installed styles Picks a style from Zotero's styles folder and checks it with BBT
Export pandoc kit for current note Writes a cleaned copy, CSL-JSON and pandoc defaults for export
Export Word kit with live Zotero citations for current note Writes a cleaned copy and pandoc defaults whose .docx keeps Zotero fields for Word
Copy CSL-JSON for cited sources Copies CSL-JSON for the current note's citations
Write pandoc bibliography sidecar for current note Saves a bibliography file for pandoc
Open references sidebar Reviews the current note's citations
Open annotations sidebar Reviews and inserts annotations
Open source PDF at page Opens the PDF at a file-position page
Open link under cursor Opens the Zotero link or [@citekey] under the cursor
Find notes citing a source Finds notes that use the current or a previous citekey
Find literature across vaults Finds notes for the same source in allowed peer vaults
Copy Zotero item link (Hookmark-compatible) Copies a Markdown link to the Zotero item
Copy literature note identity link (rename-safe) Copies a link that keeps working after the note is renamed
Copy Obsidian file link (Hookmark-native) Copies the literature note's obsidian://open address
Diagnose index and links Diagnoses connection, index and identities
Diagnose setup Report-only setup checks with a copyable report
Insert item content from Zotero Inserts a source's notes, citation, metadata, abstract, links or annotations
Search annotations Searches every annotation and inserts it
Open / Import / Cite Zotero selection Acts on the items selected in Zotero, read when you run the command
Copy Zotero action script Copies an Actions & Tags script that opens notes from Zotero menus (setup)
Annotations sidebar: … Follow modes, pin, unpin and fetch latest for the annotations sidebar

PDF page numbers are one-based file positions, not printed page labels.

Settings

Settings are grouped by area; request limits and the agent-only References headings are under Advanced. Values are checked as you type. Switches and menus are saved as soon as they change (0.6.7). After typing a value, press Save configuration; until then the previous value applies.

Section Setting Default and meaning
Connection Server endpoint http://127.0.0.1:23119/better-bibtex; localhost only
Connection Test connection Tests the saved endpoint
Literature index Index path References/Zotero/zotero-index.json (before 0.6.5: 80. References/zotero-index.json, kept where an index already is)
Literature index Maximum index age 60 min (1–10080); older indexes refresh in the background on the next read
Literature index Refresh saved index Refreshes the index now
Citations Citation trigger Bracket: completion opens after [@; At sign: also after a bare @; Off
Citations Citation format pandoc; the format of Zotero's citation picker
Citations Picker wait 600 s (30–1800); how long inserting a citation waits for your pick
Citations Default citation format Pandoc citation ([@key]); used for citations from the literature index and for pasted Zotero links
Citations Mark citekey problems On; underlines unknown, ambiguous and former citekeys
Citations Citation hover preview Off; a card with title, authors, year and bibliography entry
Citations Show citations as author-date Off; author-date display in reading view and live preview, the text is unchanged
Citations Mod+click on a citation Nothing; or Literature note, or PDF (at the locator page)
Citations Paste Zotero links as citations Off; pasted or dropped Zotero item links become citations
Literature notes Output folder References/Zotero; where new literature notes go
Literature notes New note file name @{citekey}; fixed tokens {citekey}, {title}, {shortTitle}, {year}, {firstAuthor}, {itemType}, {collection}
Literature notes New note subfolder Empty (directly in the output folder); same tokens, / between levels
Literature notes Image folder References/Zotero/images; copies of image annotations
Literature notes Excluded tags obscite; Zotero tags left out of notes and annotation tags, one per line
Note layout Abstract, Bibliography entry, Metadata fields, Links, Zotero notes, Synthesis scaffold On; a switched-off part keeps an empty generated block
Note layout Fields by item type Off; metadata fields chosen per Zotero item type
Note layout Join continued highlights Off; a highlight whose comment starts with + joins the one before it
Note layout Zotero rich text Off; italics, bold and line breaks from Zotero as Markdown
Note layout Annotation tags Plain; or Obsidian tags (#tag)
Note layout Synthesis lines, Annotations heading, callout types The 0.6.0 note; rename to fit your theme
Annotations Heading highlight color Gray; highlights in this color become headings (None keeps every highlight a callout)
Annotations Follow the Zotero selection Off; on window focus, or also every few seconds while the sidebar shows the selection
Annotations Selection check interval 10 s (3–30)
Bibliography and references Bibliography style apa; an installed Zotero CSL style ID, checked with BBT on Save; a note's csl overrides it
Bibliography and references Choose an installed style Choose style lists Zotero's installed styles and checks the one you pick
Bibliography and references Bibliography locale Empty (the style's default); for example ko-KR; a note's lang overrides it
Bibliography and references Bibliography order As the style orders it; or order of first citation, or alphabetical
Bibliography and references Zotero data directory ~/Zotero; the folder that holds Zotero's styles folder, read only
Bibliography and references Allow export kits outside the vault Off; on lets Export kit folder be an absolute folder or one under ~/ (0.6.6)
Bibliography and references Export kit folder CMDS Zotero exports; where the export kits go, one subfolder per note
Bibliography and references Run pandoc after export Off; on runs pandoc on the kit and opens the .docx (0.6.6)
Bibliography and references Pandoc path Empty: the usual install folders, then the system's search path
Bibliography and references Link exports in Hookmark Off; on (macOS) hooks the .docx and the note in Hookmark (0.6.6)
Bibliography and references References sidebar follows the active note On; when off the sidebar keeps its note until you press Refresh
Recently read Recently read window 30 days (7/30/90/365); the recently read list and picker ordering
Connected vaults Peer vaults One Vault name | absolute path per line, for cross-vault lookup
Advanced Request timeout 20 s (1–180)
Advanced Attachment timeout 60 s (1–180); attachments that need image rendering can take longer
Advanced Parallel requests 2 (1–8); requests at once for exports, bibliographies and reading history
Advanced Refresh requests 4 (1–8); requests at once during an index refresh; lower it if Zotero slows down
Advanced References headings Headings that mark a References section for the agent cites action; defaults References, Bibliography, Works Cited, 참고 문헌, 참고 자료

PDF text and agents

AI agents and scripts use the same features through the CLI. It hands work to the plugin in the running Obsidian and answers read-only requests from the index file when Obsidian is not available.

node scripts/ingest.mjs --vault "Research" --action recent --days 30
node scripts/ingest.mjs --vault "Research" --action import --citekey Example2026
node scripts/ingest.mjs --vault "Research" --action import --citekey Example2026 --apply
node scripts/ingest.mjs --vault "Research" --action pdf-text --citekey Example2026 --pages 1-3
node scripts/ingest.mjs --vault "Research" --action locate --citekey Example2026 --quote "quoted text"
  • recent returns read days and note states (none, behind, current, foreign, duplicate).
  • import previews only unless --apply is given. Hard conflicts are refused with note-conflict. If Zotero cannot be read fresh, nothing is written unless --allow-stale is given.
  • pdf-text extracts text with Obsidian's bundled pdf.js into a private cache (.cmds-zotero/pdf-text/), with the character maps CJK fonts need. A scan without a text layer reports textLayer: none and an OCR warning; watermarks repeated on every page are not counted as body text.
  • locate finds the page of a quote and returns a link into Zotero's reader.
  • annotations (0.6) returns a paper's annotations by attachment in reading order, filtered by --color, --type, --tag or --attachment; --fresh reads Zotero now and --today picks the paper opened today.
  • citing (0.6) lists the notes that cite a paper, former citekeys included, with line and excerpt.
  • resolve --stdin (0.6) answers up to 500 lookups given one JSON object per line.
  • In read-only contexts use scripts/ingest-ro.mjs, which refuses writes and --apply. Agents never edit managed sections; their own summaries go under ## Synthesis or ## Notes. The full rules are in the agent contract.

Cross-vault and Hookmark

The plugin reads the note maps of vaults listed in Peer vaults, read-only, and Find literature across vaults opens them. The same citekey in another vault can be a different source, so check the identity. The Hookmark link commands only copy links to the clipboard. Bookmarks are made only when you turn on Link exports in Hookmark (off by default, macOS): after pandoc, the .docx and its source note become two bookmarks hooked together.

Data and privacy

  • The plugin asks the local BBT for metadata, citations, bibliographies, attachments and annotations, and reading history. It never changes Zotero settings, the database, citekeys or library records.
  • Importing image annotations, or inserting one as a callout from the annotations sidebar or Search annotations, reads Zotero's cached image outside the vault and copies it into the image folder. Listing Zotero's installed styles (choosing a style, a note whose csl names one, the pandoc export kit) reads the .csl files in Zotero's styles folder, read-only.
  • In the vault it writes settings, the index, literature notes, image copies, export kits you ask for and private files under .cmds-zotero/ (bibliography, note map, backups, PDF text caches). It creates .cmds-zotero/.gitignore first so the folder stays out of git. PDF text caches hold full paper text; do not share them.
  • The index and note map can contain bibliographic data, private paths and annotations. Keep them out of public repositories.
  • For agent requests and the Diagnose setup and Diagnose index and links commands, when the vault is a Git repository, the plugin runs git read-only (ls-files, check-ignore) to report whether private files are ignored. Three opt-in settings (all off by default) start other programs only during an export: Run pandoc after export runs pandoc on the kit and opens the .docx, and Link exports in Hookmark runs osascript to make the Hookmark bookmarks. Each runs without a shell and with a time limit. It runs nothing else.
  • No telemetry, own HTTP server or self-updater.

Troubleshooting

Symptom Check
The recently read list is empty Zotero is running, the reading window, and the PDF was opened in Zotero's reader
A new highlight is missing from the note Zotero is running; with Zotero closed the saved index is used
A note is refused as "not created by CMDS Zotero" Another plugin created it; it is never overwritten. Check the output folder and file name, or take it over with Adopt current note as literature note
Import blocked by damaged markers Fix the marker at the line shown in the preview, use Reset, or run Rebuild current literature note
Update all owned literature notes shows a list instead of starting Since 0.6.3 every batch shows a review list first; tick the rows you want and press the apply button
A note is skipped as synced by Better Notes Better Notes would overwrite the update; update that note alone, which warns before writing
Update literature notes changed in Zotero skips a note you just annotated The dates come from the saved index; run Refresh citekey index first
A bibliography style is refused Better BibTeX could not render it; the message gives the reason. Check that the style is installed in Zotero, the Zotero data directory and the Bibliography locale
A citekey is underlined in the editor The index does not have it, several items carry it, or it is a former key: refresh the index, run Check citations in current note or Fix renamed citekey in this note; switch off Mark citekey problems to hide the marks
The export kit offers a new folder You changed a file of the earlier kit, which is never overwritten
Index refresh refused Whether the old cmds-link-zotero plugin is enabled
Connection fails Zotero and BBT are running, the localhost endpoint, timeouts; run Diagnose setup
The citation picker reports no pick The picker was closed or Picker wait ran out; run the command again
"Recently read" says Zotero 10 is needed Reading history needs Zotero 10 or later
A PDF opens on the wrong page Page numbers are file positions, not printed labels
pdf-text returns nothing The textLayer value; none means a scan that needs OCR

Migrating from the old plugin ID

To move from cmds-link-zotero, quit Obsidian and run scripts/migrate-local.mjs as dry-run, then check, then apply, with a new private backup folder outside the vault and the repository.

node scripts/migrate-local.mjs --vault /path/to/vault --backup /path/to/private-backups/migration-001 --mode dry-run
node scripts/migrate-local.mjs --vault /path/to/vault --backup /path/to/private-backups/migration-001 --mode check
node scripts/migrate-local.mjs --vault /path/to/vault --backup /path/to/private-backups/migration-001 --mode apply --expect CHECK_FINGERPRINT

rollback mode undoes it and refuses to overwrite files changed after deployment. Afterwards check that only the new ID is enabled and rebuild the index.

Updates, support and license

Web guide | Korean docs site | Repository | Releases | Issues | Changelog When reporting a problem, include the plugin, Obsidian, Zotero and BBT versions, your OS and diagnostics with private data removed. Do not post real indexes, private paths, annotation text or PDF text caches. Yohan Koo (CMDSPACE), https://cmdspace.work. MIT, LICENSE.

Back to top ↑