무작정 Markdown 으로 문서 사이트를 만들고 싶은 이들에게...

나 말하는 거였다. 하지만 너도 아마 갈망할 것이다.
맞다. Jekyll 이나 뭐 Hugo, Vuepress... 이것저것 정적 사이트 생성 모듈은 여러모로 웹 문서화의 편리함을 제공하고 있다.
아예 클라우드나 솔루션으로 제공하는 Read the docs, Bitbook 등이 대기업의 신뢰를 듬뿍 얻어가며 서비스하고 있다.

근데 jekyll 같은 건 많이 쓰던데, Gitbook 같은 거 한국에 생각보다 잘 안쓰더라.

그건 그렇고, Markdown 을 바로 출판해서 보여주고 싶다. 게다가 대외비 자료도 포함되어 셀프 서비스를 해야 한다.
이럴 때엔 어떻게 대응해야 할지 찾아보았고, 나는 2개의 훌륭한 모듈을 찾았다.
Markdown 파일만 올리면 바로 서비스 가능한 2개의 모듈, 지금 Araboja!

Retype

Retype

일단 미리 말해두자면, 오픈소스가 아니라 상용이다.
하지만 다행인 건, 무료이다. 게다가 기업 사용도 무료이다.
조건이 있다면, 재배포 금지다. 재배포할 거면 라이선스를 취득해야 한다.
근데 그에 대한 정보가 없다. 라이선스 코드 떡하니 요구하면서.
구매할 수 없는 반디집 이런 느낌일 거다.

어쨌든, Retype 다. 이녀석의 사용법은 간단하다.

1. npm install retypeapp --global 명령어로 명령어 셋 설치
2. 원하는 빈 폴더에 retype init 으로 프로젝트 초기화
3. markdown 문서를 작성하고 폴더 구조로 맞추기
4. retype watch 명령어로 문서화된 사이트 미리보기
5. markdown 문서를 수정하고 실시간으로 문서화된 사이트에 반영하는 모습 확인
6. retype build 명령어로 사이트 빌드
7. retype run 명령어로 사이트 최종 확인
8. 빌드한 결과물인 .retype 폴더 내용물을 Github Page 및 내부 정적 웹 서버에 업로드 후 결과 확인

실시간 미리보기가 매우 훌륭하며, 디자인도 미려하고, 라이트 및 다크 테마를 훌륭하게 지원한다.

장점

• 미려한 디자인과 라이트/다크모드의 훌륭한 지원
• .md 파일만 딸랑 올려도 될 정도의 쉬운 문서 관리
• yml 방식의 직관적인 설정과 문서 제공
• 상업적으로도 무료 (그냥 반디집 생각하면 된다)
• 검색 기능, 수학식, 다이어그램(mermaid.js) 기본 지원.
• 파일만 만들어도 메뉴가 자동으로 만들어지며, 문서 내 옵션으로 설정 가능

단점

• 클로즈드 소스 (다시한번 말할게. 반디집 알지?)
• CSS 등의 커스터마이징 불가 (이는 1.12.0 2.0.0 목표로 작업 중)
• 다국어 미지원 (이로 인해 한국어 검색이 불안정) (언제 목표인지 모름)

가장 아쉬운 점이 바로 디자인을 커스터마이징할 수 없다. 그래서 FHD 이상의 대형 화면에서는 조그맣게 보이고, 최대 넓이의 한계로 제한된 넓이의 문서를 제공할 수밖에 없다.
다행인 점은 여러 사용자가 지적한 덕분에 다음 버전에 커스터마이징 적용하고 가이드도 제공한다고 한다. 나는 왜 하필 직전 버전을 만났을까?

여하튼 이러한 단점 덕분에 영어권 문서 작성하는 문서에 특화되어 있다는 아쉬움이 남는다
하지만 걱정 마라! 내가 한국어 지원한다고 자원했다. 아직 답변이 오진 않았지만, 개발사측에서 응답이 오는 대로 전해주도록 하겠다.

아, yarn 써도 되는데, 특이사항으로는 dotnet 패키지로도 제공한다는 것이다. 대체 정체가 뭐냐 너는...

유료 버전

반디집 데자뷰다! 반디소프트는 해명하라!(?)

Docsify

Docsify

중국에서는 참 신기하게 한국에서 요구하는 비즈니스 라이브러리를 오픈소스로 귀신같이 잘 만든다. Electron처럼 전 세계적으로 성공한 사례가 있고, 국내 기준으로 리액트 점유율을 위협하는 Vue가 있다. 자바의 경우, 다른 나라는 다 느린데도 JPA 쓰는데, 한국과 중국에서는 Mybatis 를 많이 쓰다 보니 IntellJ 에 Mybatis 플러그인이 있다.
근데 전자정부는 리액트를 택했다. (물론 엄밀히 샘플만 딸랑 있지만 결정권자들의 성향을 생각하면 당해본 개발자들은 내 말 뜻을 잘 알 것이다)

어쨌든 이것도 비슷하게 Markdown 문서를 만들고 바로 올릴 수 있다. 컨트롤 타워는 index.html 파일 하나에 다 담겨 있다 보면 된다.
그래서 배포와 서비스 또한 상당히 직관적이다.

1. npm i docsify-cli -g 명령어로 명령어 셋을 설치한다.
2. docsify init ./docs 명령어로 doc 폴더에 문서 사이트를 초기화한다.
3. index.html 파일을 확인한다.
4. README.md 파일을 작성하고, 그 외에 마크다운 문서를 작성해서 올린다.
5. 각 문서 메뉴를 만들기 위하 _sidebar.md 파일을 생성한다.
6. 마크다운 형식의 목록 작성하듯이 메뉴를 작성한다. 예)

* [Home](/)
* [Guide](guide.md)

1. index.html 파일 내 window.$docsify 객체에 loadSidebar: true 속성을 추가한다. subMaxLevel: 2 속성을 추가하면 섫정한 헤더 레벨 만큼의 서브메뉴를 자동으로 생성해준다.
2. docsify serve docs 명령어로 미리본다.
3. 얘도 문서 수정하면 자동으로 새로고침하여 보여준다.
4. 확인 끝났으면, 생성한 doc 폴더의 내용을 Github Pages 및 내부 정적 웹 서버에 업로드 후 결과 확인.

장점

• 직관적인 환경과 그만큼 쉬운 배포
• 커스터마이징의 유연함
• 커버 페이지 지원
• 플러그인을 지원하며 플러그인 제작도 간편함
• 심지어 Vue 도 지원
• PWA 및 SSR도 지원
• 오픈소스

단점

• 초기화의 번거로움 (세팅해야 한다고)
• 다지인 관리의 번거로움 (라이브러리 추가해야 한다) 대신 플러그인 추가하면 단점 상쇄 가능할 정도로 더욱 쉬워진다. (CSS 변수 제공)
• 검색 기능을 제공하지만 별도로 설정해야 한다.
• 수식과 다이어그램을 지원하지만 별도로 파서를 작성해야 한다.
• 소스 보기 시 기본 몇 개 언어만 지원해서 원하면 추가해야 한다.
• Retype 와 달리 메뉴도 직접 작성해야 한다.

난 일단 이걸 골랐고 서비스 중이다. 첫번째로 커스터마이징의 유연함 (Retype는 컨텐츠 넓게 가능하긴 한데 번거로움) 때문이다. 하지만 Retype 가 다음 버전에 재대로 한 방 먹여준다면, 다시 Retype로 전환도 고려하고 있다.

자, 개발자 문서화가 쉬워진다! 난 이 두 모듈에 감사의 표시를 전한다!