Content
View differences
Updated by Hagen Mahnke 8 months ago
The import from and export to markdown is considered lossy, but we don't know what is lost in either direction.
Converting from BlockNote JSON to Y.doc binary should be lossless, but converting from Y.doc to BlockNote JSON will lose the editing history.
To check what will be lost and have data to confirm whether it's acceptable, build a proof of concept and run it with test data.
## Tasks
1. Build proof of concept for export from Y.doc to markdown
2. Build proof of concept for import from markdown to Y.doc
3. Build test data
1. export test data into markdown
2. import results from a into Y.doc
<br>
## Learnings
##
### Export to markdown via HTML
BlockNote's export to markdown works by exporting to HTML first and then to markdown. Loss of information is happening in this step, see comment on
`createExternalHTMLExporter` function in [externalHTMLExporter](https://github.com/TypeCellOS/BlockNote/blob/main/packages/core/src/api/exporters/html/externalHTMLExporter.ts#L31).
```text
// Used to export BlockNote blocks and ProseMirror nodes to HTML for use outside
// the editor. Blocks are exported using the `toExternalHTML` method in their
// `blockSpec`, or `toInternalHTML` if `toExternalHTML` is not defined.
//
// The HTML created by this serializer is different to what's rendered by the
// editor to the DOM. This also means that data is likely to be lost when
// converting back to original blocks. The differences in the output HTML are:
// 1. It doesn't include the `blockGroup` and `blockContainer` wrappers meaning
// that nesting is not preserved for non-list-item blocks.
// 2. `li` items in the output HTML are wrapped in `ul` or `ol` elements.
// 3. While nesting for list items is preserved, other types of blocks nested
// inside a list are un-nested and a new list is created after them.
// 4. The HTML is wrapped in a single `div` element.
```
Converting from BlockNote JSON to Y.doc binary should be lossless, but converting from Y.doc to BlockNote JSON will lose the editing history.
To check what will be lost and have data to confirm whether it's acceptable, build a proof of concept and run it with test data.
## Tasks
1. Build proof of concept for export from Y.doc to markdown
2. Build proof of concept for import from markdown to Y.doc
3. Build test data
1. export test data into markdown
2. import results from a into Y.doc
<br>
## Learnings
##
### Export to markdown via HTML
BlockNote's export to markdown works by exporting to HTML first and then to markdown. Loss of information is happening in this step, see comment on
`createExternalHTMLExporter` function in [externalHTMLExporter](https://github.com/TypeCellOS/BlockNote/blob/main/packages/core/src/api/exporters/html/externalHTMLExporter.ts#L31).
```text
// Used to export BlockNote blocks and ProseMirror nodes to HTML for use outside
// the editor. Blocks are exported using the `toExternalHTML` method in their
// `blockSpec`, or `toInternalHTML` if `toExternalHTML` is not defined.
//
// The HTML created by this serializer is different to what's rendered by the
// editor to the DOM. This also means that data is likely to be lost when
// converting back to original blocks. The differences in the output HTML are:
// 1. It doesn't include the `blockGroup` and `blockContainer` wrappers meaning
// that nesting is not preserved for non-list-item blocks.
// 2. `li` items in the output HTML are wrapped in `ul` or `ol` elements.
// 3. While nesting for list items is preserved, other types of blocks nested
// inside a list are un-nested and a new list is created after them.
// 4. The HTML is wrapped in a single `div` element.
```