> 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/vi/cau-hinh/overleaf-toolkit/nhap-va-xuat-pandoc.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 cách sử dụng [Pandoc](https://pandoc.org/). Việc chuyển đổi chạy bên trong một **container Docker được cách ly** được quản lý bởi `clsi` dịch vụ, nên tính năng này mặc định bị tắt và phải được bật bằng một vài biến môi trường. #### Nó làm gì | Hướng | Từ → Đến | Định dạng | Ở đâu | | -------- | ---------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- | | **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 thông qua Pandoc) | *** ### Biến môi trường Có **hai** biến quan trọng, và một biến trông giống 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 khi đặt giá trị này; mọi giá trị khác sẽ tắt). * **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 route nhập, các route xuất, và `ol-ExposedSettings.enablePandocConversions` cờ cho biết frontend có nên 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 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ó `SANDBOXED_COMPILES=true` và socket Docker của máy chủ (`/var/run/docker.sock`) được gắn kết. 2. **Trường `PANDOC_IMAGE` phải có mặt** trên máy chủ Docker đó (được kéo về hoặc build cục bộ) trước khi thực hiện chuyển đổi đầu tiên. *** ### Thiết lập nhanh 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` nhận các biến. *** ### Build image Pandoc Một image Pandoc chuẩn vẫn hoạt động vì clsi gọi Pandoc theo cách tổng quát (không có template/filter tùy chỉnh). Nó chỉ cần ba thành phần tối thiể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 sandboxed của clsi # (nhập/xuất: docx / markdown / html, thông qua ENABLE_PANDOC_CONVERSIONS). # # Vì sao tồn tại điều 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 tổng quát (không có template/filter/reference-doc tùy chỉnh), nên một # image pandoc chuẩn vẫn hoạt động — nó chỉ cần ba thành phần tối thiểu mà clsi giả định: # # 1. Không có ENTRYPOINT `pandoc` — clsi chạy Cmd ["pandoc", ...]; với entrypoint # mặc định, điều đó sẽ trở 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` tại UID 1000 — mặc định dev / microservices. # - `www-data` tại UID 33 — các container *anh em* sandboxed của Server Pro đặt # TEXLIVE_IMAGE_USER=www-data (xem /etc/overleaf/env.sh). clsi (chạy với # www-data) tạo thư mục chuyển đổi sở hữu bởi 33:33, nên 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 hoặc # "unable to find user www-data" hoặc "permission denied". # Alpine đã có sẵn nhóm `www-data` ở GID 82, nên ta chuyển nó sang GID 33 để # khớp với host/image 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 # thẻ pandoc/core cụ thể để có bản build tái tạo hoàn toàn. 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 ``` Hãy build và gắn thẻ để thẻ khớp với `PANDOC_IMAGE`: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Đối với production, hãy ghim `pandoc/core` vào một phiên bản cụ thể thay vì `latest` để có bản build tái tạo được, 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ể | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | 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 việc chuyển đổi thất bại với lỗi máy chủ | `ENABLE_PANDOC_CONVERSIONS` chưa được đặt trên **clsi**, hoặc `PANDOC_IMAGE` thiếu trên máy chủ Docker | | `clsi` lỗi khi kéo image (401) | `PANDOC_IMAGE` vẫn trỏ tới mặc định riêng tư; build/trỏ tới image của 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` không được cài trong image | | Lỗi quyền trên các file đã chuyển đổi | Image không có người dùng `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/vi/cau-hinh/overleaf-toolkit/nhap-va-xuat-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.