Adventure Book
당신은 문서를 하나의 여정으로 바꾸고 있습니다. 독자는 사용자가 선택한 테마로 구성된 일러스트 이야기를 단계별로 여행하며, 이야기 속 모든 표시된 단어를 클릭하면 그것이 나타내는 실제 것(소스 문서의 실제 명령, 규칙, 결정 또는 사실)을 볼 수 있습니다. 결과물은 오프라인에서도 작동하며 의존성이 없는 단일 .html 파일입니다.
엔진(탐색, 팝업 서랍, 코덱스, 진행 맵, 시차, 키보드, 모바일 레이아웃, 축소 동작)은 이미 assets/template.html에 내장되어 있습니다. scripts/build_book.py가 당신의 콘텐츠를 이 템플릿에 조립합니다. 당신의 역할은 창의적이면서도 충실한 부분, 즉 이야기, 우화, 산문, 팝업 및 장면 아트를 만드는 것입니다.
세 가지 참고 자료가 작업을 안내합니다: references/story.md(구조 — 매번 읽으십시오), references/themes.md(테마별 어조와 우화), references/scenes.md(그리기).
설계 시 피해야 할 두 가지 실패는 너무 많은 단어와 그 아래에 이야기가 없는 것입니다: 문서의 섹션을 의상으로 갈아입히고, 단계마다 반복하며 실제 사실을 분위기 속에 묻어버리는 책입니다. 더 적은 단어, 하나의 명확한 여정.
워크플로우
- 전체 소스를 읽으십시오. 제목, 일이 일어나는 순서, 독자가 이후에 할 수 있어야 하는 것, 그리고 틀리기 쉬운 사실(정확한 명령어, 이름, 숫자, 규칙)에 주목하십시오. 그 사실들이 바로 팝업이 보호하기 위해 존재하는 것들입니다.
- 테마와 우화를 정하십시오. 사용자가 제공한 테마를 사용하십시오. 제공된 것이 없으면 자료에 어울리는 것을 선택하고 선택한 테마를 알리십시오.
references/themes.md의 해당 섹션에서 어조, 모티프, 영웅 원형, 단계 명명 패턴을 읽으십시오. 그런 다음 자신을 위한 짧은 매핑 테이블을 작성하십시오: 소스의 각 실제 개념과 그에 대응하는 테마 세계의 개념(VPN = 베일, 데이터베이스 = 위대한 길들여진 짐승, CI 파이프라인 = 시련의 장). 모든 매핑은 책 전체에서 일관되게 유지하십시오. 독자는 우화를 한 번 배웁니다. 4장에서 베일이 안개가 되면 책은 가르치는 것을 멈춥니다. - 이야기를 구성하십시오.
references/story.md를 읽고, 아무것도 계획하기 전에 이 책의 스토리 스파인을 채우십시오: 영웅이 도달해야 할 목표, 그곳에 도달하게 하는 "그 때문에"의 연쇄, 끝 부분에서 저지르는 실수, 책이 마무리되는 이미지. 문서는 섹션의 목록입니다. 책은 결과의 연쇄이며, 하나를 다른 것으로 바꾸는 것이 전체 작업입니다. 소스가 단순한 목록처럼 보인다고 이 단계를 건너뛰지 마십시오 — 바로 그런 것들이 슬라이드쇼로 나오는 경우입니다. - 단계를 계획하십시오. 5
9개를 목표로 하되, 각각 하나의 비트를 가지며 스파인에 매핑하십시오(도착 1단계, 상승 중간 36단계, 잘못되는 1단계, 보상 1단계). 각 단계는 일반적으로 소스의 한 섹션입니다: 비트를 담기에는 너무 얇은 섹션은 병합하고, 약 120단어 이상의 내러티브가 필요한 섹션은 분할하십시오. 독자가 지식을 필요로 하는 순서대로 단계를 배열하십시오. 이는 일반적으로 문서의 순서입니다. 각 단계에 테마 어조의 제목과source:헤더를 부여하여 독자가 단계 내부에서 원본 섹션을 펼쳐볼 수 있게 하십시오. - 작업 폴더에 콘텐츠 파일을 작성하십시오 (
book.json,stages/NN-name.md,scenes/*.svg). 형식은 아래와 같습니다. - 자르고, 체크리스트를 실행하십시오. 각 단계를 "이야기 쓰기"에 비추어 다시 읽고 단어의 약 3분의 1을 제거하십시오. 초고는 거의 항상 필요한 길이의 두 배이며, 삭제하는 모든 문장은 표시된 단어를 더 쉽게 볼 수 있게 만듭니다. 그런 다음
references/story.md끝에 있는 체크리스트를 따라가며 실패한 부분을 수정하십시오. 이 두 작업은 빌드 전에 이루어져야 하며, 선택적 다듬기가 아닙니다. - 빌드하고 경고를 읽으십시오. "no pop-out with id", "heading not found", 커버리지 경고를 모두 수정하십시오. 보고서가 깨끗해지거나 남은 모든 경고가 의도적일 때까지 다시 빌드하십시오.
- 확인하고 전달하십시오. 파일을 열거나(macOS에서는
open <file>.html) 가능하다면 headless Chrome으로 스크린샷을 찍으십시오. 사용자에게 파일 위치, 탐색 방법(화살표 키, 맵 클릭, 빛나는 단어 클릭), 사용한 테마를 알려주십시오.
콘텐츠 형식
book.json (JSON 파일 기준 상대 경로):
{
"title": "포털을 향한 탐구",
"subtitle": "AGENTS.md를 통한 기사의 여정",
"theme": "knight",
"source": "../AGENTS.md",
"cover": { "eyebrow": "대화형 모험", "scene": "scenes/cover.svg", "blurb": "cover.md" },
"stages": [ "stages/01-gates.md", "stages/02-forge.md" ],
"ending": { "scene": "scenes/ending.svg", "blurb": "ending.md",
"recap": [ "다른 무엇보다 먼저 [[베일|vpn]]을 건너십시오", "모든 패키지는 `@internal/` 배너를 사용합니다" ] }
}
각 단계는 Markdown 파일입니다:
---
id: gates
title: 성문
chapter: 제1장
source: 로컬 개발 환경 설정
scene: scenes/01-gates.svg
---
안개가 길에 깔려 성에 다가가자 경비병이 길을 막습니다: [[베일|vpn]]을 통과하지 않은 자는 입장할 수 없다고...
## popout: vpn
title: VPN
회사 VPN에 연결된 상태여야 다른 모든 것이 작동합니다. 내부 패키지 저장소와 서비스는 네트워크 내부에서만 접근할 수 있기 때문입니다.
빌드 스크립트가 적용하거나 경고하는 규칙:
- 모든 산문 필드는 Markdown입니다. 모든 장면은 인라인 SVG이며
.svg파일의 경로로 제공됩니다. [[표시 텍스트|id]]는 팝업 링크를 표시합니다.[[docker]]는 텍스트를 id로 사용합니다. 각 id는 동일한 단계에## popout: id블록이 필요합니다(또는book.json의 책 수준popouts배열).- 프론트매터의
source:는 소스 문서의 제목을 지정합니다. 스크립트는 해당 섹션을 그대로 추출하여 "원본 스크롤" 버튼 뒤에 표시합니다. 팝업 블록은source: <heading>을 추가로 가져와 설명 아래에 관련 섹션을 첨부할 수 있습니다. 단,## popout: id바로 아래,title:과 함께 팝업의 헤더 줄에 위치해야 하며 설명 뒤에 있으면 안 됩니다. 잘못 배치되면 조용히 산문으로 읽히고 섹션은 드러나지 않습니다. - 테마는 미리 정의된 이름(
knight,space,pirate,noir,expedition,deepsea) 또는 객체{ "extends": "knight", "colors": {...}, "fonts": {...}, "vocabulary": {...} }입니다. 미리 정의된 테마는assets/themes.json에 있습니다. 새 테마를 만들 때는 하나를 복사하여 시작점으로 삼으십시오.
빌드:
python3 <skill-dir>/scripts/build_book.py --content work/book.json --out <name>.html
이야기 쓰기
2인칭, 현재 시제, 단계당 하나의 장면과 하나의 비트. "당신"이 영웅입니다. 단계는 장소에 대한 설명이 아니라 그 장소에서 일어나는 무언가입니다. 당신이 도착하고, 사람이나 문제를 만나고, 한 가지를 수행하고, 변화하거나 더 나은 장비를 갖추고 떠납니다. 단계가 "당신이 어딘가에 있고 분위기만 있다"로 요약된다면 아직 비트가 없는 것입니다: 소스 섹션에서 비트(독자가 해야 할 일, 하지 말아야 할 실수, 내려진 결정)를 찾아 그 주변에 장면을 구성하십시오.
계획한 형태를 유지하십시오. references/story.md는 구조에 대한 권위자입니다: 목표는 초반에 명시되고, 단계는 "그리고 나서"보다는 "그러므로"와 "하지만"으로 연결되며, 중반은 고조되고, 끝 부분에는 실제 실수가 있으며, 후렴구나 이어지는 장치가 있습니다.