문서는 세 갈래다

/docs 아래에 셋이 나란히 있다. 읽는 사람이 다르므로 글을 어디에 쓸지가 먼저다.

가늠이 서지 않을 때의 기준은 하나다 — 화면을 보고 있는 사람에게 필요한 말이면 플레이북, 코드를 열 사람에게 필요한 말이면 위키. 왜 이 방향인지에 대한 설명은 연구다.

앞의 둘은 build_docs.py 가 만들고 위키는 build_wiki.py 가 만든다. 위키만 다국어가 없고, 얼굴(static/css/wiki.css)이 다르고, 게이트(static/js/wiki-gate.js, admin 클레임)가 걸린다. 아래 규칙은 앞의 둘 — 플레이북·연구 — 이야기다.

연구 원고 작성

연구 원고는 지정된 개발용 저작 도구에서 근거 문헌과 함께 작성한 뒤 마크다운을 docs/research/로 옮긴다. 도구별 규약은 저장소의 docs/archive/research-authoring-development.md에 보존한다.

어디에 무엇이 있나

콘텐츠는 전부 docs/ 아래의 마크다운이고, 코드는 생성기 둘뿐이다. 글을 쓰거나 고칠 때 파이썬을 만질 일은 없다.

docs/_index.json            위계 정본 — 섹션의 존재·차례, 섹션별 목차 묶음(groups),
                            위키 주소, 서비스 단추 행선지(apps)
docs/<섹션>/<이름>.md        한국어 정본
                            (docs/playbook/start.md → contextbio.ai/docs/playbook/start)
docs/<섹션>/en/<이름>.md     같은 파일명의 영어 번역
docs/wiki/<이름>.md         위키 (한국어만)
i18n/<언어>.json            화면 고정 문구 — 섹션 이름은 docs.sections, 묶음은 docs.groups
images/                     본문 이미지 (images/docs/<이름>/ 아래 권장)

지원 언어는 한국어·영어 둘이다(content.py 의 LANGS). 한국어가 정본이라 뿌리에 놓이고 영어가 en/ 아래에 놓인다.

빌드는 python build_docs.py && python build_wiki.py && python build_static.py, 배포는 main 푸시 → GitHub Actions. 커밋 범위가 곧 배포 범위이므로 로컬에서 빌드가 통과하는 것을 보고 푸시한다.

프론트매터

---
title: RNA-seq 발현 분석        # 필수 — 쪽 제목이자 좌측 목차의 이름
subtitle: …                    # 선택 — 제목 아래 작게 붙는 영문 정식 명칭 (앱 쪽)
group: guides                  # 필수 — 그 섹션의 groups 중 하나
order: 130                     # 필수 — 묶음 안 차례, 십 단위로 (사이 삽입이 쉽다)
summary: FASTQ 에서 DEG 표까지…  # 필수 — 제목 아래 한 줄
app: aurora                    # 선택 — "서비스 열기" 단추 (_index.json 의 apps 키)
hero: true                     # 선택 — 섹션 표지(index.md)만 크게 낸다
date: 2026-08-29               # 최초 작성일
updated: 2026-08-29            # 마지막 수정일 — 본문 끝에 표기된다. 고치면 갱신한다
draft: true                    # 초안 — 전 언어에서 빌드 제외. 공개할 때 지운다
tags: [rnaseq, deg]            # 선택 — 지금은 기입만, 검색을 들일 때 쓴다
---

구조 메타(group·order·app·hero·draft·subtitle·날짜)는 한국어 정본의 값만 쓰인다. 번역 파일에서는 title 과 summary 만 다시 적는다 — 나머지를 적어도 무시된다. 언어마다 차례가 어긋나는 사고를 막기 위한 계약이다. subtitle 이 정본 전용인 것은 그것이 영문 정식 명칭이라 번역할 것이 없기 때문이다(회사 사이트 제품 카드의 full_name 과 같은 값).

각 섹션의 index.md 는 그 섹션의 표지다. 없으면 빌드가 선다.

링크는 섹션까지 적는다

[데이터 준비](/playbook/data)          같은 갈래든 다른 갈래든 언제나 섹션부터
[가상세포](/research/virtual-cell)
[연구](/research)                      섹션 표지

섹션을 뺀 /aurora 는 문서 쪽이 아니라 서비스 주소다. 그렇게 적은 링크는 404 조차 나지 않고 사람을 조용히 앱으로 보낸다 — 깨진 링크보다 알아채기 어려운 사고여서 validate() 가 빌드 실패로 잡는다. 서비스로 보내고 싶다면 전체 주소로 적는다 (https://contextbio.ai/aurora).

/docs/… 로 시작하는 주소도 원고에 적지 않는다. 한국어에서는 우연히 통하지만 영어에서 /en 접두사가 붙지 않아 깨진다 — 언어별 주소로 바꾸는 일은 빌드가 한다.

빌드를 세우는 것들

build_docs.py 의 validate() 가 원고를 검사하고, 걸리면 빌드가 실패한다. main 푸시가 곧 배포라 사람 리뷰가 없으므로 Actions 의 빌드 실패가 리뷰 게이트다.

• title·group·summary·order 중 하나라도 없는 정본
• 그 섹션의 groups 에 없는 group, _index.json 의 apps 에 없는 app
• index.md 가 없는 섹션
• 정본(docs/<섹션>/<이름>.md)이 없는 번역 파일 — 고아 번역
• 섹션이 빠진 문서 링크, 그 섹션에 없는 쪽을 가리키는 링크, /docs/… 링크

새 쪽을 내는 순서

1. 갈래를 고른다(위 표). docs/<섹션>/<이름>.md 생성 — 이름은 kebab-case 영문. 공개 후 바꾸지 않는다 (URL 이다). 초안이면 draft: true 로 시작해 두면 커밋해도 배포에 나가지 않는다.
2. 프론트매터를 채운다. 새 묶음이 필요하면 _index.json 의 그 섹션 groups 와 i18n/ko.json·i18n/en.json 의 docs.groups 에 먼저 이름을 더한다.
3. 본문을 쓴다. ## 소제목 이 오른쪽 "이 페이지" 레일이 되므로 h2 단위로 끊는다.
4. 번역은 docs/<섹션>/en/<이름>.md 로 같은 파일명. 번역을 기다리며 공개를 미루지 않는다 — 없는 언어는 한국어 본문에 안내 한 줄이 붙어 나간다.
5. 로컬 빌드로 확인하고 draft 를 지운 뒤 main 에 푸시한다.

위키 쪽을 더하는 것은 더 간단하다 — docs/wiki/<이름>.md 에 title·order·summary 만 적으면 레일에 붙는다. 다국어도 groups 도 없다. 누가 보는지는 두 값이 정한다 — 앱 문서는 app: <앱 키>(aurora·pepdesigner·biowrit·labis)를 적어 그 앱의 앱관리자에게 열고, 모든 관리자가 봐야 하는 공통 쪽은 audience: admins 를 적는다. 둘 다 없으면 전체관리자 전용이다. 기존 쪽은 위키 머리글의 편집 단추로 고칠 수 있다(dev 브랜치 커밋).

문체와 구성

이미 일관된 틀이 있다. 새 쪽도 같은 틀을 따른다.

• 기능 목록이 아니라 순서를 적는다 — 독자가 무엇을 어떤 차례로 해야 하는지. 플레이북 표지의 선언이 전체의 기준이다.
• 첫 h2 는 "무엇을 하는 것인가", 전제 조건은 본문 앞에 ("시작하기 전에 알아야 할 것").
• 경어체 평서문("~합니다"). 굵은 글씨는 문장 속 계약·경고에만 쓴다.
• 서비스 쪽은 서비스당 한 쪽. 길어지면 쪼개지 말고 절차를 분석 가이드(guides)로 분리한다 — 서비스 쪽은 "무엇인가", 가이드는 "어떻게 하는가"다.
• 위키는 평서문이되 독자가 개발자다. 경로·포트·파일명을 그대로 적고, 비밀값은 적지 않는다(게이트는 화면만 가린다 — 이 위키의 "이 위키" 절 참고).