Skip to main content

​
Edicus Makers 문서 지침

이 디렉터리는 Mintlify로 만드는 Edicus Makers 문서 센터다. 레포 전체 지침은 루트 AGENTS.md를 먼저 읽는다.

​
이 프로젝트

  • 페이지는 YAML frontmatter가 있는 MDX 파일이고, 사이트 설정은 docs.json이다.
  • 로컬 미리보기: pnpm --filter edicus-docs dev (mint dev, 포트 13001)
  • 배포: Mintlify GitHub App이 main 브랜치의 apps/docs를 서브디렉터리로 읽어 자동 배포한다. 공개 주소는 make.edicus.io/docs다. make.edicus.io는 apps/make의 Vercel 프로젝트(edicus-help)가 받고 /docs만 Mintlify(motion1.mintlify.site)로 프록시한다. Mintlify 대시보드의 사용자 지정 도메인에서 “Host at”을 켜고 기본 경로를 docs로 둔다.
  • 내부 링크는 지금처럼 /sdk/launch 형태로 쓴다. Mintlify는 기본 경로에 맞춰 문서를 다시 빌드한다. 하위 경로 전환 직후 내부 링크가 /docs 아래로 이어지는지 한 번 확인한다. 고객센터처럼 문서 밖으로 가는 링크는 https://make.edicus.io/help 같은 절대 주소로 쓴다.
  • 탭은 넷이다. 개발자(가이드 MDX), 상품 설정(products/, Edicus Manager 상품·리소스·Customize·렌더 옵션), 템플릿 제작(templates/, InDesign 템플릿과 익스포터, 테스트 렌더), Server API(OpenAPI 자동 생성).
  • 상품 설정과 템플릿 제작 문서의 출처는 edicus-man(화면 이름, 저장 키, 기본값), Edicus 편집기(dev, 실제 동작), edicus-cep(익스포터, dev), edicus-prepress(렌더, dev) 코드다. Notion Help Center와 고객 Q&A는 참고만 하고 코드로 확인되는 것만 싣는다.
  • 설정 항목마다 코드에서 끝까지 추적한 동작을 적는다. “모션원에 확인하세요” 같은 미확인 표기를 남기지 않는다. 편집기가 읽지 않는 키는 그렇다고 쓰고, 일부 파트너에게만 열리는 항목은 “파트너 권한에 따라 잠금으로 표시될 수 있습니다”로만 쓴다(파트너 코드 금지).
  • Server API 레퍼런스의 단일 진실 원천은 api-reference/openapi.json이다. 엔드포인트가 바뀌면 MDX가 아니라 이 스펙을 고친다. docs.json의 Server API 탭은 METHOD /path 형태로 오퍼레이션을 참조한다.
    • 각 오퍼레이션에 x-mint.href로 ASCII 경로를 박아 둔다. 이게 없으면 한글 summary에서 슬러그가 유도돼 URL이 퍼센트 인코딩된다. 형식은 /api-reference/<tag 소문자>/<operationId 케밥>.
    • 리소스 API 오퍼레이션은 servers로 리소스 호스트를 개별 지정한다.
    • 여러 엔드포인트에 걸쳐 쓰이는 스키마는 api-reference/models/<케밥>.mdx에 데이터 모델 페이지로 둔다. frontmatter openapi-schema: "/api-reference/openapi.json <스키마 이름>"가 components.schemas를 그대로 그리므로 본문에는 필드를 다시 쓰지 않고, 어느 엔드포인트에서 나오는지만 적는다. 필드 설명은 스펙의 description에 쓴다. 엔드포인트 하나에만 붙는 XxxResult는 페이지를 만들지 않는다. 다른 체제로 옮길 때는 스키마를 표로 그리는 변환이 필요하다.
  • 콘텐츠 출처는 edicus-sdk 레포의 docs/와 llms.txt, edicus-api와 edicus-resource 레포의 실제 라우트, 그리고 references/의 사내 스펙 PDF 두 편이다. 문서와 코드가 다르면 코드를 따르고, 그 차이를 reference/known-inconsistencies.mdx에 적는다. 이 파일은 2026-10-07부터 .mintignore로 배포에서 빼 둔 내부 작업 목록이다. 항목마다 해당 저장소의 이슈를 단다. 공개 페이지에서 링크하지 않고, docs.json에도 다시 넣지 않는다.
  • 공개하지 않는 기능 셋이 있다. 아래는 파트너 연동 대상이 아니라 모션원 내부 도구용이므로 문서 본문, 예제, 표, 이벤트와 커맨드 목록, openapi.json, docs.json 어디에도 싣지 않는다. 2026-10-07에 전부 걷어 냈다.
    • 템플릿 편집: editTemplate(v2 edit_template)와 템플릿 편집 화면에서만 오는 publish-template-report, update-template-report.
    • 스태프 토큰: POST /v2/auth/staff/token, StaffTokenResult, edicusIdToken 보안 스킴, 이 엔드포인트에서만 나는 오류 코드(invalid_credentials, no_partner_code, no_staff_account, token_expired).
    • 패시브 모드: run_mode: 'passive', sdk/passive-mode.mdx, 패시브 모드 전용 이벤트(state-history, var-added, var-deleted, var-changed, selection-changed, font-list, undo, redo, impose-opened, set-cell-src-infos-report, clear-cell-src-report, enter-overlay-mode, exit-overlay-mode).
    • SDK나 서버에 실제로 있어도 싣지 않는다. 공개 여부가 바뀌면 사용자가 정한다. 비공개 내부 문서(reference/known-inconsistencies.mdx)에서는 언급해도 된다.
  • Edicus 내부 운영용 엔드포인트(/api/order/query, /api/order/request_for_render, /api/orders/:id/status/as/:status, force_cancel, master_admin 계열)는 싣지 않는다.
  • 서버용 JS SDK는 없다. @edicus/sdk/server, createEdicusApi, EdicusApiError, EdicusNetworkError, createRequester를 문서에 쓰지 않는다. 서버 연동은 HTTP 엔드포인트 직접 호출로만 설명한다. 예제는 TypeScript fetch로 쓰고, 반복되는 헤더와 오류 확인은 server/client.mdx의 callEdicus 래퍼를 참조한다. @edicus/sdk(브라우저)와 @edicus/sdk/types(타입 전용), @edicus/sdk/legacy(v2 호환) 세 진입점만 존재한다.
  • 검증은 pnpm --filter edicus-docs exec mint validate와 mint broken-links로 한다. 둘 다 통과해야 한다.
  • _legacy-starlight/는 Mintlify 전환 전의 Astro Starlight 앱 전체다. .mintignore로 빌드에서 제외한다. 되살리는 방법은 그 안의 README.md에 있다. 콘텐츠 이전이 끝나면 지운다.
  • Mintlify 컴포넌트와 설정은 https://mintlify.com/docs 에서 확인한다. MCP를 쓸 수 있으면 https://www.mintlify.com/docs/mcp를 쓴다.

​
독자와 용어

  • 독자는 셋이다: 외부 연동 개발자, 템플릿 제작자, Edicus Link 셀러. 개발자 문서는 경험이 적은 개발자를 기준으로 개념을 하나씩 설명한다.
  • 용어: 파트너(고객사), 파트너 코드, API 키(서버 전용), 토큰(브라우저용 JWT), 프로젝트(사용자가 편집 중인 문서), 템플릿, ps_code(사이즈코드@상품코드). 영어 식별자는 코드체로 쓴다.
  • wire 이름(액션 이름, 파라미터 이름)은 오타를 포함해 실제 이름 그대로 쓴다. 바로잡지 않는다.

​
문체

  • 한국어, 존댓말. em dash를 쓰지 않는다.
  • 한 문장에 한 가지 생각. 제목은 명사형이나 짧은 문장.
  • UI 요소는 굵게, 파일명과 명령과 코드 참조는 코드체.
  • 개념 페이지 구조: 배우는 것, 왜 필요한가, 직접 해보기, 됐는지 확인, 다음 단계.

​
허용 컴포넌트

Mintlify 전용 컴포넌트는 import 없이 쓸 수 있지만 Mintlify 밖에서는 동작하지 않는다. 나중에 직접 만드는 체제(Starlight 등)로 옮길 때 변환 비용을 줄이기 위해 아래 표의 컴포넌트만 쓰고, 본문은 최대한 순수 마크다운으로 쓴다. 흐름과 상태 전이는 ASCII 아트 대신 mermaid로 그린다. 한글은 폭이 넓어 ASCII 정렬이 깨진다. 쓰지 않는 것: 위 표 밖의 Mintlify 컴포넌트, <div className="..."> 같은 Tailwind 레이아웃, 인라인 HTML과 스타일, 커스텀 React 컴포넌트, snippets/ 재사용 조각. 필요해지면 먼저 이 표에 대응 관계와 함께 추가한 뒤 쓴다.

​
다루지 않는 것

  • 내부 호스트명, 서비스 계정, DB 접속 정보, API 키 값. 예제의 키는 항상 자리표시자다.
  • MotionOne 내부 운영 절차.