콘텐츠 작성자 가이드
D.Hub 학습 센터의 워크숍은 dhub2-examples 시나리오를 기반으로 만들어집니다. 시나리오를 직접 작성·기여하려는 사람을 위한 안내입니다.
왜 시나리오를 작성하는가
이 사이트의 워크숍은 사용자가 자기 D.Hub 인스턴스에 그대로 적재 가능한 실제 시나리오를 전제로 합니다. 각 워크숍은 dhub2-examples 레포의 한 시나리오와 1:1로 대응합니다.
학습자는 클릭으로 적재합니다. 워크숍 본문은 zip 한 개를 받아 포털 *가져오기* 다이얼로그로 올리는 흐름만 가정합니다. 기여자는 Python 도구로 적재합니다. 본 페이지는 그 기여자 시점 — 시나리오를 새로 만들거나 적재 흐름을 자동화하려는 시점 — 을 안내합니다.
새 도메인을 다루고 싶다면 — 예를 들어 사내 제조 라인, 공공 데이터, 보험 청구 — 그 시나리오를 dhub2-examples에 추가하는 것이 학습 센터에 워크숍을 한 개 더 등록하는 가장 빠른 길입니다. 본 페이지는 그 시나리오를 어떻게 작성하는지 안내하는 4개의 작성자 문서로 연결됩니다.
작성자 문서 4종
모든 문서는 dhub2-examples 레포에 있습니다. 본 사이트에는 변경 추적이 어려우므로 미러하지 않고 GitHub로 연결합니다.
학습 센터 콘텐츠 MDX 작성 규칙
시나리오 머지 후 학습 센터 사이트에 워크숍·레슨을 추가할 때 자주 부딪치는 MDX 파서 트랩을 미리 정리합니다. 빌드 실패를 가장 흔하게 일으키는 패턴들입니다.
- 줄 첫 단어로
import/export금지. MDX는 줄 첫 단어가import또는export면 ESM 구문으로 해석합니다. 한국어 본문에서"import 도구를 실행합니다"같은 표현을 줄 시작에 두면 acorn 파서가 실패합니다. 대안: "적재 도구를 실행합니다" 처럼 우회하거나, 줄 앞에 다른 어구를 두세요. - 본문 안의 중괄호
{...}는 백틱으로 감싸기.{지표명}같은 자리표시자가 본문에 그대로 있으면 MDX가 JavaScript 표현식으로 해석합니다. 인라인 코드(`{지표명}`) 로 감싸거나 다른 표기로 바꾸세요. - 외부 사용자 매뉴얼은 본문 인라인 hyperlink가 아니라 frontmatter
docs_refs[]로. 본문에서는 매뉴얼명을 평문으로만 인용하고, 실제 링크는 페이지 하단의 관련 사용자 매뉴얼 블록이 자동 렌더합니다. 이 패턴은 docs 사이트 URL이 환경별로 바뀌어도 본문이 stale이 되지 않도록 보장합니다. - 새
docs_refs[]슬러그는lib/docs-refs.ts에 라벨을 함께 추가해야 합니다.npm run validate가 누락을 잡아 빌드를 멈춥니다. - 본문 첫 줄은 H2(
##)부터. H1은 페이지 컴포넌트가 렌더하므로 본문에 또 두면 위계가 두 번 노출됩니다.
시나리오를 다 만들었다면
새 시나리오가 dhub2-examples에 머지되면, 본 학습 센터에 그에 대응하는 워크숍 을 추가할 수 있습니다. 워크숍은 content/workshops/<시나리오 slug>/index.ko.mdx 한 파일이면 시작합니다 — 기존 리테일 재고 인텔리전스 워크숍이 좋은 템플릿입니다.
학습자 시점의 zip 적재 흐름은 학습 센터가 자동으로 호스팅합니다. 빌드 시점에 scripts/build-scenario-zips.mjs가 dhub2-examples 의 시나리오 디렉토리를 public/downloads/<시나리오 slug>.zip 으로 묶어, 워크숍 본문의 <ScenarioDownload /> 컴포넌트가 그 zip 을 그대로 가리킵니다. 시나리오를 머지한 다음 학습 센터 빌드를 한 번 돌리면 새 zip 이 자동으로 배포됩니다.
본 사이트의 콘텐츠 작성 컨벤션(frontmatter 스키마, docs_refs 사용법, 톤)은 레포의 AGENTS.md에 있습니다.