· 톺아보기

[소개] 소소하게 Markdown(.md) 에디터/뷰어를 만들었습니다

데이스타777 · · 수정

조회 2,543 · 공감 6 · 댓글 9

AI작업 많이 하다보니까. 마크다운(.md) 파일이 자꾸 쌓이더라구요.그래서 TUI로에디터 만들어서 쓸만한 거 같아 공유드립니다. (오늘은 터미널 버전만 공유드리고, 다음에는 데스크톱에디터 버전으로 맥/윈도우/리눅스용 UI버전 공유할께요. 이건 아직 좀 더 개발해야해서)


Markdown 파일을 자주 열어보거나, README/메모를 터미널에서 관리하시는 분들께 소개해봅니다. (MIT 라이센스입니다. 무료고 수정해서 쓰셔도 됩니다)


제가 만든 `mdok-cli`는 `.md` 파일을 터미널에서 읽고, 편집하고, 바로 미리볼 수 있는 작은 TUI 에디터입니다. (마우스로 버튼클릭이나 스크롤 등이 됩니다)

이름은 Markdown OK의 줄임말입니다.


이런 식으로 씁니다 (노드랑 npm이 있어야해요)


npm install -g @daystar7777/mdok


mdok README.md       # 파일 열기

mdok                 # 마지막 세션 이어서 열기

mdok view README.md  # 터미널용 예쁜 출력



실행하면 왼쪽에는 파일/목차가 나오고,(mdok 좌측의 화살표를 누르면 나옵니다) 가운데 화면은 분할 편집·소스 편집·읽기 보기로 전환할 수 있습니다. 탭을 여러 개 열어둘 수도 있고, 종료 후 다시 실행하면 열린 탭과 커서 위치도 복원합니다.




분할 화면에서는 Markdown을 고치면서 오른쪽 미리보기가 바로 따라옵니다.


mdok-real-current.jpg



소스만 넓게 보고 편집할 수도 있습니다.

mdok-real-source.jpg




읽기만 할 때는 Markdown 렌더링 결과만 깔끔하게 볼 수 있습니다.

mdok-real-viewer.jpg




## 왼쪽 사이드바

mdok-real-sidebar.jpg



화면 왼쪽 위의 `<` 버튼(터미널 폭에 따라 `[>]`로 보일 수 있음)을 누르면 사이드바가 열립니다. 여기에 최근에 열었던 파일, 현재 문서의 목차, 작업 폴더 안의 Markdown 파일 목록이 나옵니다.


파일을 여러 개 오갈 때나 긴 문서에서 목차를 눌러 이동할 때 쓰는 영역이고, 본문을 넓게 보고 싶을 때는 같은 버튼으로 다시 접을 수 있습니다. 키보드로는 `Ctrl+O` 다음 `b`를 누르면 됩니다.


## 기존 Markdown 도구와 조금 다른 점


Markdown을 편집할 때 미리보려고 브라우저를 따로 열거나, 문서를 다른 서비스에 붙여넣는 과정이 번거로워서 만들기 시작했습니다.


- 소스 편집과 실시간 미리보기

- 한국어/영어 UI, 한글·한자·이모지 폭 처리

- 탭, 최근 파일, 목차 사이드바, 세션 복원

- 찾기/바꾸기, Markdown 린트, 표 정리, HTML 내보내기

- 테마 5종과 줄번호, 기본 Vim 모드

- 저장 시 원자적 기록, Git 저장소에서는 자동 커밋/푸시/풀 보조


특히 터미널에서 한글이 들어간 문서를 편집할 때 커서가 한 칸씩 밀리는 일이 꽤 거슬렸는데, 표시 폭 기준으로 계산하도록 따로 처리했습니다.


## 읽기만 할 때는 더 단순하게


TUI를 띄우지 않고 Markdown을 터미널에서 보기 좋게 렌더링하는 `view` 명령도 넣었습니다.



mdok view README.md | less



파이프에 연결해서 쓰거나, SSH로 접속한 서버에서 README나 작업 메모를 확인할 때 편합니다.


## AI 기능은 BYOK 방식입니다


API 키를 프로그램에 넣어둔 방식이 아니라, 본인이 가진 API 키를 환경변수로 넣는 방식입니다.


export MDOK_API_KEY=sk-...

mdok ask README.md -q "이 문서 3줄로 요약해줘"



TUI 안에서도 열린 문서에 질문하거나 선택 영역을 AI로 고쳐쓰고, 변경 전후 diff를 확인한 뒤 적용할 수 있습니다. OpenAI 호환 API 주소와 모델을 설정할 수 있어서, 다른 호환 엔드포인트나 로컬 서버에도 연결할 수 있습니다.


다만 AI 기능은 문서가 외부 API로 전송되는 기능인 만큼, 민감한 문서에는 주의가 필요합니다. 앱에서 공용 키를 제공하는 방식은 아니고, 사용자가 직접 키와 전송 대상을 선택합니다.


## Git과 QR


Git 저장소 안에서 사용하면 저장 후 자동 커밋을 만들고, 별도 패널에서 push/pull/수동 commit을 할 수 있습니다. Git을 원하지 않으면 끌 수 있습니다.



- GitHub: https://github.com/daystar7777/mdok-cli

- npm: https://www.npmjs.com/package/@daystar7777/mdok


Node.js 22 이상이 필요합니다. MIT 라이선스이고, 아직 0.x대라 기능이나 UI는 계속 다듬고 있습니다.


터미널에서 Markdown을 많이 보시는 분들이라면 한 번 써보시고, 특히 키 조작이나 미리보기 쪽에서 불편한 점을 알려주시면 다음 버전에 반영해보겠습니다.





댓글 9

  1. 깨끗이 ·
    저도 가끔 markdown으로 문서 작업하는 경우가 있는데 알아보니 md 형식도 앱에 따라서 조금씩 달라서 호환이 안 되기도 하는 것 같아요. pandoc, vscode, 등등. 특히 표나 latex 지원에서 달라지는 듯 한데, latex 지원도 하시나요? 뭔가 호환 문제에서 여러 가지 버전을 지원하는 것 또는 어떤 형식을 지원하는지 명확하게 명시하는 것도 좋을 것 같습니다. 근데 TUI에서 하면 latex는 조금 한계가 있을 것 같긴 하네요.
  2. 데이스타777 ·
    @깨끗이님 아 좋은 조언 감사합니다. 최대한 해보는 방법을 찾아보겠습니다.

    현재 공개 버전은 기본 Markdown과 GFM 스타일 표를 중심으로 지원합니다. LaTeX 수식은 소스로 작성·보존할 수 있지만, TUI 안에서 조판된 수식으로 보여주는 기능은 아직 지원하지 않습니다.
    지원 범위와 제한을 명확히 문서화하고 있으며, 개발 버전에는 Markdown 형식을 선택하는 Pandoc 내보내기와 VS Code 연결을 추가했습니다. 수식은 HTML·LaTeX·PDF 출력으로 연결하는 방향입니다. 다만 모든 앱과 완전 호환된다고 약속하기보다는, 실제 변환 결과를 검증하며 지원 범위를 넓히려고 합니다. 문제가 되는 표나 수식 예시를 주시면 테스트에 반영하겠습니다.
  3. 깨끗이 ·
    @데이스타777님 네... 확인되면 보내드릴께요. 한 가지 제가 필요했던 기능과 아이디어를 드리자면, latex의 경우에는 문법 highlight하는 기능과 인식되는 명령과 그렇지 않은 명령 구분하는 기능이 있으면 좋을 것 같습니다(예를 들어 깨진 latex 안에 있으면 오류라고 status bar에 표시하거나... latex을 빨간색으로 하거나... 그런데 생각해보니 프로그램에 따라 $$-$$, \[, \] 표시도 한 쪽만 지원해서 find-replace로 바꿔 줬던 기억이 있네요). latex은 mathjax 등 엔진에 따라 지원되는 패키지 등이 다르다고 들었습니다. 그리고 제가 필요해서 한번 구현해봐 하다가 말은 것은 git diff 또는 diff를 md syntax 고려하면서 보여주는 기능인데 이 기능이 있으면 md 파일 서로 비교할 때 매우 편할 것 같습니다. 비슷한 기능을 하는 프로그램이 몇 개 있었던 것 같은데, latex 포함 모두를 비교하는 기능은 제공하지 않았던 것으로 기억합니다.
  4. 데이스타777 ·
    @깨끗이님 자세한 제안 감사합니다. 말씀해 주신 내용을 바탕으로 이번 0.1.7에 관련 기능을 추가했습니다.
    LaTeX 수식은 소스에서 문법을 강조하고, 구분자·중괄호 오류와 선택한 KaTeX/MathJax 엔진에서의 호환성 문제를 구분해 표시하도록 했습니다. 상태 표시줄과 진단 목록에서 확인할 수 있습니다. 다만 모든 LaTeX 명령·패키지를 판단할 수는 없어, 검사하지 못한 항목은 오류로 단정하지 않고 별도로 안내합니다.
    $…$ ↔ \(…\), $$…$$ ↔ \[…\] 변환도 추가했습니다. 코드 영역은 제외하고, 변경 내용을 미리 확인한 뒤 적용하거나 되돌릴 수 있습니다.
    문서 비교는 Markdown 블록·표 셀·수식 토큰의 변경을 살펴볼 수 있도록 했으며, 두 파일 비교와 Git의 staged/unstaged 비교를 지원합니다. 원문 diff도 함께 확인할 수 있습니다. 다만 수학적으로 같은 식인지 판단하는 기능이나 모든 Markdown 확장 문법과의 완전한 호환까지 지원하는 것은 아닙니다.
    TUI에서 Ctrl+O → M은 수식 도구, Ctrl+O → D는 비교 기능입니다. 실제로 사용하셨던 문서나 문제가 되는 수식 예시를 보내주시면, 해당 사례도 테스트에 반영하겠습니다. 구체적인 사용 경험을 알려주셔서 감사합니다.
  5. metermatters ·
    저도 읽는건 glow로 편집은 nano로 하다가, 편집기를 만들어볼까 했는데 결국 번거로운 건 브라우징이라는 생각이 들어서 찾아보다 mc로 정착했습니다. DOS시절 ncd랑 비슷해서 왠지 익숙하기도 하고, 편집화면으로도 엔터 한 번으로 바로 들어갈 수 있어서 편한 것 같습니다.
  6. 데이스타777 ·
    @metermatters님 좋은 힌트 주셔서 감사합니다. 기본을 뷰어로 바꾸고 엔터치면 에디팅 가능하게 바꾸어서 패치했습니다.

    npm install -g @daystar7777/mdok@latest
    mdok --version
    으로 설치 가능합니다
  7. 깨끗이 ·
    사실 md로 작업 중이어서 몇 가지 제안을 더 해 봅니다. 저는 현재는 meld + obsidian으로 meld로 원고 비교해서 바로 작업하거나, obsidian에서 작업(주로 수식)하는데, obsidian은 작업하면 바로바로 저장이 되는데 meld는 obsidian에서 저장된 내용이 update가 되지 않아서 나중에 meld에서 작업해서 저장하려면 disk의 내용이 변경되었다고 뜹니다. 그런데 여기서 저장하면 obsidian에서 작업한 내용은 모두 날라가죠. meld에서 저장하지 않은 내용도 obsidian에 바로 업데이트가 되지 않기도 하고요. 부가적인 내용일 수도 있지만 disk 상의 변경이 바로 update이 되는지 아니면 open했을 때의 내용을 그대로 유지하는지 설정할 수 있으면 좋을 것 같습니다(auto-save 기능도 on/off 할 수 있으면 좋고요.). kate 같은 프로그램은 disk에서 update가 감지되면 변경 사항 update할 것인지 묻습니다.
  8. 깨끗이 ·
    하나 더 있는데, meld의 경우 동일한 파일을 두 군데에서 열면 meld가 완전히 죽어버리는 현상이 있습니다(우분투). 아직 사용해보지 않아서 mdok는 어떤지 모르겠지만, 혹시라고 그런 경우에는 프로그램이 아예 열리지 않거나 해서 시스템이 다운되는 현상은 방지해야 하지 않나 생각합니다.
  9. 데이스타777 · · 공감 1
    @깨끗이님 넵 고려해서 문제 대응할 수 있도록 수정해볼께요. 위의 댓글도 마찬가지로요

모두의공원 최근 글

모두의공원 목록 더 보기