안녕하세요.
로컬 Markdown 문서를 자주 확인하다 보니, 브라우저에서 폴더를 탐색하면서 여러 문서를 편하게 읽을 수 있으면 좋겠다는 생각으로 Markdown Leader라는 Chrome 확장 프로그램을 만들었습니다.
현재 Chrome 웹 스토어에는 1.0.0이 공개되어 있습니다.
주요 기능은 다음과 같습니다.
• 폴더 안의 Markdown 문서 탐색
• 여러 문서를 탭으로 열고 순서 변경·고정
• 문서 검색과 자동 목차
• 코드 구문 강조, 표, 수식, Mermaid 다이어그램
• 즐겨찾기와 최근 파일·폴더
• 원본 Markdown의 체크박스 상태 변경
• 선택한 문구에 검토 메모 추가·수정·삭제
처음에는 읽기 전용 뷰어로 시작했는데, 실제로 사용하다 보니 문서를 읽으면서 체크박스를 처리하거나 검토 내용을 원본과 함께 보관하고 싶었습니다.
그래서 일반적인 문서 읽기는 원본을 건드리지 않고, 사용자가 체크박스를 클릭하거나 메모 저장을 요청한 경우에만 쓰기 권한을 확인한 뒤 원본 파일을 갱신하도록 만들었습니다.
메모는 별도 서버가 아니라 Markdown 파일 끝의 HTML 주석에 저장됩니다. 파일을 다른 사람에게 전달하면 메모도 함께 이동하기 때문에 이 점은 제품 화면에서도 안내하고 있습니다.
파일이 외부 편집기에서 바뀐 경우에는 덮어쓰지 않도록 저장을 중단하고 충돌을 알립니다. 로컬 파일과 폴더를 다루다 보니 Chrome의 파일 접근 권한, 지속되는 파일 핸들, 외부 변경 감지 같은 부분이 생각보다 손이 많이 갔습니다.
오늘은 후속 버전인 1.1.0도 Chrome 웹 스토어 심사에 제출했습니다.
1.1.0에는 다음 기능을 추가했습니다.
• 이름·수정일 기준 파일 정렬
• 파일 탐색기 폭 조절과 설정 저장
• A4 페이지 미리보기와 Chrome PDF 저장
• 이동되거나 삭제된 파일·폴더 다시 연결
• 연결 오류가 발생해도 마지막으로 읽은 본문 유지
현재 설치되는 공개 버전은 1.0.0이고, 1.1.0은 심사 대기 중입니다. 승인이 끝나면 자동으로 업데이트됩니다.
별도의 계정이나 서버는 없습니다. Markdown 문서와 메모를 개발자 서버로 전송하지 않으며 광고·제품 내부 분석·AI 연동도 없습니다.
Chrome 웹 스토어
https://chromewebstore.google.com/detail/markdown-leader/mglmfpabbmcifhimdlembgchpaofbogm
소스 코드
https://github.com/bohe76/markdown-leader
로컬 Markdown을 많이 다루시는 분들이 계시면 사용해 보시고 의견 부탁드립니다. 파일 접근이나 문서 검토 흐름에서 불편한 부분도 알려주시면 다음 버전에 반영해 보겠습니다.
아래 이미지는 현재 심사 중인 1.1.0 화면입니다.
1.1.0 심사 제출 화면: 파일 정렬과 탐색기 폭 조절
1.1.0 심사 제출 화면: A4 미리보기와 PDF 저장 안내
체크박스와 검토 메모
Mermaid 다이어그램과 수식
1.1.0 심사 제출 화면: 파일 연결 복구
먼저 쓰기입니다. createWritable() 의 keepExistingData 기본값이 false 이고, 규격 설명은 true 일 때만 기존 파일을 임시 파일로 먼저 복사하고 아니면 임시 파일이 빈 채로 시작한다고 돼 있습니다. 그래서 체크박스 한 칸 바꾸려고 그 위치만 부분 쓰기하고 close 하면 앞뒤가 통째로 날아갑니다. 본문 전체를 다시 쓰고 계신지, 아니면 옵션을 켜고 여시는지 궁금합니다.
같은 절에 스트림을 닫을 때 임시 파일로 원본을 교체하는 식으로 구현된다고 적혀 있습니다. 저장할 때마다 파일이 바뀌어 끼워지는 셈이라, 외부 편집기가 그 파일을 열어두고 감시 중이면 수정이 아니라 삭제 후 생성으로 잡힐 수 있습니다. 외부 변경 감지를 어떤 값으로 잡으시는지가 이 지점과 같이 걸립니다.
다음은 권한입니다. 핸들은 직렬화가 되니 IndexedDB 에 넣어 다음 실행에 다시 꺼낼 수 있지만 권한은 같이 살아남지 않습니다. 해당 출처의 탭이 전부 닫히면 접근을 잃고 다음 방문 때 다시 물어본다고 돼 있고, 그래서 queryPermission 으로 먼저 확인하고 없으면 requestPermission 을 부르라고 안내합니다. 이 요청은 사용자 제스처 안에서만 뜹니다. 1.1.0 의 파일 다시 연결이 자동 복구처럼 보이더라도 첫 클릭 한 번은 반드시 필요한 구조일 텐데, 그 클릭을 어느 화면에 두셨는지 궁금합니다.
마지막은 메모입니다. 파일 끝 HTML 주석에 넣으신다고 하셨는데, CommonMark 에서 그 블록의 종료 조건이 --> 를 포함한 줄입니다. 메모 본문에 그 문자열이 들어가면 거기서 주석이 끝나고 뒤가 본문으로 샙니다. 저장할 때 치환해 두시는지요.
먼저 createWritable()의 keepExistingData 기본값이 false라는 말씀은 맞습니다.
이 상태에서 특정 위치만 부분적으로 쓰면 기록하지 않은 앞뒤내용이 보존되지 않을 수 있습니다.
다만 저희는 체크박스 위치만 스트림에 부분 기록하지 않고, 변경된 전체 Markdown 문서를 UTF-8로 다시 기록한 뒤 close()하고 있습니다. BOM과 CRLF를 포함한 원본 형식 보존도 실제 파일 저장 과정에서 확인하고 있습니다.
따라서 현재 방식에서는 기본값으로 인한 본문 유실이 발생하지 않습니다. 관련 동작은 File System Standard의 createWritable() 규격과도 일치합니다.
임시 파일 교체 부분도 중요한 지적입니다.
규격에서는 변경 내용을 임시 파일에 기록한 뒤 스트림을 닫을 때 원본을 교체하는 방식을 일반적인 구현 예로 설명하고 있습니다.
따라서 외부 편집기나 파일 감시 도구에 따라 단순 수정이 아니라 교체·이동·재생성 계열 이벤트로 관찰될 가능성이 있습니다.
다만 이벤트 형태는 표준에서 보장하지 않고 운영체제와 편집기 구현에 따라 달라집니다.
저희는 외부 변경 판단에 파일 이벤트 종류나 수정 시각만 사용하지 않고, 저장 직전 실제 파일 내용을 다시 읽어 마지막으로 확인한 원문과 비교합니다. 내용이 달라졌다면 저장을 중단하고 충돌로 처리합니다.
다만 마지막 비교와 close() 사이에 발생하는 외부 저장까지 원자적으로 차단할 수 있는 API는 없으므로, 이 부분은 현재 웹 파일 API의 한계로 보고 있습니다.
권한 부분도 말씀하신 흐름으로 처리하고 있습니다.
파일 핸들은 IndexedDB에 보관할 수 있지만, 다시 사용할 때는 queryPermission()으로 현재 권한을 확인하고 필요한 경우 사용자 동작 안에서 requestPermission()을 호출합니다.
최근 항목이나 즐겨찾기 열기, 저장, 다시 연결 동작이 그 진입점입니다.
한편 Chrome 122부터는 사용자가 지속 권한을 허용한 환경에서 권한이 다음 방문에도 유지될 수 있으므로, 모든 경우에 반드시 다시 묻는 것은 아닙니다.
어느 경우든 저장된 상태를 신뢰하지 않고 실제 권한 조회 결과를 기준으로 처리하고 있습니다.
관련 내용은 Chrome의 파일 핸들·권한 안내와 지속 권한 안내에서 확인할 수 있습니다.
마지막으로 HTML 주석 종료 조건에 대한 지적도 정확합니다.
CommonMark에서는 <!--로 시작한 HTML 블록이 -->를 포함한 줄에서 종료됩니다.
이에 따라 검토 메모를 그대로 삽입하지 않고 JSON으로 직렬화한 뒤 <, >, &를 유니코드 이스케이프합니다.
예를 들어 메모 안의 -->는 실제 파일에서 --\u003e 형태로 저장되고, 읽을 때 원래 문자열로 복원됩니다. -->와 HTML 문자열이 포함된 메모의 저장·재열기 테스트도 함께 확인했습니다.
기준은 CommonMark의 HTML block 규칙입니다.
중요한 경계 조건을 세심하게 짚어주신 덕분에 저장·권한·외부 편집기 호환성 동작을 다시 확인할 수 있었습니다. 좋은 피드백을 주셔서 감사합니다.