> For the complete documentation index, see [llms.txt](https://overleaf-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://overleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/pandoc.md). # Pandoc 가져오기 및 내보내기 ### Pandoc 가져오기 / 내보내기 Overleaf는 다음을 사용하여 문서를 LaTeX로, 그리고 LaTeX에서 문서로 변환할 수 있습니다: [Pandoc](https://pandoc.org/). 변환은 다음 내부에서 실행됩니다: **샌드박스화된 Docker 컨테이너** 다음에 의해 관리되는 `clsi` 서비스입니다. 따라서 이 기능은 기본적으로 꺼져 있으며 몇 개의 환경 변수를 설정해 켜야 합니다. #### 하는 일 | 방향 | 출발 → 도착 | 형식 | 위치 | | -------- | --------------- | ---------------------- | --------------------------------------------------------------------------- | | **가져오기** | 문서 → LaTeX 프로젝트 | `docx`, `마크다운` | *새 프로젝트 → 가져오기* (다음을 업로드하여 `.docx` / `.md` 그리고 이를 편집 가능한 `.tex` 프로젝트로 만듭니다) | | **내보내기** | LaTeX 프로젝트 → 문서 | `docx`, `마크다운`, `html` | *메뉴 → 다운로드 / 내보내기* (Pandoc를 통해 프로젝트를 렌더링함) | *** ### 환경 변수 다음이 있습니다 **두** 중요한 변수 2개와, 비슷해 보이지만 작동하는 변수 1개가 있습니다 **아니**. 1\. `ENABLE_PANDOC_CONVERSIONS` — 마스터 스위치 ```bash ENABLE_PANDOC_CONVERSIONS=true ``` * 유형: boolean (`true` 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 호스트에(풀했거나 로컬에서 빌드한 상태로) 있어야 합니다. *** ### 빠른 설정 개발 스택(`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를 일반적인 방식으로 호출하기 때문입니다(사용자 정의 템플릿/필터 없음). 런타임 필수 요소 3가지만 필요하며, 이는 모두 다음에서 처리합니다 `develop/pandoc/Dockerfile`: ```dockerfile # clsi 샌드박스 변환용 사용자 정의 Pandoc 이미지 # (가져오기/내보내기: docx / markdown / html, ENABLE_PANDOC_CONVERSIONS를 통해). # # 이 파일이 존재하는 이유: # 공식 quay.io/sharelatex/pandoc:3.9 이미지는 비공개입니다(401, 가져올 수 없음). # clsi는 pandoc를 일반적으로 호출하므로(사용자 정의 템플릿/필터/reference-doc 없음), # 기본 pandoc 이미지로 충분합니다. 단, clsi가 가정하는 런타임 필수 요소 3개가 필요합니다: # # 1. `pandoc` ENTRYPOINT 없음 — clsi는 Cmd ["pandoc", ...]로 실행합니다. 기본 # entrypoint가 있으면 `pandoc pandoc ...`가 됩니다. # 2. `zip` — 가져오기 변환의 두 번째 단계에서 결과를 패키징하기 위해 `zip -r`를 실행합니다. # 3. clsi가 변환 컨테이너를 실행하는 방식과 일치하는 사용자(User=$TEXLIVE_IMAGE_USER): # - UID 1000의 `tex` — dev / 마이크로서비스 기본값. # - 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` 그룹이 있으므로, 이를 GID 33으로 옮겨 # 호스트/texlive 이미지와 맞춥니다. # # 빌드(tag는 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` 이미지 가져오기 오류(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://overleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/pandoc.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.