Skip to content

feat: add Oxi (oxidocs) converter for docx to pdf and png - #708

Open
Ryujiyasu wants to merge 8 commits into
C4illin:mainfrom
Ryujiyasu:add-oxidocs
Open

Ryujiyasu wants to merge 8 commits into
C4illin:mainfrom
Ryujiyasu:add-oxidocs

Conversation

@Ryujiyasu

@Ryujiyasu Ryujiyasu commented Nov 14, 2026 •

Copy link
Copy Markdown

Closes #707.

Adds Oxi (oxidocs) as a second converter for Word documents, next to LibreOffice:

  • src/converters/oxidocs.ts: docx, docm and dotx to pdf (oxidocs docx-to-pdf, the whole document) and png (oxidocs docx-to-png, the first page). Everything else stays with LibreOffice, which also stays the default for docx.
  • Its tests, the registry entry and its test, a printVersions line, the README row and the knip entry.
  • Dockerfile: downloads the static musl build (x86_64 or aarch64, fonts included) from the pinned release oxidocs-v0.9.0-static.3, the same way as vtracer, and checks its SHA-256 before extracting.

The converter passes --quiet, so a successful conversion prints nothing; only warnings (for example a font with no file) and errors reach the log.

It also passes --strict: when a document holds content Oxi does not draw (ink drawings, for example), oxidocs writes no file and exits non-zero, so ConvertX reports the conversion as failed rather than returning a file with parts missing; LibreOffice can then be chosen instead.

Tested:

  • bun test tests/converters (284 pass) and bun run lint pass.
  • Built the image from this Dockerfile (x86_64) and, through the web routes (register, upload, convert, download), converted a docx to PDF and to PNG, both as root (the default) and with PUID=1000. A document with ink drawings fails as described above, with no output file. The arm64 download path is not tested in an image build; the arm64 binary itself is built and smoke-tested on an ARM runner in Oxi's CI.

I maintain Oxi. This PR was written with AI assistance (Claude); I reviewed it and take responsibility for it.


Summary by cubic

Adds Oxi (oxidocs) as a second converter for Microsoft Office documents alongside LibreOffice, which stays the default. docx, docm, and dotx convert to PDF (whole document) or PNG (first page), pptx, pptm, and potx to PDF (every slide) or PNG (first slide), and xlsx, xlsm, xltx, and xltm to PDF (print areas of every visible sheet) or PNG (first printed page).

  • Downloads the static musl build in the Dockerfile for x86_64 and aarch64 and runs oxidocs fonts-index to lay out its bundled fonts at build time, so they're present when the container runs with a non-root PUID; the version is a Renovate-managed ARG at 0.9.0-static.6.
  • Passes --strict, so a document holding content Oxi can't draw fails instead of writing an incomplete file, and --quiet, so successful conversions print nothing.

Written for commit 3a413ba. Summary will update on new commits.

View guided diff

Signed-off-by: RyujiYasukochi <ryuji.yasu@gmail.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 8 files

Reply to a comment to ask cubic a question or push back. It learns from your replies.

View guided diff | Re-trigger cubic

Comment thread Dockerfile Resolved
Comment thread src/converters/oxidocs.ts Resolved
Signed-off-by: RyujiYasukochi <ryuji.yasu@gmail.com>
Comment thread Dockerfile Outdated
rm /tmp/vtracer.tar.gz

# Install oxidocs binary (docx to pdf/png)
RUN ARCH=$(uname -m) && \

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like this to be a little bit more automatic if I am going to maintain this, but if you want to keep it up to date, this is fine

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for looking at this. I'm happy to keep it up to date: I'll send a PR whenever there is a new oxidocs release worth picking up, with the new tag and checksums.

If you would rather have Renovate handle it later, I can restructure the block (one version ARG with a # renovate: annotation, and checking against the .sha256 file published with each release instead of a pinned value). Just say so.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it is possible I think it would benefit us both :)

You can decide:)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 0e0f694, so it should not need anything from you when Oxi releases:

  • The version is now one ARG OXIDOCS_VERSION with a # renovate: annotation (github-releases, Ryujiyasu/oxi, only tags starting with oxidocs-v). A regex manager in renovate.json picks it up. The stock customManagers:dockerfileVersions preset would not work, because the Dockerfile has CRLF line endings and its pattern expects a single whitespace character between the comment and the ARG.
  • A versioningTemplate treats the -static.N rebuild number as a release rather than a prerelease. Without it, Renovate would stop at 0.9.0-static.* and never offer 0.9.1-static.1.
  • The archive is now checked against the .sha256 file published next to each asset, so a bump changes only the version. One trade-off to be aware of: this still catches a corrupted or truncated download, but someone able to replace the release assets could replace the .sha256 as well. The pinned hashes protected against that. If you'd rather keep pinned hashes, Renovate can't update them by itself, so I would go back to sending the bump PRs.
  • Bumped to 0.9.0-static.5.

Tested by building the install step on debian:testing-slim: the download, the checksum check and oxidocs docx-to-pdf --strict all work, and /tmp is left empty. Separately, the arm64 archive verifies against its .sha256, and an archive with an extra byte appended fails the check. The regex was checked against the Dockerfile and against the repo's other release tags (desktop-v*, nextcloud-app-v*, site), which it ignores.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you can remove the .sha256 since it doesn't provide any protection (if it simplifies anything)

also it is ok to change the line endings to LF

…ha256

The oxidocs version is one ARG with a renovate annotation, picked up by a
regex manager (the Dockerfile's CRLF line endings keep the stock
dockerfileVersions preset from matching). The archive is checked against the
.sha256 file published with each release instead of hashes pinned in the
Dockerfile, so a version bump needs no other edit. Moves to 0.9.0-static.5.

Signed-off-by: RyujiYasukochi <ryuji.yasu@gmail.com>
@Ryujiyasu

Copy link
Copy Markdown
Author

One more note on 0.9.0-static.5: besides .docx, this binary also converts PowerPoint and Excel:

  • oxidocs pptx-to-pdf and oxidocs pptx-to-png
  • oxidocs xlsx-to-pdf (the print areas of each visible sheet, with the sheet's page setup)

All of them take the same --strict --quiet flags. I ran each one in the test image above on a sample .pptx and on a Japanese .xlsx invoice. Everything converted, and the Japanese text is drawn with the CJK font bundled in the binary, so the image does not need extra fonts for it.

This PR only wires up .docx so it stays small. Once it is merged, I can send a follow-up PR that adds pptx and xlsx as inputs for the same converter, with tests. If you would rather have them in this PR, just say so.

Comment thread renovate.json Outdated
"customManagers": [
{
"customType": "regex",
"description": "oxidocs release in the Dockerfile. Its tags are oxidocs-v0.9.0-static.N; the -static.N rebuild number is a release, not a prerelease. A dedicated pattern because the Dockerfile has CRLF line endings, which customManagers:dockerfileVersions does not match.",

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can fix the line endings instead, it is not intentional

@C4illin

C4illin commented Nov 18, 2026

Copy link
Copy Markdown
Owner

This PR only wires up .docx so it stays small. Once it is merged, I can send a follow-up PR that adds pptx and xlsx as inputs for the same converter, with tests. If you would rather have them in this PR, just say so.

Seems like the last two formats wouldn't add much to review, you can include it here if you want :)

…te setup

- pptx, pptm and potx go to pdf (every slide) or png (the first slide),
  xlsx, xlsm, xltx and xltm to pdf (the print areas of every visible sheet),
  with the same --strict --quiet as docx.
- The Dockerfile has LF line endings, so the stock dockerfileVersions preset
  matches the oxidocs ARG; the versioning (-static.N is a release) and the
  tag filter are in the renovate comment, and renovate.json only extends the
  preset.
- The .sha256 check is gone: it came from the same release as the archive.

Signed-off-by: RyujiYasukochi <ryuji.yasu@gmail.com>
@Ryujiyasu

Ryujiyasu commented Nov 18, 2026 •

Copy link
Copy Markdown
Author

Thanks! All three are in e8ca063:

  • pptx and xlsx: pptx/pptm/potx → pdf (every slide) or png (the first slide), and xlsx/xlsm/xltx/xltm → pdf (the print areas of every visible sheet), with the same --strict --quiet. Excel → png is left out for now, because the xlsx-to-png command is only in Oxi's next static release. When it is out, Renovate will bump the version and adding png to calc is a one-line follow-up.
  • Line endings: the Dockerfile is LF now. That lets the stock customManagers:dockerfileVersions preset match the oxidocs ARG, so renovate.json only extends the preset. The versioning rule (-static.N is a release) and the oxidocs-v tag filter moved into the # renovate: comment.
  • .sha256: removed, agreed.

Checks: bun test tests/converters/oxidocs.test.ts tests/converters/main.test.ts passes (44 tests, including new ones for pptx and xlsx). tsc, ESLint and Prettier are clean. I also built the install step on debian:testing-slim and ran docx → pdf/png, pptx → pdf/png and xlsx → pdf with --strict inside it. All five worked.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

3 issues found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="Dockerfile">

<violation number="1" location="Dockerfile:79">
P3: This install comment advertises PNG output for xlsx, but Oxi exposes only PDF for workbooks. Change it to state that docx/pptx support PDF and PNG while xlsx supports PDF only.</violation>
</file>

<file name="src/converters/oxidocs.ts">

<violation number="1" location="src/converters/oxidocs.ts:13">
P2: The new category targets let the `/convert` endpoint accept xlsx→png through oxidocs, then run unsupported `xlsx-to-png`. Validate the target against the uploaded file's input category before starting conversion.</violation>

<violation number="2" location="src/converters/oxidocs.ts:14">
P3: These category additions make Oxi advertise duplicate PDF/PNG entries in the main picker and converter list. Deduplicate targets when merging category outputs in the converter registry.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

Comment thread src/converters/oxidocs.ts
},
to: {
text: ["pdf", "png"],
presentation: ["pdf", "png"],

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The new category targets let the /convert endpoint accept xlsx→png through oxidocs, then run unsupported xlsx-to-png. Validate the target against the uploaded file's input category before starting conversion.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/converters/oxidocs.ts, line 13:

<comment>The new category targets let the `/convert` endpoint accept xlsx→png through oxidocs, then run unsupported `xlsx-to-png`. Validate the target against the uploaded file's input category before starting conversion.</comment>

<file context>
@@ -5,12 +5,19 @@ import { ExecFileFn } from "./types";
   },
   to: {
     text: ["pdf", "png"],
+    presentation: ["pdf", "png"],
+    calc: ["pdf"],
   },
</file context>

Comment thread Dockerfile Outdated
chmod +x /usr/local/bin/vtracer && \
rm /tmp/vtracer.tar.gz

# Install oxidocs binary (docx, pptx and xlsx to pdf/png)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This install comment advertises PNG output for xlsx, but Oxi exposes only PDF for workbooks. Change it to state that docx/pptx support PDF and PNG while xlsx supports PDF only.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At Dockerfile, line 79:

<comment>This install comment advertises PNG output for xlsx, but Oxi exposes only PDF for workbooks. Change it to state that docx/pptx support PDF and PNG while xlsx supports PDF only.</comment>

<file context>
@@ -1,120 +1,115 @@
+  chmod +x /usr/local/bin/vtracer && \
+  rm /tmp/vtracer.tar.gz
+
+# Install oxidocs binary (docx, pptx and xlsx to pdf/png)
+# renovate: datasource=github-releases depName=Ryujiyasu/oxi versioning=regex:^(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:-static\.(?<build>\d+))?$ extractVersion=^oxidocs-v(?<version>.+)$
+ARG OXIDOCS_VERSION=0.9.0-static.5
</file context>
Suggested change
# Install oxidocs binary (docx, pptx and xlsx to pdf/png)
# Install oxidocs binary (docx and pptx to pdf/png; xlsx to pdf)

Comment thread src/converters/oxidocs.ts Outdated
to: {
text: ["pdf", "png"],
presentation: ["pdf", "png"],
calc: ["pdf"],

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: These category additions make Oxi advertise duplicate PDF/PNG entries in the main picker and converter list. Deduplicate targets when merging category outputs in the converter registry.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/converters/oxidocs.ts, line 14:

<comment>These category additions make Oxi advertise duplicate PDF/PNG entries in the main picker and converter list. Deduplicate targets when merging category outputs in the converter registry.</comment>

<file context>
@@ -5,12 +5,19 @@ import { ExecFileFn } from "./types";
   to: {
     text: ["pdf", "png"],
+    presentation: ["pdf", "png"],
+    calc: ["pdf"],
   },
 };
</file context>

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one is real: allTargets in src/converters/main.ts concatenates every category's to list, so on the main page Oxi's group shows pdf png three times (once per input category). LibreOffice's group already shows pdf twice for the same reason, so it is not specific to this converter. Picking any of the buttons converts correctly, so only the list looks repeated.

The fix is a one-line dedupe where allTargets is built ([...new Set([...])]), which would tidy LibreOffice's list too. I can add it to this PR or send it as a separate one, whichever you prefer.

(The other two comments from that run no longer apply: since 0.9.0-static.6, xlsx → png is supported, and the Dockerfile comment says docx, pptx and xlsx to pdf/png.)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the duplicate-list finding applies: allTargets concatenates category targets, so Oxi’s entries repeat, as do LibreOffice’s. Since conversion works, this is a listing issue; please deduplicate the merged targets in src/converters/main.ts so the shared fix covers both.

Signed-off-by: RyujiYasukochi <ryuji.yasu@gmail.com>
@Ryujiyasu

Copy link
Copy Markdown
Author

Oxi's 0.9.0-static.6 is out with xlsx-to-png, so I bumped to it here and added png for workbooks: calc now goes to pdf and png. Tests pass (now covering xlsx → png), and inside the install step on debian:testing-slim all six conversions (docx, pptx and xlsx, each to pdf and png) work with --strict.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Converter Request] Oxi: docx to PDF/PNG with Word-faithful layout

2 participants