Markdown TOC Generator

  1. 들어가며
  2. Markdown TOC Generator
    1. 장점
    2. 단점
    3. 필요사항
    4. 사용법
  3. 맺음말

들어가며

마크다운 문서의 목차를 만드는 것에 관심이 생기고 검색하다가 도움을 받고자 ADN에 질문을 올렸다. 친절하게도, ADN에서 내가 팔로우하고 있는 jmjeong님께서 마크다운 문서의 목차를 만드는 프로그램을 만들어서 배포하셨다. 터미널 명령어도 전혀 모르고 기본적인 프로그래밍 개념도 없는 내가 질문을 많이 했는데도 친절하게 설명해주셨다. 프로그램이 작동하는 원리는 모르지만, 나처럼 프로그래밍을 모르는 사람도 유용하게 사용하면 좋겠다는 생각이 들어 소개 글을 작성한다.

Markdown TOC Generator

장점

  • 특정 앱이 필요 없음: toc.py 파일 하나만 내려받으면 사용할 수 있다.
  • Depth 지정 옵션: 목차에 포함할 Heading의 Depth를 지정할 수 있다.
  • 목차 형태 지정 옵션: 목차의 항목에 말머리 형태를 다양한 조합으로 선택할 수 있다.
  • 들여쓰기 지정 옵션: 목차의 하위 항목에 들여쓰기(Indent)를 얼마나 할지 설정할 수 있다.
  • 결과물을 터미널에서 바로 확인 가능: 생성된 목차를 바로 확인할 수 있다.
  • 클립보드에 복사 옵션: 목차를 만들고 클립보드에 저장까지 한 번에 할 수 있다.

단점

  • 커맨드 라인 인터페이스(Command-line interface, CLI)에 익숙하지 않은 사람에게는 생소할 수 있다.

필요사항

사용법

예를 들어 순서대로 설명하겠다. “~/User/Username/Notes”라는 폴더에 “mtest.md”라는 마크다운 문서가 있는 경우 “mtest.md” 문서의 목차를 생성하는 상황을 가정한다.

  1. toc.py 파일을 내려받는다.
  2. 내려받은 toc.py 파일을 “~/User/Username/Notes” 폴더에 넣는다.
  3. 터미널을 실행하여 cd Notes 명령어를 입력한다.
    • toc.py 파일과 마크다운 문서가 위치한 폴더로 이동하는 것이다.
  4. python toc.py mtest.md 명령어를 입력한다.
    • 이 명령어가 toc.py 파일을 통해 원하는 문서의 목차를 생성한다.

위의 순서대로 진행하면 터미널 화면에 생성된 목차가 초기 설정 값대로 출력된다. 옵션으로 설정 값을 변경할 수 있으며 초기 설정 값은 다음과 같다.

  • Depth(옵션 -d) = 2: ##로 입력한 Heading 2부터 하위 Heading을 목차의 항목으로 가져온다. python toc.py -d 3 mtest.md라고 명령하면 ###로 입력한 Heading 3부터 하위 Heading을 목차의 항목으로 가져온다.
  • 들여쓰기(옵션 -i) = 4: 항목이 하위 레벨로 내려갈수록 스페이스 4번의 공백으로 들여쓰기가 된다. python toc.py -i 2 mtest.md라고 입력하면 스페이스 2번의 공백으로 들여쓰기가 된다.
  • 클립보드로 복사(옵션 -c): 기본적으로는 클립보드로 복사하지 않고 터미널 화면에만 목차를 출력한다. python toc.py -c mtest.md라고 명령하면 생성된 목차를 클립보드로 복사한다.
  • 말머리 기호(옵션 -f) = DD: Heading 2,3은 숫자”1. “로, 그보다 하위 항목의 말머리 기호는 순서 없는 목록을 사용할 때 쓰이는 “* “가 기본으로 설정되어 있다. 선택할 수 있는 말머리 기호 옵션에는 “D:1., d:1.1., *:*, a:a., A:A., H:가. , h:ㄱ.” 이 있다. 각 옵션별 설정 값의 조합에 따라 다양한 형태의 목차를 얻을 수 있다.

맺음말

초기 버전에서는 설정할 수 있는 옵션이 적어서 내가 원하는 형태로 목차가 생성되지 않았다. 그래서 Keyboard Maestro Macro로 목차를 만들어서 삽입했는데, 지금 버전은 충분히 내가 원하는 형태의 목차를 만들 수 있다.

나는 다른 옵션은 초기 설정값이 딱 원하는 결과물이어서 목차를 바로 클립보드로 저장하는 옵션만 추가하여 사용한다. 마크다운 문서를 열어 원하는 위치에 붙여넣으면 된다. 나는 글과 목차를 구분하기 원해서 위아래로 구분선을 넣는다. 이렇게 하면 내가 원하는 목차를 마크다운 문서에 넣을 수 있다.

좋은 프로그램을 만들어 주신 jmjeong님께 감사하다는 말로 이번 글을 마무리한다. 정말 고맙습니다. :)

  1. 이 글을 처음 작성하는 현재 1.5 버전이다. 페이지 오른쪽에 구름 모양 아이콘과 함께 “Download Gist”라고 적혀 있는 버튼을 눌러서 내려받을 수 있다. 압축을 해제하면 복잡한 이름의 폴더 안에 toc.py 파일이 있다.


이 글은 2014-10-30에 작성되었습니다.