> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/pandoc-import-and-export.md). # Pandoc 가져오기 및 내보내기 ### Pandoc 가져오기 / 내보내기 Overleaf는 다음을 사용해 문서를 LaTeX로, 그리고 LaTeX에서 문서로 변환할 수 있습니다 [Pandoc](https://pandoc.org/). 변환은 다음 내부에서 실행됩니다 **샌드박스화된 Docker 컨테이너** 가 관리하는 `clsi` 서비스이므로, 이 기능은 기본적으로 꺼져 있으며 몇 개의 환경 변수로 켜야 합니다. #### 작동 방식 | 방향 | 원본 → 대상 | 형식 | 위치 | | -------- | --------------- | -------------------------- | ------------------------------------------------------------------------- | | **가져오기** | 문서 → LaTeX 프로젝트 | `docx`, `markdown` | *새 프로젝트 → 가져오기* (다음 파일을 업로드하고 `.docx` / `.md` 를 편집 가능한 `.tex` 프로젝트로 바꿉니다) | | **내보내기** | LaTeX 프로젝트 → 문서 | `docx`, `markdown`, `html` | *메뉴 → 다운로드 / 내보내기* (Pandoc을 통해 프로젝트를 렌더링합니다) | *** ### 환경 변수 다음이 **두** 개의 중요한 변수와, 그렇지 않은 하나의 유사 변수가 있습니다 **하지**. 1\. `ENABLE_PANDOC_CONVERSIONS` — 마스터 스위치 ```bash ENABLE_PANDOC_CONVERSIONS=true ``` * 유형: boolean (`true` 이면 활성화되고, 그 외에는 비활성화됩니다). * **다음 두 곳 모두에 설정되어야 합니다 `web` 및 `clsi` 서비스.** 이들은 서로 다른 구성으로 동작하는 별도 프로세스입니다: * `web` 다음으로 읽어 들입니다 `enablePandocConversions` (`services/web/config/settings.defaults.js`). 가져오기 경로, 내보내기 경로, 그리고 `ol-ExposedSettings.enablePandocConversions` 플래그를 제어해 프런트엔드에 가져오기/내보내기 UI를 보여줄지 여부를 알려줍니다. * `clsi` 다음으로 읽어 들입니다 `enablePandocConversions` (`services/clsi/config/settings.defaults.cjs`). Pandoc을 실행하는 엔드포인트를 제어합니다. * 다음에서는 활성화되어 있지만 `web` 에서는 활성화되어 있지 않다면 `clsi` (또는 그 반대라면), UI는 보이지만 변환은 실패합니다 — 서로 동기화된 상태로 유지하세요. 2\. `PANDOC_IMAGE` — clsi가 변환을 위해 실행하는 컨테이너 이미지 ```bash PANDOC_IMAGE=your-repo/pandoc:3.9 ``` ### 사전 요구 사항 변환은 다음이 생성한 Docker 컨테이너로 실행되므로 `clsi`: 1. **`clsi` Docker 접근이 가능한 샌드박스 모드로 실행되어야 합니다.** 개발 스택에서는 `clsi` 이미 다음이 `SANDBOXED_COMPILES=true` 와 호스트 Docker 소켓(`/var/run/docker.sock`)이 마운트되어 있습니다. 2. **다음 `PANDOC_IMAGE` 가 존재해야 합니다** 첫 변환 전에 해당 Docker 호스트에 (로컬에서 pull되었거나 빌드된 상태로) 있어야 합니다. *** ### 빠른 설정 개발 스택(`develop/dev.env`)에는 이미 다음이 포함되어 있습니다: ```bash ENABLE_PANDOC_CONVERSIONS=true PANDOC_IMAGE=overleaf-pandoc:local ``` 공식 이미지는 비공개이므로, 포함된 이미지를 빌드하세요 **한 번** 기능을 사용하기 전에: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` 그다음 스택을 (재)시작해서 `clsi` 및 `web` 변수를 적용하세요. *** ### Pandoc 이미지 빌드 기본 Pandoc 이미지는 clsi가 Pandoc을 일반적인 방식으로 호출하기 때문에(맞춤 템플릿/필터 없음) 작동합니다. 런타임 필수 요소는 세 가지뿐이며, 모두 다음이 처리합니다 `develop/pandoc/Dockerfile`: ```dockerfile # clsi 샌드박스 변환용 맞춤 Pandoc 이미지 # (가져오기/내보내기: docx / markdown / html, ENABLE_PANDOC_CONVERSIONS를 통해). # # 이유: # 공식 quay.io/sharelatex/pandoc:3.9 이미지는 비공개입니다(401, pull 불가). # clsi는 pandoc을 일반적인 방식으로 호출하므로(맞춤 템플릿/필터/reference-doc 없음), # 기본 pandoc 이미지면 충분합니다 — clsi가 가정하는 런타임 필수 요소 세 가지만 있으면 됩니다: # # 1. `pandoc` ENTRYPOINT 없음 — clsi는 Cmd ["pandoc", ...]를 실행합니다. 기본 # entrypoint가 있으면 `pandoc pandoc ...`가 됩니다. # 2. `zip` — 가져오기 변환의 두 번째 단계는 출력물을 패키징하기 위해 `zip -r`을 실행합니다. # 3. clsi가 변환 컨테이너를 실행하는 방식에 맞는 사용자(User=$TEXLIVE_IMAGE_USER): # - UID 1000의 `tex` — 개발 / microservices 기본값. # - UID 33의 `www-data` — Server Pro 샌드박스 *형제* 컨테이너는 # `TEXLIVE_IMAGE_USER=www-data`로 설정합니다(/etc/overleaf/env.sh 참조). clsi는( # `www-data`로 실행 중)가 33:33 소유의 변환 디렉터리를 만들므로, 컨테이너는 그 안에 쓸 수 있도록 # `www-data`(33)로 실행되어야 합니다 — 그렇지 않으면 pandoc은 # "unable to find user www-data" 또는 "permission denied"로 실패합니다. # Alpine에는 이미 GID 82의 `www-data` 그룹이 있으므로, 호스트/texlive 이미지와 # 맞추기 위해 GID 33으로 옮깁니다. # # 빌드 (태그는 develop/dev.env의 PANDOC_IMAGE와 일치해야 함): # docker build -t overleaf-pandoc:local develop/pandoc # # 참고: 작성 시점의 `latest`(pandoc 3.10)에 고정되어 있습니다. 완전히 재현 가능한 빌드를 위해 # 특정 pandoc/core 태그로 고정하세요. FROM pandoc/core:latest ENTRYPOINT [] RUN apk add --no-cache zip \\ && adduser -D -u 1000 tex \\ && (delgroup www-data 2>/dev/null || true) \\ && addgroup -g 33 www-data \\ && adduser -D -u 33 -G www-data www-data ``` 태그가 일치하도록 빌드하고 태그를 지정하세요 `PANDOC_IMAGE`: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` 프로덕션에서는 `pandoc/core` 를 대신 특정 버전으로 고정하세요 `latest` 재현 가능한 빌드를 위해, 그리고 `PANDOC_IMAGE` 를 레지스트리 경로로 설정하세요. *** ### 문제 해결 | 증상 | 가능한 원인 | | ------------------------------------ | ------------------------------------------------------------------------------------- | | 가져오기/내보내기 버튼이 보이지 않음 | `ENABLE_PANDOC_CONVERSIONS` 하지 `true` 에서 **web** | | UI는 보이지만 변환이 서버 오류로 실패함 | `ENABLE_PANDOC_CONVERSIONS` 다음에 설정되어 있지 않음 **clsi**, 또는 `PANDOC_IMAGE` Docker 호스트에 없음 | | `clsi` 이미지 pull 오류(401) | `PANDOC_IMAGE` 여전히 비공개 기본값을 가리킴; 직접 이미지를 빌드하거나 해당 이미지로 지정하세요 | | 컨테이너가 실행됨 `pandoc pandoc …` / 잘못된 인자 | 이미지에 다음이 있음 `pandoc` `ENTRYPOINT`; 다음을 사용하세요 `ENTRYPOINT []` | | 가져오기 출력이 비어 있음 / zip 단계 실패 | `zip` 이 이미지에 설치되어 있지 않음 | | 변환된 파일에서 권한 오류 | 이미지에 다음이 없음 `tex` UID 1000의 사용자 | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ayakaleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/pandoc-import-and-export.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.