DeckStitch

Markdown을 원본으로 삼아 HTML/PDF 발표자료를 만들고, 필요한 figure까지 함께 관리하는 발표자료 제작 하네스입니다.

핵심 원칙은 단순합니다. 먼저 content.md에 발표 원고를 작성하고, 사용자가 문구를 검토/수정한 뒤, 같은 원고에서 HTML과 PDF를 생성합니다. 발표자료에 들어가는 figure도 assets.yml로 명시적으로 연결해 원고, 이미지, 결과물이 따로 놀지 않게 합니다.

왜 필요한가

연구 발표자료나 기술 발표자료는 보통 다음 문제가 생깁니다.

• 원고와 슬라이드 문구가 서로 달라짐
• figure가 어디서 왔는지 추적하기 어려움
• HTML과 PDF 결과물이 다르게 보임
• 수식이 HTML/PDF에서 깨짐
• 발표자용 메모나 내부 문구가 공개 slide에 섞임
• figure 생성 prompt, 실제 데이터 plot, asset mapping이 흩어짐

DeckStitch는 이 과정을 하나의 반복 가능한 workflow로 묶습니다.

content.md
  -> figure-brief
  -> assets / plots / image-generation prompts
  -> HTML
  -> verify
  -> PDF

예시

아래 예시는 {{figure_generation_pipeline}} placeholder에서 figure prompt를 만들고, Codex가 이미지 생성 도구로 conceptual pipeline figure를 생성한 뒤 slide에 넣은 결과입니다.

실제 지표 figure는 이미지 생성으로 만들지 않고, 실제 값 기반 plot으로 제작하는 흐름을 분리합니다.

기능

• content.md 기반 Markdown-first slide 제작
• assets.yml 기반 figure mapping
• HTML 발표자료 생성
• Chrome headless 기반 PDF export
• block LaTeX를 SVG 이미지로 변환해 수식 깨짐 방지
• figure-brief로 figure 요청서 자동 생성
• conceptual figure와 data-backed figure 자동 분류
• design style guide 선택
• 1280x720 slide overflow 검사
• 이미지 누락, 금지 문구, 깨진 LaTeX 잔존 문자열 검사
• Codex agent가 그대로 따라 쓸 수 있는 AGENTS.md와 선택형 Codex skill 포함

빠른 시작

git clone https://github.com/ho323/deck-stitch.git
cd deck-stitch

python -m deckstitch init my_deck
python -m deckstitch build my_deck
python -m deckstitch verify my_deck
python -m deckstitch pdf my_deck

editable install을 하면 deckstitch 명령으로도 사용할 수 있습니다.

python -m pip install -e .
deckstitch init my_deck

Deck 구조

my_deck/
  content.md
  assets.yml
  assets/
  dist/

최소 content.md 예시:

## Slide 1. 제목

### 발표자료 제목

핵심 내용:

- 첫 번째 메시지
- 두 번째 메시지

---

## Slide 2. 결과

### Figure가 들어가는 slide

시각자료:

- `{{sample_result}}`

assets.yml 예시:

brand: "DeckStitch"
title: "My Deck"

figures:
  sample_result: "assets/sample_result.png"

Figure workflow

먼저 content.md에 필요한 figure placeholder를 적습니다.

시각자료:

- `{{gate_adapter_structure}}`
- `{{lead_time_rmse_curve}}`

그다음 figure 요청서를 생성합니다.

python -m deckstitch figure-brief my_deck

생성되는 파일:

figure_requests/
  gate_adapter_structure.md
  assets_draft.yml
figures_to_plot/
  lead_time_rmse_curve.json

분류 기준:

• 모델 구조, workflow, 실험 pipeline, before/after schematic: 이미지 생성 prompt로 처리
• RMSE, ACC, map, lead time curve, global grid, 변수별 변화: 실제 데이터와 matplotlib로 처리

Codex workflow에서는 사용자가 prompt를 직접 복사할 필요가 없습니다. Codex가 figure_requests/*.md를 읽고 이미지 생성 도구를 호출하거나, figures_to_plot/*.json을 읽고 실제 데이터 기반 plot을 만든 뒤 assets.yml까지 연결하는 방식으로 이어갑니다.

Design style

디자인 가이드는 designs/에 들어 있습니다.

python -m deckstitch styles
python -m deckstitch init my_deck --style pinterest
python -m deckstitch init my_deck --style apple
python -m deckstitch init my_deck --style stripe

현재 포함된 style:

• pinterest: warm neutral chrome, image-first discovery layout
• apple: minimal product-gallery style
• stripe: finance/infrastructure marketing style with navy, indigo, gradient mesh

선택한 style은 새 deck의 design.md로 복사됩니다. 강제 규칙이 아니라 디자인 방향을 잡기 위한 참고 자료입니다.

예제

• examples/kist_style_minimal/: 최소 동작 확인용 sample deck
• examples/generated_figure_workflow_demo/: figure prompt 생성, 이미지 생성 결과, 데이터 figure slot을 포함한 end-to-end 예제
• examples/reference_kist_atmos/: 수식, figure, 기술 설명 흐름을 포함한 연구 발표 reference

생성형 figure workflow 예제 실행:

python -m deckstitch build examples/generated_figure_workflow_demo
python -m deckstitch verify examples/generated_figure_workflow_demo

검증

python -m deckstitch verify my_deck

검사 항목:

• 이미지 누락
• 발표자용 메모나 내부 문구
• 깨진 LaTeX 잔존 문자열
• Chrome이 있을 경우 1280x720 slide overflow

Chrome이 없는 환경이나 CI에서는 정적 검사만 실행할 수 있습니다.

python -m deckstitch verify my_deck --no-browser

PDF export

python -m deckstitch pdf my_deck

PDF는 같은 HTML에서 Chrome headless로 출력합니다. 브라우저 header/footer는 비활성화합니다.

Codex skill

Codex에서 이 workflow를 반복해서 쓰려면 codex-skill/SKILL.md를 skill로 등록할 수 있습니다. 필수는 아니지만, 오픈소스 사용자에게 “Codex에게 어떤 방식으로 시키면 되는지”를 전달하는 데 유용합니다.

예시 설치 방식:

mkdir -p ~/.codex/skills/deckstitch
cp codex-skill/SKILL.md ~/.codex/skills/deckstitch/SKILL.md

프로젝트 이름

DeckStitch는 Markdown 원고, figure, 수식, design style을 하나의 검증 가능한 발표자료로 이어 붙인다는 의미입니다.

• 프로젝트명: DeckStitch
• Python package: deckstitch
• CLI: deckstitch
• 한 줄 설명: Markdown-first workflow for building verified HTML and PDF presentations

개발

테스트:

PYTHONPYCACHEPREFIX=/private/tmp/deckstitch_pycache python3 -m unittest discover -s tests -v

이 프로젝트는 Python stdlib 중심으로 작성되어 있습니다. Chrome은 PDF export와 browser overflow audit에만 필요합니다.