cudoc

API 레퍼런스

English | 한국어 · 사용 가이드

이 레퍼런스는 현재 구현의 공개 import, 옵션 기본값, 데이터 계약, 부수 효과, 내부 처리 방식을 설명합니다.

문서 작성과 어댑터 설치는 사용 가이드에서 시작합니다. 이 레퍼런스 가운데 호환을 약속하는 부분과 현재 릴리스의 동작을 설명하는 부분은 지원 버전에서 구분합니다.

레퍼런스 구성

문서 모델, Node 쪽 라이브러리, 호스트 어댑터를 각각 페이지 하나가 맡습니다.

문서 내용
문서 API 문법 옵션, 페이지 메타데이터, 컴파일, 의미 AST, 표현, 렌더링, 섹션, 필터링
Node API 수집, 라이브러리 파일, 임베드, 참조 검사, 데이터셋, 출력 보호, CLI, 언어 서버
어댑터 remark, 캡처, 호스트 순서, markdown-it 토큰, HTML 생성

패키지

호스트에 필요한 것만 설치합니다. 모든 패키지는 ESM이며 Node.js 22 이상이 필요합니다. 각 사용 가이드의 첫 단계에 그 호스트의 정확한 설치 명령이 있습니다.

패키지 역할
@cudoment/cudoc 공통 문서 처리, 컴파일, 쿼리, 수집, 데이터셋
cudoc-remark remark와 MDX 파이프라인 연결
cudoc-docusaurus Docusaurus 통합
cudoc-nextra Nextra 통합
cudoc-markdown-it markdown-it 파이프라인 연결
cudoc-vitepress VitePress 렌더링과 수집
cudoc-eleventy Eleventy 렌더링과 수집
cudoc-export HTML(사이트·단일 페이지·리뷰 페이지)·PDF·Word 생성

Next.js에는 전용 어댑터 패키지가 없습니다. @next/mdx가 remark 파이프라인을 그대로 넘겨주고, cudoc이 순서를 맞춰야 할 네이티브 제목 ID 처리나 목차 처리도 없기 때문에, host: "next"를 준 cudoc-remark 하나가 통합의 전부입니다. Docusaurus와 Nextra에 어댑터가 있는 이유는 그 호스트들에 그런 처리가 있기 때문입니다. → MDX 호스트

코어 패키지만 스코프를 사용합니다. npm에 cudoc 이름이 이미 있어서 @cudoment/cudoc으로 배포합니다.

패키지 경계

각 패키지는 작업의 한 층을 맡습니다.

코어에는 React 런타임 의존성이 없습니다. React는 이름 있는 컴포넌트를 출력하는 cudoc-remark/components에서만 사용합니다. Node 전용 진입점은 빌드 스크립트나 서버 코드에서 가져오고 클라이언트 컴포넌트에서는 가져오지 않습니다.

공개 진입점

아래 경로는 전체 패키지 이름을 적은 경우가 아니면 @cudoment/cudoc 뒤에 붙습니다. 실제 import 경계는 패키지 exports를 기준으로 합니다.

Import 역할 레퍼런스
@cudoment/cudoc, /ast, /syntax, /mdx AST 검증, 순회, 선택자, 하위 노드 생성 코어 도우미
/document 옵션과 원본 트리 정규화 문서 모델
/markdown 독립 컴파일 컴파일
/render HAST와 HTML 렌더링 렌더링
/present 화면 전용 마크업: 코드 제목과 탭 표현
/query, /sections 섹션 선택, 쿼리, 페이지 메타데이터 섹션
/dataset 불변 필터링 필터링
/node/library 전체 라이브러리 수집과 로딩 수집
/node/roots 컴파일러 없이 쓰는 소스 루트와 라이브러리 경로 수집
/node/resolve-embed 임베드 요청 해석과 처리 임베드
/node/prepare-embeds 빌드 전 임베드 데이터 준비·읽기 준비
/node/watch 반복되는 증분 수집 감시
/node/dataset 필터링한 AST 디렉터리 생성 데이터셋
/node/check, /node/report 라이브러리 전체 참조 검사와 출력 서식 참조 검사
/node/lsp cudoc lsp가 실행하는 표준 입출력 언어 서버 언어 서버
/node/local-target 로컬 링크·이미지를 문서, 파일, URL로 해석 참조 검사
/node/image-size PNG, JPEG, GIF, BMP 헤더에서 읽는 픽셀 크기 라이브러리 파일
/node/storage 파일시스템과 임시 디렉터리 기반 출력 저장
/embed, /node/export-ast, /node/load-ast-file, /node/paths 개별 AST 스냅샷과 경로 개별 스냅샷
/transforms/table-cell-list, /transforms/table-column-layout 하위 문법 변환 코어 도우미
/styles.css 테마를 인식하는 콜아웃, 배지, 트리, 코드, 주석, 탭 스타일 호스트 스타일시트
/paged 쪽을 나누는 작성기가 공유하는 쪽 나누기·트리 상수 페이지를 나누는 출력
cudoc-remark와 하위 경로 remark 연동, 캡처, TOC, 임베드 런타임 remark
cudoc-docusaurus, cudoc-nextra 호스트 플러그인 배열 MDX 호스트
cudoc-markdown-it 호스트 어댑터가 공유하는 markdown-it 파이프라인 markdown-it
cudoc-vitepress VitePress 호스트 정의와 컴파일러 VitePress와 Eleventy
cudoc-eleventy Eleventy 호스트 정의, 렌더러와 컴파일러 VitePress와 Eleventy
cudoc-export 사이트·PDF·Word 생성기와 디자인 토큰 내보내기
cudoc-export/docx, /pdf, /print Word 작성기, PDF 인쇄기, 인쇄용 HTML 페이지를 나누는 출력

모든 패키지는 ./package.json도 export하므로, 도구가 export 맵으로 패키지 manifest를 읽을 수 있습니다. /embed는 개별 스냅샷을 위한 Node 모음입니다. 문서 라이브러리나 코드 블록 임베드 API를 재수출하지 않습니다. 해당 API는 표에 적힌 node/*에서 가져옵니다. /sections는 collectSections를 제공하며 /query에는 하위 조회 도우미도 포함됩니다.

처리 흐름

문서는 설정된 컴파일러와 정규화를 거쳐 라이브러리에 이르고, 거기에서 임베드·렌더링으로, 또는 데이터셋 필터링으로 이어집니다.

flowchart LR
  Source[Markdown 또는 MDX] --> Compiler[설정된 컴파일러]
  Compiler --> Normalize[공통 문서 의미]
  Normalize --> Library[AST와 원문 스냅샷]
  Library --> Embed[선택, 치환, 임베드 처리]
  Embed --> Render[호스트 또는 HTML 렌더링]
  Library --> Dataset[불변 데이터셋 필터링]

문법 확장만 렌더링할 때는 라이브러리 저장이 필요하지 않습니다. 문서 간 임베드는 저장된 라이브러리를 사용하며, 원문 치환은 기존 설정으로 다시 컴파일합니다. 호스트 어댑터는 독립 파서와 결과가 같다고 가정하지 않고 실제 호스트 처리를 캡처해야 합니다.

같은 수집 라이브러리를 기본 호스트와 HTML 내보내기에서 함께 사용할 수 있습니다. HTML의 library 모드는 호스트 컴파일러를 다시 실행하거나 공유 파일을 변경하지 않고 준비된 블록을 사용합니다. 자세한 내용은 내보내기 입력 경로와 링크 정책에 있습니다.

최신화

함수, export, 옵션, 기본값, 스키마, 진단, 파이프라인을 변경할 때 같은 변경에서 관련 레퍼런스를 갱신합니다. 호출자의 사용 흐름이 바뀌면 사용 가이드와 실행 예제도 확인합니다.

cudoc