플러그인과 문제 해결

플러그인

Baram이 플러그인을 지원하나요?

네. 설정 > 플러그인을 열어 플러그인을 찾아보고 설치·업데이트·관리합니다. 탭에는 구역이 셋 있습니다 — 둘러보기(플러그인 발견), 설치됨(가진 것 전부를 내장·커뮤니티·개발 중으로 묶어 보여 줌), 업데이트(새 버전 적용).

플러그인을 클릭하면 에디터 탭에 상세 페이지가 열려 전체 설명, 렌더된 README, 요구하는 권한, 저장소·홈페이지 링크를 봅니다.

Baram과 함께 오는 플러그인을 끌 수 있나요?

네. 내장 플러그인 — 예를 들어 미디어 뷰어 — 도 다른 것과 같은 켬 / 끔 토글을 갖고, 그 선택은 재시작 후에도 기억됩니다. 끄면 아무것도 제거하지 않고 비활성화됩니다.

플러그인 하나가 “폐기됨”이라고 합니다

설치한 뒤에 그 플러그인 버전이 폐기될 수 있습니다 — 보안 문제가 발견됐거나 저자가 내렸기 때문입니다. Baram은 서명된 폐기 목록과 설치된 플러그인을 대조해 그 플러그인을 폐기됨으로 표시하고, 이유를 보여 주며, 실행하지 않습니다.

파일은 있던 자리에 그대로 둡니다 — 사용자 없이 아무것도 지우지 않습니다 — 그리고 제거 동작을 제안합니다. 폐기가 아니라 취약점 신고인 경우에는 플러그인이 계속 돌고, 새 버전이 나오면 Baram이 갱신하라고 합니다.

그 목록을 신뢰할 수 없을 때도 Baram이 그렇다고 말합니다 — 한 번도 받지 못했거나, 서명을 검증할 수 없었거나, 오래돼 낡았을 때 — 다 괜찮다고 암시하지 않습니다.

플러그인은 안전한가요?

플러그인은 권한으로 통제됩니다. 각자 필요한 권한(에디터, 파일, 명령, UI 등)을 선언하고, 설치 전에 사용자가 검토하고 승인합니다. 내려받은 파일은 SHA-256 체크섬으로 검증하고, 설치는 단계적입니다 — 다른 곳에서 풀어 검증한 뒤 모든 검사를 통과해야 제자리로 옮깁니다 — 그래서 설치가 중단돼도 반쯤 쓰인 플러그인이 남지 않습니다.

그 승인이 얼마나 강하게 강제되는지는 플러그인 종류에 달려 있습니다.

샌드박스 — 기본값이고 마켓플레이스에 올라오는 유일한 종류입니다. 플러그인 코드가 에디터와 격리되고 권한이 필요한 모든 동작이 승인한 권한과 대조되므로, 본 목록이 실제 경계입니다.
완전 신뢰 — 격리 없이 Baram 안에서 돕니다. 권한 목록은 그런 플러그인이 무엇을 하려는지 알려 줄 뿐 제한하지는 않습니다. 계정이 닿는 모든 파일, 모든 네트워크 호스트, 앱이 가진 모든 자격 증명에 닿을 수 있습니다. Baram이 빨간 경고를 띄우고 설치 전에 별도의 확인을 요구하므로 실수로 그리로 갈 수는 없습니다.

Baram을 업데이트했더니 플러그인이 멈췄습니다

v0.4.x로 설치한 플러그인은 v0.5.0 이후 버전이 불러올 수 없습니다. 그 버전들은 Baram에 플러그인 신뢰 모델이 생기기 전에 설치했으므로, 설치된 사본에 샌드박스로 도는지 완전 신뢰로 도는지 기록이 없습니다 — 그리고 Baram은 종류를 알 수 없는 플러그인을 실행하지 않습니다. 설정 > 플러그인 > 설치됨에서 그 플러그인에 오류가 보입니다.

업데이트 확인으로는 해결되지 않습니다. 그 플러그인은 업그레이드가 아니라 다시 승인받아야 하기 때문입니다. 설치됨 탭에서 제거한 뒤, 현재 버전이 마켓플레이스에 올라와 있으면 다시 설치하십시오. 그 시절 플러그인 중 일부는 다시 올라오지 않았고, 그런 것은 옛 사본을 제거하는 것이 할 수 있는 전부입니다.

이 일은 v0.5.0 전에 설치한 플러그인에 한 번만 적용됩니다. 그 뒤에 설치한 것은 영향이 없습니다.

플러그인을 어떻게 만드나요?

플러그인 개발 가이드를 보십시오. 플러그인은 baram-plugin.json 매니페스트와 ESM 진입점을 가진 디렉터리이고, ExtensionContext API로 명령·Tiptap 확장·UI 등을 더합니다.

문제 해결

앱이 시작되지 않습니다

macOS: v0.6.0 이후 빌드는 공증돼 있어 정상적으로 열립니다. “손상됐다”거나 “확인할 수 없다”는 경고는 가진 사본이 더 오래됐거나 내려받기가 손상됐다는 뜻입니다 — 현재 릴리스를 다시 내려받으십시오. 인터넷에서 내려받은 앱을 확인하라는 물음은 정상이고 오류가 아닙니다.
Windows: SmartScreen이 앱을 막으면 “추가 정보”를 클릭한 뒤 “실행”을 누르십시오
Linux: AppImage에 실행 권한이 있는지 확인하십시오 — chmod +x Baram-*.AppImage

macOS가 폴더 접근을 묻습니다

macOS는 앱이 보호된 위치 — 서류, 데스크탑, 다운로드, iCloud Drive — 의 파일을 처음 읽을 때 시스템 권한 물음을 띄웁니다. 한 번 허용하면 그 허가가 기억되고, 업데이트를 거쳐도 유지됩니다.

v0.5.x 이하에서 올라오셨나요? 이미 허용했더라도 한 번 더 묻습니다. 그 빌드들은 ad-hoc 서명이라 재빌드를 견디는 신원이 앱에 없었고, 그래서 macOS가 버전마다 다른 앱으로 보고 매번 다시 물었습니다. v0.6.0부터 Baram은 Apple Developer ID 인증서로 서명되고 신원이 안정적입니다 — 이번이 마지막일 것입니다.

v0.6.0 이후에도 물음이 반복되면 시스템 설정 > 개인정보 보호 및 보안에서 전체 디스크 접근 권한을 부여하거나, 볼트를 보호된 폴더 밖에 두십시오(예: ~/Notes).

이것은 Baram이 아니라 macOS가 묻는 것입니다. Baram은 열려는 폴더에 대해 자기 승인을 따로 갖고 있습니다 — 폴더를 열 때 왜 권한을 묻나요?를 보십시오.

에디터가 느립니다

큰 파일: 10,000줄이 넘는 파일은 여는 데 최대 1초가 걸릴 수 있습니다. 아주 큰 파일은 쪼개는 것을 생각해 보십시오
코드 블록이 많음: 코드 블록마다 CodeMirror 인스턴스가 돕니다. 코드 블록이 많은 문서는 메모리를 더 씁니다
수식 렌더: 복잡한 LaTeX 수식도 빠르게 렌더되지만(50ms 이내), 수식 블록이 수백 개인 문서는 스크롤 성능에 영향을 줄 수 있습니다

키보드 단축키가 동작하지 않습니다

에디터 영역에 포커스가 있는지 확인하십시오(먼저 에디터를 클릭)
macOS에서는 시스템 환경설정 > 키보드 > 단축키에서 같은 조합이 다른 동작에 배정돼 있지 않은지 확인하십시오
어떤 단축키는 상황에 따라 동작이 달라집니다 — Cmd+K는 빠른 전환을 열고, AI 인라인 편집은 텍스트를 선택했을 때 플로팅 툴바로 닿습니다

편집한 뒤 마크다운 파일이 달라 보입니다

Baram은 무손실 왕복 충실성으로 마크다운을 보존합니다. 무언가 달라 보인다면 이런 이유일 수 있습니다.

줄 끝 공백이 정규화됐다
그 파일이 Baram이 지원하지 않는 비표준 마크다운 문법을 썼다

왕복 결함이라고 생각되면 GitHub에 알려 주십시오.

위키링크가 동작하지 않습니다

워크스페이스(폴더)가 열려 있는지 확인하십시오 — 위키링크는 워크스페이스 안의 파일로 링크합니다
파일 이름은 대소문자를 구분하지 않고 맞춥니다
자동완성에 파일이 안 보이면 그 파일이 워크스페이스 폴더에 있는지 확인하십시오

로그 파일은 어디 있나요?

Baram은 돌면서 평범한 텍스트 로그를 씁니다. 버그 보고에 붙여 주시면 짐작할 일이 많이 줄어듭니다.

macOS: ~/Library/Logs/com.inel.baram/baram.log
Windows: %LOCALAPPDATA%\com.inel.baram\logs\baram.log
Linux: ~/.local/share/com.inel.baram/logs/baram.log

실행할 때마다 버전을 적은 줄이 덧붙으므로, 한 파일이 보통 여러 세션을 담습니다. 2MB에서 회전하고, 옆에 옛 파일 두 개까지 baram_<날짜>_<시각>.log 이름으로 남습니다. 시각은 UTC입니다.

로그에는 Baram 자신의 진단이 담깁니다 — 읽지 못한 파일, 불러오기를 거절한 플러그인 같은 것들입니다. API 키는 절대 쓰이지 않습니다. 다만 이름은 쓰입니다 — 파일·폴더 경로, 플러그인 id, 그리고 문서 안의 무언가를 불러오지 못했을 때 그 문서에서 가져온 텍스트(예: 깨진 이미지 경로). 그래서 로그 한 줄이 노트의 한 조각을 인용할 수 있고, 경로는 볼트가 어떻게 정리돼 있는지 드러냅니다. 공개 이슈에 올리기 전에 한번 살펴보십시오.

더 알아보려면 사용 설명서와 키보드 단축키를 보십시오.