feature: file exporters

[YousefED]

This PR adds the concept of Exporters to BlockNote. An Exporter is a loosely coupled, type safe way to transform documents from BlockNote-style JSON to another format (for example, .pdf and .docx).

Demo for PDF: https://blocknote-git-feature-file-exporters-typecell.vercel.app/interoperability/converting-blocks-to-pdf
Demo for Word: https://blocknote-git-feature-file-exporters-typecell.vercel.app/interoperability/converting-blocks-to-docx

Requirements

• Exporters can be defined in separate packages. i.e.: if you don't need docx export functionality, you don't need to include any docx related dependencies
• Exporters are type-safe, even for custom schemas. So for example, when trying to export a document with a custom schema using the default exporters, you'll get a type error (as you're trying to transform a document with an exporter that might not support all content in your document)
• Exporters are customizable: the consumer can customize how certain types of content (i.e.: blocks, inline content, styles) are transformed
• It needs to be possible to easily make changes to the "output document". For example; add custom headers / footers
• TBD: It would be nice of we can add support for manual page breaks

Architecture

As a reminder, the BlockNote schema consists of 3 main types: blocks, inline content, and styles (see docs). First, exporters define a mapping for each of them. Exporters run Blocks (BlockNote JSON) through the mappings to get a new, "transformed" document.

Note: Client-side vs. Server-side

In the current setup, we have chosen to make Exporters work completely client-side. This has the following benefits:

• no server needs to be able to see / touch your data (i.e.: support for E2EE)
• complete control over the exported files. Because we generate pdf / docx files "from the ground up"; we should be able to control every single aspect of the exported files. If we'd go for a JSON -> HTML -> Docx / pdf approach using a "3rd party" HTML -> DocX / PDF exporter,

The main downside of this approach is that we'll need to write custom exporters for each file type, instead of creating 1 exporter to HTML and letting third party libraries handle the HTML -> Docx and HTML -> pdf exporting separately. However, it's likely that this approach would also run into limitations or a lot of custom HTML fiddling to make sure the "HTML -> xxx" converter works well.

Docx

The Docx exporter uses the docxJs to create .docx files

PDF

The PDF exporter uses https://react-pdf.org to create .pdf files. I've also looked at the following libraries:

• pdfmake, but ran into this issue
• https://github.com/parallax/jsPDF rich text not as simple, no declarative api
• pdfkit looks solid but react-pdf builds an easier declarative syntax on top of it, including easy support for rich text ( elements that are nestable)

TODO

The current PR is a proof of concept and produces valid pdf and docx files. Now, the main next step is to get as close as possible to the BlockNote "design" as possible for both pdf and docx. This means supporting all types of blocks, inline content, and styles and make sure things like font, font size, line height are similar to the BlockNote defaults (yet, stay customizable)

TODO:
general:

• video / audio / files (TBD)
• image downloader to fix CORS issues
• colors
• docs
• separate packages
• create abstract class?
• add tests, for example with output file snapshots
• "templating" options (i.e.: customize document from outside)
• (nice to have) multi-level bullet list indentation styles (change from solid to open dot to square etc) (nice to have?)
• bug: support both strike and underline for same text

Re. files, audio, video
Support for audio / video in pdf / word either doesn't exist or requires quite a bit of research (i.e.: how to embed audio / video in a word document). An "MVP" might just be to insert an icon and a link to the external file, instead of an item with preview / interactivity

pdf

• add symbol font for checklists
• emojis
• image widths, captions
• alignment / bg color / ... (block container props) and create complete test document with all possible blocknote elements
• more tests
• fix table widths (nice to have?)

DocX

• demo
• fonts (docx.js issue?)
• lists
• images
• image caption style
• hyperlink style

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
blocknote	✅ Ready (Inspect)	Visit Preview	Oct 24, 2024 5:47am
blocknote-website	✅ Ready (Inspect)	Visit Preview	Oct 24, 2024 5:47am