feat(boxnote): add a BoxNote document backend by pablopupo · Pull Request #3722 · docling-project/docling

pablopupo · 2026-06-29T21:03:09Z

Description

Adds a backend for Box Notes (.boxnote), modeled on the existing csv and webvtt backends.

.boxnote files are JSON, but Box has two incompatible schemas. The older atext/pool model (what boxnotes2html parses) predates a 2022 change; the current one is a ProseMirror-style doc tree, which is what the app exports now. This handles the current format and maps its nodes onto a DoclingDocument: headings, paragraphs (with bold/italic/underline/strikethrough and links), lists, tables, code and images.

The decode is pure Python, so there's no new dependency. A legacy atext/pool note is detected and rejected with a clear DocumentLoadError rather than mis-parsed. I left legacy out to keep this focused; it's an easy follow-up if you'd want it here.

Changes

docling/backend/boxnote_backend.py: new BoxNoteDocumentBackend.
docling/datamodel/base_models.py: register InputFormat.BOXNOTE, the .boxnote extension, and a mime type.
docling/datamodel/document.py: resolve .boxnote to its mime in format detection.
docling/document_converter.py: BoxNoteFormatOption on the SimplePipeline, plus its default option.
docs/usage/supported_formats.md: list BoxNote.

Tests

tests/test_backend_boxnote.py covers a sample .boxnote end to end (Markdown, indented-text and JSON ground truth), format detection, the legacy-unsupported path, and empty input.

Resolves #481

Checklist:

Documentation has been updated, if necessary.
Examples have been added, if necessary.
Tests have been added, if necessary.

github-actions · 2026-06-29T21:03:21Z

✅ DCO Check Passed

Thanks @pablopupo, all your commits are properly signed off. 🎉

mergify · 2026-06-29T21:03:45Z

Merge Protections

🟢 All 2 merge protections satisfied — ready to merge.

Show 2 satisfied protections

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

🟢 Require two reviewer for test updates

When test data is updated, we require two reviewers

#approved-reviews-by >= 2

PeterStaar-IBM

Can you also update the README.me and docs/index.md?

PeterStaar-IBM · 2026-06-30T04:21:47Z

@pablopupo Many thanks for this addition! Can you look into my comments?

codecov · 2026-06-30T04:24:57Z

Codecov Report

❌ Patch coverage is 92.34043% with 18 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/backend/boxnote_backend.py	92.10%	18 Missing ⚠️

📢 Thoughts on this report? Let us know!

ceberam

Thanks @pablopupo for enabling Docling with yet another file format 🚀

I left some comments and I agree with @PeterStaar-IBM on the gap with rich cell content.
I also share some recommendations for the style:

Instead of Optional[X] / Union style use the modern X | None style
Try to be more specific in method signatures, instead of using bare list / dict type hints (e.g., prefer list[dict] / dict[str, Any]). We have seen very often that these type hints help Mypy identify potential issues.

pablopupo · 2026-06-30T14:50:14Z

I pushed a round of fixes that should cover what you both raised:

DocItemLabel.PARAGRAPH is now DocItemLabel.TEXT.
For tables, table_header cells are kept and marked as column_header, and any cell with images or multiple blocks now becomes a RichTableCell. A lone cell that carries a link or formatting does too, since otherwise the hyperlink would be dropped (a plain TableCell has no hyperlink field). The fixture exercises all three.
I removed the unload() override since it just duplicated the base class.
_as_url is much stricter, so only http/https/mailto turn into links and everything else (javascript:, bare strings, relative paths) is dropped rather than guessed at. A malformed href no longer takes the whole conversion down with it either.
The annotations use X | None and specific list[dict] / dict[str, Any] hints now.
README.md and docs/index.md both list Box Notes.

While I was in there I also tightened up a couple of malformed inputs, so a non-object JSON payload or a non-string href fails cleanly instead of raising.

On the mime type, I opened docling-project/docling-core#668 for it. This PR can't switch to application/vnd.box.boxnote until that's in a docling-core release though, since DocumentOrigin rejects the mime on the current floor (2.84.0), so I've kept application/json here with a comment and will flip it (and bump the floor) once it's released. I can hold this PR for that if you prefer!

DocumentOrigin rejects application/vnd.box.boxnote because it isn't in Python's mimetypes registry, so the Box Note backend in docling (docling-project/docling#3722) falls back to application/json. This registers it in _extra_mimetypes so the backend can use the correct mime. The list is also sorted alphabetically now. Signed-off-by: pablopupo <145598901+pablopupo@users.noreply.github.com>

PeterStaar-IBM

lgtm!

ceberam

Thanks @pablopupo for addressing all the comments!

If you could just fix the conflict that popped up on docs/usage/supported_formats.md by rebasing to main.

Box Notes (.boxnote) are JSON. This adds a declarative backend that reads the current ProseMirror-style "doc" schema, the format the Box Notes app exports today, and maps it onto a DoclingDocument: headings, paragraphs with bold/italic/underline/strikethrough and links, bullet, ordered and check lists, tables, code and images. Decoding is pure-Python (stdlib json), so no new dependency is added. Legacy notes (the pre-August-2022 atext/pool format that boxnotes2html parses) are detected and reported as unsupported rather than mis-parsed, and can follow in a later change. Registers InputFormat.BOXNOTE with a .boxnote extension and mime, wired to the SimplePipeline, with a unit test and a sample fixture. Resolves docling-project#481 Signed-off-by: pablopupo <145598901+pablopupo@users.noreply.github.com>

docling-core 2.86.0 registers application/vnd.box.boxnote in DocumentOrigin, so the interim application/json fallback is no longer needed. Raises the docling-core floor accordingly and regenerates the groundtruth. Signed-off-by: pablopupo <145598901+pablopupo@users.noreply.github.com>

pablopupo · 2026-07-06T16:36:33Z

Rebased on main and resolved the supported_formats.md conflict, both table rows are in now. BoxNote tests and the pre-commit hooks pass on the rebased branch.

ceberam

🚀

dolfim-ibm

lgtm

PeterStaar-IBM

lgtm!

PeterStaar-IBM requested review from PeterStaar-IBM and ceberam June 30, 2026 04:15

PeterStaar-IBM requested changes Jun 30, 2026

View reviewed changes

Comment thread docling/backend/boxnote_backend.py Outdated

Comment thread docling/backend/boxnote_backend.py Outdated

ceberam requested changes Jun 30, 2026

View reviewed changes

Comment thread docling/backend/boxnote_backend.py

Comment thread docling/backend/boxnote_backend.py Outdated

Comment thread docling/backend/boxnote_backend.py Outdated

Comment thread docling/backend/boxnote_backend.py Outdated

pablopupo force-pushed the feat/481-boxnote-backend branch from 0a8dc37 to eed5c2b Compare June 30, 2026 14:49

pablopupo mentioned this pull request Jun 30, 2026

feat(document): register the Box Note mime type docling-project/docling-core#668

Merged

pablopupo requested a review from ceberam July 3, 2026 02:29

PeterStaar-IBM previously approved these changes Jul 4, 2026

View reviewed changes

dolfim-ibm previously approved these changes Jul 6, 2026

View reviewed changes

ceberam reviewed Jul 6, 2026

View reviewed changes

pablopupo added 2 commits July 6, 2026 09:34

pablopupo dismissed stale reviews from dolfim-ibm and PeterStaar-IBM via 2aa17a1 July 6, 2026 16:36

pablopupo force-pushed the feat/481-boxnote-backend branch from ad7db49 to 2aa17a1 Compare July 6, 2026 16:36

ceberam approved these changes Jul 6, 2026

View reviewed changes

dolfim-ibm approved these changes Jul 7, 2026

View reviewed changes

PeterStaar-IBM approved these changes Jul 7, 2026

View reviewed changes

ceberam merged commit 4b4b9d8 into docling-project:main Jul 7, 2026
26 checks passed

Conversation

pablopupo commented Jun 29, 2026

Description

Changes

Tests

Uh oh!

github-actions Bot commented Jun 29, 2026

Uh oh!

mergify Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🟢 Enforce conventional commit

🟢 Require two reviewer for test updates

Uh oh!

PeterStaar-IBM left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

PeterStaar-IBM commented Jun 30, 2026

Uh oh!

codecov Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ceberam left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pablopupo commented Jun 30, 2026

Uh oh!

PeterStaar-IBM left a comment

Choose a reason for hiding this comment

Uh oh!

ceberam left a comment

Choose a reason for hiding this comment

Uh oh!

pablopupo commented Jul 6, 2026

Uh oh!

ceberam left a comment

Choose a reason for hiding this comment

Uh oh!

dolfim-ibm left a comment

Choose a reason for hiding this comment

Uh oh!

PeterStaar-IBM left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mergify Bot commented Jun 29, 2026 •

edited

Loading

codecov Bot commented Jun 30, 2026 •

edited

Loading