docs: formats

Author: nperez0111

adr/2025_06_17-formats.md

@@ -0,0 +1,55 @@
+# BlockNote Formats
+
+Right now, there are several formats supported by BlockNote:
+
+- internal html (serialized html from the editor's schema) for things like clipboard handling
+- external html (a "normal" html format) for things like rendering to a blog
+- markdown
+- exported formats: docx, pdf, react
+
+There is a relationship between all of these formats:
+
+```ts
+/** The editor content */
+type Model = Block[] | InternalEditorState;
+
+type InternalHTML = string;
+function toInternalHTML(model: Model): InternalHTML;
+function fromInternalHTML(html: InternalHTML): Model;
+
+type ExternalHTML = string;
+function toExternalHTML(model: Model): ExternalHTML;
+function fromExternalHTML(html: ExternalHTML): Model;
+
+type Markdown = string;
+function toMarkdown(model: ExternalHTML): Markdown;
+function fromMarkdown(markdown: Markdown): Model;
+
+type Docx = Buffer;
+function toDocx(model: Model): Docx;
+
+type PDF = Buffer;
+function toPDF(model: Model): PDF;
+```
+
+You'll notice that the formats are all derived from the model.
+
+This gives us a unidirectional flow of data. Any other direction is potentially lossy (e.g. markdown -> model).
+
+## Internal vs. External HTML
+
+There are two representations of HTML:
+
+- The internal HTML format which is a serialized version of the editor's schema, without regard for normalization (e.g. list items will be nested oddly)
+  - Used for clipboard handling
+- The external HTML format which is a normalized version of the editor's schema, with list items nested "normally"
+
+The internal HTML format is "lossless", whereas the external HTML format is not
+
+Ideally we could avoid having to convert between the two formats, and just use the external HTML format as an output format.
+
+One idea to get closer to this, would be to have the clipboard instead use the model as the "internal" format, and then have the external HTML be a fallback for when the model would not be interpretable (such as by other applications).
+
+In an ideal world, we would only have a single html format, and it would be what is currently the "external" html format.
+
+See some earlier discussion about this: <https://github.com/TypeCellOS/BlockNote/issues/1583>