> 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/vi/cau-hinh/overleaf-toolkit/pandoc-import-and-export.md). # Nhập và xuất Pandoc ### Nhập / xuất Pandoc Overleaf có thể chuyển đổi tài liệu sang và từ LaTeX bằng [Pandoc](https://pandoc.org/). Việc chuyển đổi chạy bên trong một **container Docker được cô lập trong sandbox** do `clsi` dịch vụ quản lý, vì vậy tính năng này mặc định tắt và phải bật bằng một vài biến môi trường. #### Tính năng | Hướng | Từ → Sang | Định dạng | Vị trí | | -------- | ---------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- | | **Nhập** | tài liệu → dự án LaTeX | `docx`, `markdown` | *Dự án mới → Nhập* (tải lên một `.docx` / `.md` và biến nó thành một `.tex` dự án có thể chỉnh sửa) | | **Xuất** | dự án LaTeX → tài liệu | `docx`, `markdown`, `html` | *Menu → Tải xuống / Xuất* (kết xuất dự án qua Pandoc) | *** ### Các biến môi trường Có **hai** biến quan trọng, và một biến tương tự nhưng không **không**. 1\. `ENABLE_PANDOC_CONVERSIONS` — công tắc chính ```bash ENABLE_PANDOC_CONVERSIONS=true ``` * Kiểu: boolean (`true` bật nó; bất kỳ giá trị nào khác sẽ tắt nó). * **Phải được đặt trên CẢ HAI `web` và `clsi` dịch vụ.** Chúng là các tiến trình riêng biệt với cấu hình riêng biệt: * `web` đọc nó vào `enablePandocConversions` (`services/web/config/settings.defaults.js`). Nó kiểm soát các tuyến nhập, các tuyến xuất, và cờ `ol-ExposedSettings.enablePandocConversions` dùng để báo cho frontend có hiển thị giao diện Nhập/Xuất hay không. * `clsi` đọc nó vào `enablePandocConversions` (`services/clsi/config/settings.defaults.cjs`). Nó kiểm soát các endpoint chạy Pandoc. * Nếu nó được bật trên `web` nhưng không trên `clsi` (hoặc ngược lại), giao diện sẽ xuất hiện nhưng việc chuyển đổi sẽ thất bại — hãy giữ chúng đồng bộ. 2\. `PANDOC_IMAGE` — image container mà clsi chạy để chuyển đổi ```bash PANDOC_IMAGE=your-repo/pandoc:3.9 ``` ### Điều kiện tiên quyết Vì các lần chuyển đổi chạy dưới dạng các container Docker được khởi chạy bởi `clsi`: 1. **`clsi` phải chạy ở chế độ sandbox với quyền truy cập Docker.** Trong môi trường dev `clsi` đã có sẵn `SANDBOXED_COMPILES=true` và socket Docker của máy chủ (`/var/run/docker.sock`) được mount. 2. **Trường `PANDOC_IMAGE` phải có mặt** trên host Docker đó (được kéo về hoặc build cục bộ) trước lần chuyển đổi đầu tiên. *** ### Thiết lập nhanh Bộ stack dev (`develop/dev.env`) đã đi kèm với: ```bash ENABLE_PANDOC_CONVERSIONS=true PANDOC_IMAGE=overleaf-pandoc:local ``` Vì image chính thức là riêng tư, hãy build image đi kèm **một lần** trước khi sử dụng tính năng: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Sau đó (khởi động lại) stack để `clsi` và `web` nạp các biến này. *** ### Build image Pandoc Một image Pandoc mặc định hoạt động vì clsi gọi Pandoc theo cách chung chung (không có template/filter tùy chỉnh). Nó chỉ cần ba thành phần thiết yếu khi chạy, tất cả đều được xử lý bởi `develop/pandoc/Dockerfile`: ```dockerfile # Image Pandoc tùy chỉnh cho các chuyển đổi sandbox của clsi # (nhập/xuất: docx / markdown / html, thông qua ENABLE_PANDOC_CONVERSIONS). # # Vì sao cần cái này: # Image quay.io/sharelatex/pandoc:3.9 chính thức là riêng tư (401, không thể pull). # clsi gọi pandoc theo cách chung (không có template/filter/reference-doc tùy chỉnh), nên một # image pandoc mặc định là đủ — nó chỉ cần ba thành phần lúc chạy mà clsi giả định: # # 1. Không có `pandoc` ENTRYPOINT — clsi chạy Cmd ["pandoc", ...]; với entrypoint mặc định # thì sẽ thành `pandoc pandoc ...`. # 2. `zip` — bước thứ hai của chuyển đổi nhập chạy `zip -r` để đóng gói đầu ra. # 3. Người dùng khớp với cách clsi chạy container chuyển đổi (User=$TEXLIVE_IMAGE_USER): # - `tex` ở UID 1000 — mặc định của dev / microservices. # - `www-data` ở UID 33 — các container *anh em* sandbox của Server Pro đặt # TEXLIVE_IMAGE_USER=www-data (xem /etc/overleaf/env.sh). clsi (chạy với tư cách # www-data) tạo thư mục chuyển đổi thuộc sở hữu 33:33, vì vậy container phải chạy # với tư cách www-data(33) để ghi vào đó — nếu không pandoc sẽ lỗi với một trong hai # "unable to find user www-data" hoặc "permission denied". # Alpine đã có sẵn nhóm `www-data` ở GID 82, vì vậy chúng tôi chuyển nó sang GID 33 để # khớp với host/ảnh texlive. # # Build (tag phải khớp với PANDOC_IMAGE trong develop/dev.env): # docker build -t overleaf-pandoc:local develop/pandoc # # Lưu ý: ghim vào `latest` (pandoc 3.10 tại thời điểm viết). Hãy ghim vào một # tag pandoc/core cụ thể để có các bản build hoàn toàn tái lập. 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 ``` Build và tag nó để tag khớp với `PANDOC_IMAGE`: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Với môi trường production, hãy ghim `pandoc/core` vào một phiên bản cụ thể thay vì `mới nhất` để các bản build tái lập, và đặt `PANDOC_IMAGE` thành đường dẫn registry của bạn. *** ### Khắc phục sự cố | Triệu chứng | Nguyên nhân có thể | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Các nút Nhập/Xuất không xuất hiện | `ENABLE_PANDOC_CONVERSIONS` không `true` trên **web** | | Giao diện xuất hiện nhưng chuyển đổi thất bại với lỗi máy chủ | `ENABLE_PANDOC_CONVERSIONS` không được đặt trên **clsi**, hoặc `PANDOC_IMAGE` bị thiếu trên host Docker | | `clsi` lỗi khi kéo image (401) | `PANDOC_IMAGE` vẫn trỏ tới mặc định riêng tư; hãy build/trỏ tới image của riêng bạn | | Container chạy `pandoc pandoc …` / sai đối số | Image có một `pandoc` `ENTRYPOINT`; hãy dùng `ENTRYPOINT []` | | Đầu ra nhập trống / bước zip thất bại | `zip` chưa được cài trong image | | Lỗi quyền trên các tệp đã chuyển đổi | Image không có `tex` người dùng ở 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/vi/cau-hinh/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.