사용법#

프로필#

Harang Immich는 프로필을 통해 여러 Immich 서버와 연결할 수 있습니다. 각 프로필은 서버 주소, API 키, 기본 앨범을 하나로 묶고, 서로 구분할 수 있도록 이름을 붙일 수 있습니다 (예: “집 서버”, “회사 서버”).

Settings → Harang Immich를 열어 프로필을 관리하세요:

활성 프로필

이 기기가 이미지를 조회하고 업로드할 때 현재 사용하는 프로필입니다. 이 선택은 볼트가 아니라 기기에 로컬로 저장되므로, 데스크탑과 모바일이 서로 다른 프로필을(혹은 같은 프로필을) 각자 사용하더라도 볼트가 동기화될 때 서로의 설정을 덮어쓰지 않습니다.

프로필

프로필마다 다음 항목을 담은 섹션이 하나씩 있습니다:

프로필 이름: 직접 정하는 이름으로, 활성 프로필 선택 목록과 이미지 삽입 갤러리에 표시됩니다. 이 프로필에서 삽입하는 모든 이미지 링크에도 이 이름이 그대로 들어갑니다(아래 “링크 문법” 참고) — 프로필 이름을 바꾸면 그 이름으로 이미 삽입해둔 이미지가 깨지므로, 한 번 쓰기 시작한 이름은 어느 정도 고정된 값으로 취급하세요.
Immich 서버 주소: 해당 프로필이 사용하는 Immich 서버의 기본 주소입니다. 예: https://immich.example.com.
Immich API 키: 해당 Immich 계정에서 발급받은 API 키입니다 (사전 요구사항 참고). 이 키는 볼트에 평문으로 저장되지 않고 Obsidian의 SecretStorage에 저장되며, 프로필마다 자신만의 키를 가집니다.
Immich 앨범 선택 / 새 앨범 만들기: 이전과 동일하되, 해당 프로필의 서버로 범위가 한정됩니다.

각 프로필 제목 옆의 휴지통 버튼을 누르면 해당 프로필이 삭제됩니다. 프로필을 삭제해도 Immich 서버 자체에는 아무 영향이 없습니다 — 로컬에 저장된 연결 정보만 제거됩니다. 그 프로필로 이미 삽입해둔 이미지는 계속 해당 프로필을 참조하며(아래 참고), 프로필이 사라지고 나면 이미지 대신 “프로필을 찾을 수 없음” 오류가 표시됩니다.

프로필 추가

설정할 새 빈 프로필을 추가합니다.

캐시 관리

어느 프로필의 서버에서 가져온 썸네일이든 로컬(볼트 안 플러그인 전용 .cache 폴더)에 캐시되어 반복해서 다시 내려받지 않습니다. 이 섹션에서는 현재 캐시 사용량을 보여주고 캐시 비우기로 캐시를 비울 수 있습니다.

단일 서버만 지원하던 버전에서 업그레이드하는 경우, 새 버전에서 플러그인이 처음 로드될 때 기존 연결 정보가 자동으로 프로필 하나로 마이그레이션되며, 이미 삽입해둔 이미지들도 변경 없이 그대로 동작합니다.

핵심 기능 4가지#

1. Immich에서 이미지 삽입#

편집 모드에서 Immich 이미지 삽입 명령을 실행하세요 (명령 팔레트를 사용하거나 단축키를 지정할 수 있습니다). 활성 프로필의 기본 앨범(또는 전체 사진)의 썸네일을 보여주는 갤러리 창이 열립니다. 프로필이 두 개 이상 설정되어 있다면 상단의 활성 프로필 드롭다운으로 이번 선택에 한해 다른 프로필로 전환할 수 있고, 앨범 드롭다운으로 해당 프로필 서버의 다른 앨범으로 전환할 수 있습니다 — 둘 다 저장된 설정은 바꾸지 않습니다. 사진을 클릭하면 Harang Immich의 링크 문법으로 커서 위치에 삽입됩니다.

2. 편집 모드 미리보기#

편집 중(라이브 프리뷰)에는 노트에 있는 Harang Immich 링크가 인라인 이미지로 렌더링됩니다. 커서를 링크 텍스트 위로 이동하면 잠시 원본 문법이 드러나 편집할 수 있고, 커서를 다른 곳으로 옮기면 다시 이미지로 렌더링됩니다.

3. 읽기 모드 미리보기#

읽기(Reading) 보기에서도 편집 모드로 전환할 필요 없이 Harang Immich 링크가 동일한 방식으로 이미지로 렌더링됩니다.

4. 이미지 붙여넣기/드래그로 업로드#

편집 모드에서 클립보드의 이미지를 붙여넣거나 Obsidian 바깥에서 이미지를 드래그하면 활성 프로필의 서버로 자동 업로드됩니다. 업로드가 끝날 때까지 임시로 “업로드 중…” 표시가 들어가고, 완료되면 실제 링크로 교체됩니다. 업로드에 실패하면 표시가 지워지고 오류 알림이 표시됩니다. 해당 프로필에 앨범이 선택되어 있으면 업로드된 이미지는 자동으로 해당 앨범에 추가됩니다.

링크 문법#

Harang Immich 이미지는 표준 마크다운 이미지 링크 대신 전용 문법을 사용하므로, 플러그인이 실제 이미지로 치환하기 전까지는 Obsidian 기본 렌더러가 이를 그대로 둡니다:

![immich:profile name/ASSET_ID]
![immich:profile name/ASSET_ID|alt text]

프로필 이름이 링크를 원래 서버에 고정하므로, 프로필 이름이 그대로 유지되는 한 나중에 활성 프로필을 바꾸더라도 이미 삽입한 이미지는 깨지지 않습니다. 프로필 이름을 바꾸면 그 옛 이름으로 이미 삽입해둔 모든 이미지가 깨집니다 — 링크가 더 이상 그 이름의 프로필을 찾지 못하기 때문입니다 (실제로 어떻게 보이는지는 문제 해결 & FAQ 참고). 프로필 개념이 생기기 전에 만들어진 링크(![immich:ASSET_ID], 프로필 정보 없음)도 계속 동작합니다 — 그 프로필도 이름을 바꾸지 않았다면, 기존 단일 서버 설정이 마이그레이션된 프로필로 해석됩니다.

보통 이 문법을 직접 타이핑할 일은 없습니다 — 갤러리 명령이나 이미지 붙여넣기/드래그를 통해 자동으로 삽입됩니다.

이미지를 삭제할 때 Immich와 동기화 유지하기#

Harang Immich는 각 노트가 참조하는 Immich 에셋 ID를(그리고 각각 어느 프로필에 속하는지도) 추적합니다. 링크를 지우거나, 노트를 편집하거나, 노트 전체를 삭제하거나, 이름을 바꿔서 노트에서 링크가 사라지면 플러그인이 이를 감지하고 더 이상 참조되지 않는 Immich 에셋을 어떻게 처리할지 묻습니다. 한 노트가 여러 프로필의 에셋을 참조하고 있었다면, 각 에셋은 실제로 속한 서버에서 삭제됩니다:

휴지통으로 이동 — Immich에서 해당 에셋을 휴지통으로 보냅니다(소프트 삭제).
완전 삭제 — 해당 에셋을 즉시 삭제합니다.
취소 — 해당 에셋을 Immich에 그대로 둡니다.

노트 삭제나 이름 변경은 즉시 감지되며, 노트 내용 편집은 타이핑을 멈춘 뒤 짧은 지연(디바운스) 후에 확인하므로 편집 중에 안내창이 끼어들지 않습니다.