doc-template

옵시디언 Markdown 한 파일을 기획·리서치 문서 HTML로 만듭니다. 라이트·다크, PC·모바일, 인쇄를 지원하고, 터미널·Claude Code·Codex·Claude 앱에서 같은 도구로 씁니다.

• 표지와 띠지(결론 한 줄 + 바뀌는 것·대가·뒤집힐 조건)로 첫 화면에서 결론이 읽힙니다.

• 본문 폭은 한글 한 줄 36자 안팎(36em), 행간 1.7입니다. 절 사이에는 타공 헤어라인이 들어갑니다.

• 색은 머리말 한 줄로 고릅니다. 다이칸야마 츠타야 서점이 소개한 책 표지에서 뽑은 여섯 배색, 흑백(검정·흰색 두 색만), 한 가지 색 모드가 있습니다.

• 정하지 않은 것은 본문에 이름표로 흩지 않고 결정 모음 한 곳에 모읍니다. 옵시디언 접이 상자(> [!decide]- 질문)로 쓰면 표지 아래 「정하지 않은 것 N가지 · 모아 보기」 줄과, 관련 절 머리의 「정할 것 N」 표시가 자동으로 붙습니다.

• 머리의 문서 번호와 메타의 상위 문서에 적은 티켓 번호(CCO-121 등)는 머리말 jira: 주소로 자동 링크됩니다.

• 유형이 넷입니다. 위에서 아래로 읽는 기획(plan)·리서치(research), 기간을 훑고 날짜로 찾아가는 일정표(schedule) — 국면 카드·고정 2주 달력(오늘 표시)·운영 흐름과 부스팅 두 열·서랍 레이어, 조건으로 걸러 찾는 목록(catalog) — 상단에 고정되는 필터 줄·검색·건수·핵심 열만·그룹 접기. doc-template starter schedule처럼 뼈대를 받아 씁니다.

• 구조 점검이 들어 있습니다. 결론을 맨 위에, 소제목은 결론 문장으로, 한 문서 한 독자 같은 원칙(가이드)을 review가 점수와 고칠 점으로 알려 줍니다.

설치

uv가 필요합니다. 없으면 먼저 설치합니다.

curl -LsSf https://astral.sh/uv/install.sh | sh     # 또는 brew install uv
uv tool install git+https://github.com/euna-source/doc-template

doc-template(터미널 명령)과 doc-template-mcp(MCP 서버) 두 명령이 생깁니다. 업데이트는 uv tool upgrade doc-template 한 줄입니다.

Claude Code

claude mcp add doc-template -s user -- doc-template-mcp

Codex

codex mcp add doc-template -- doc-template-mcp

Claude 앱(데스크톱)

설정 → 개발자 → 설정 편집에서 claude_desktop_config.json에 아래를 넣고 앱을 다시 켭니다. command에는 which doc-template-mcp로 나온 전체 경로를 씁니다.

{
  "mcpServers": {
    "doc-template": { "command": "/Users/<이름>/.local/bin/doc-template-mcp" }
  }
}

Related MCP server: Little Red Book Card MCP

쓰는 법

AI에게는 이렇게 말하면 됩니다. "doc-template으로 이 내용을 기획 문서로 만들어 줘. 테마는 t1." MCP 도구 순서는 get_guide → get_starter → review_document → render_document입니다.

터미널에서는 이렇습니다.

doc-template starter plan -o 기획.md       # 시작 문서
doc-template render 기획.md                 # 기획.html 생성
doc-template render 기획.md --theme mono    # 흑백으로
doc-template review 기획.md                  # 구조 점검(점수·고칠 점)
doc-template guide                           # 구조 원칙
doc-template themes                          # 테마 목록

테마

모든 테마는 라이트·다크 양쪽에서 글자 대비 4.5:1 이상을 검사합니다.

Markdown 문법 (옵시디언 그대로)

전체 예시는 doc-template starter plan과 examples/sample-research.md에 있습니다.

문서 템플릿 모음 유형(kinds)

문서 템플릿 모음의 여섯 유형은 doc_template.kinds가 그립니다: prd(기획서형 개발요건정의서) · research · catalog(목록형) · schedule(일정표형) · minutes(회의록형) · pt(발표형). 위의 plan(기획안)과 prd는 다른 문서입니다.

doc-template kinds render minutes 회의록.md -o 회의록.html --theme mono
echo '{"fn":"render","args":["# 제목\n","pt"]}' | doc-template kinds call   # 다른 파이썬에서 부를 때(JSON 입출력)

부품(모듈) — 아무 페이지에나 붙이기

템플릿은 부품을 조립한 것이다. 부품은 src/doc_template/modules/<id>/에 폴더 하나(module.json·style.css·script.js)로 있고, 새 부품도 폴더 하나만 더하면 된다.

doc-template kit list
doc-template kit apply 페이지.html -o 페이지-kit.html --with look,toggle,history --data history=기록.json
doc-template kit remove 페이지-kit.html -o 원본.html        # 떼면 원본과 바이트까지 같다

이미 있는 페이지의 구조는 건드리지 않는다. 붙인 자리는 <!--dk:start id-->…<!--dk:end id-->로 감싸고, 다시 붙이면 바꿔 끼운다. MCP 도구는 list_modules·apply_modules·remove_modules.

공개 배포(선택)

GitHub Pages가 켜진 저장소를 DOC_TEMPLATE_PAGES_REPO=owner/repo로 지정하면 doc-template publish 기획.html 기획-slug로 올리고 공개 URL을 받습니다. gh 로그인이 필요합니다. doc-template이 만든 HTML만 올라가고, 같은 저장소에 동시에 올리면 차례로 처리합니다. 회사 내부 문서는 공개 저장소에 올리지 마세요.

검사

uv run --with-editable . --with playwright python tests/verify_render.py   # 11테마 × 4폭 × 2모드
uv run --with-editable . python tests/test_safety.py                       # 주입·경로·덮어쓰기
uv run --with-editable . python tests/mcp_smoke.py                         # MCP 도구 호출
uv run --with-editable . python tests/test_kinds.py                        # 모음 유형 렌더·호출
uv run --with-editable . --with playwright python tests/verify_tables.py 페이지.html …   # 표 깨짐(넘침·잘림·선 끊김) 320~1440px × chrome·webkit
uv run --with-editable . python tests/test_publish_assets.py               # 배포 때 그림·도식 함께 올리기
uv run --with-editable . python tests/test_ko_style.py                     # 한국어 문체 점검
uv run --with-editable . python tests/test_kit.py                          # 부품 붙이기·떼기
uv run --with-editable . --with playwright python tests/verify_kit.py      # 부품 브라우저 확인