[DokuWiki] 문서 폭을 좁게 만드는 TOC, 어떻게 할 것인가?

DokuWiki에서는 문서 안에 자동으로 TOC(table of contents, 목차)를 만들어 준다. TOC는 문서의 내용을 신속하게 파악하고 특정 위치로 빨리 이동하는 데 큰 도움을 준다.

요즘은 ChatGPT를 써서 마크다운 문서를 만든 뒤 Commonmark Plugin을 이용해 DokuWiki에 삽입하는 일이 많다. 마크다운 문서는 GitHub에 올리기 좋고, 웹브라우저에서도 쉽게 열 수 있기 때문이다. DokuWiki에서는 새 문서를 <!DOCTYPE markdown>이라는 줄로 시작한 다음, 마크다운 본문을 복사해 넣으면 된다.

그런데 이렇게 만들어진 문서에서는 TOC가 끝나고 나서야 비로소 본문이 시작된다. 그래서 위쪽에 긴 여백이 생겨 보기가 매우 좋지 않다. 왜 그럴까? Commonmark Plugin의 렌더링 방식 차이 때문이다. DokuWiki 문법으로 작성된 문서는 본문이 먼저 시작되고, TOC는 오른쪽에 float되며, 본문은 그 옆으로 자연스럽게 흐른다. 그러나 내가 사용한 Markdown wrapper div는 CSS 문제로 인해 본문이 아래로 밀려 내려가면서 공백이 크게 생기는 것이다.

다음은 너무 긴 여백이 보기 흉해서 그림을 삽입한 예이다. 하지만 TOC가 너무 길어지면 그림을 넣어도 별 소용이 없다.

글 원본 링크는 여기. ChatGPT가 당당하게 자기를 '저자'라고 표현하였다.

conf/userstyle.css에서 TOC가 나오지 않게 하면 어떨까? 하지만 이 방법은 위키 사이트 안의 모든 문서에서 TOC가 표시되지 않게 만들기 때문에 바람직한 해결책이 아니다. TOC를 표시하지 않을 문서를 일일이 CSS에 나열하거나, 네임스페이스 단위로 따로 설정할 수도 있겠지만, 그것 역시 번거로운 일이다.

문서마다 개별적으로 자동 TOC를 나오게 하거나 혹은 나오지 않게 하면 가장 좋겠지만, 즉 문서 상단에 위키 매크로인 ~~NOTOC~~를 삽입하면 좋겠지만, 현재 내가 쓰는 플러그인에서는 이것도 잘 먹지 않는다.

DokuWiki 안에서 Markdown을 쓰는 순간 위키 기능의 절반을 잃는다!

적어도 구조화된 기술 문서를 위키 안에서 안정적으로 운영하려면, Markdown보다는 처음부터 DokuWiki 문법으로 작성하는 편이 낫겠다. GitHub와의 호환성은 조금 아쉽더라도, 위키 본연의 기능을 온전히 살리는 쪽이 더 중요해 보인다.

오늘 이 문제를 해결해 보고자 ChatGPT와 더불어 여러 시도를 해 보았으나, 결국은 ‘futile cycle’만 돌고 말았다. 인공지능에 약간 실망하게 된 하루였다.

2026년 3월 15일 업데이트

위키문서에 삽입한 마크다운 문서의 본문이 갑자기 TOC와 서로 조화를 이루기 시작하였다(사례). 특별히 건드린 것이 없는데 왜 그런지 모르겠다.