Add Documentation for html Property in Lexical Editor Configuration

[Kingscliq]

The html property in the Lexical editor configuration allows developers to add importDOM and exportDOM implementations directly, without needing node replacement. However, this property is currently undocumented, leading to a missed opportunity for users to utilize it effectively when working with HTML parsing and serialization in their editors.

Adding comprehensive documentation for the html property could benefit developers looking to manage HTML imports and exports, especially when aiming to integrate with other systems that rely on HTML or when handling complex content transformations.

Proposed Solution:

1. Update the Lexical documentation to include the html property in the editor configuration section.

2. Provide a brief example demonstrating the use of import and export with html.

Originally posted by @etrepum in #6532 (comment)

[Kingscliq]

Hi @etrepum I was going through the docs and want to be sure if this is similar to what I am trying to add to the documentation, or what I should be adding will be an addition to this?

Link

[etrepum]

Yes, exportDOM is similar to the html export config

lexical/packages/lexical/src/LexicalNode.ts

Lines 151 to 154 in e96ee55

	export type DOMExportOutputMap = Map<
	Klass<LexicalNode>,
	(editor: LexicalEditor, target: LexicalNode) => DOMExportOutput
	>;

lexical/packages/lexical/src/LexicalEditor.ts

Lines 173 to 188 in e96ee55

	export type HTMLConfig = {
	export?: DOMExportOutputMap;
	import?: DOMConversionMap;
	};
	export type CreateEditorArgs = {
	disableEvents?: boolean;
	editorState?: EditorState;
	namespace?: string;
	nodes?: ReadonlyArray<Klass<LexicalNode> | LexicalNodeReplacement>;
	onError?: ErrorHandler;
	parentEditor?: LexicalEditor;
	editable?: boolean;
	theme?: EditorThemeClasses;
	html?: HTMLConfig;
	};

There's also the import property which is similar to importDOM

[Kingscliq]

Yes, exportDOM is similar to the html export config

lexical/packages/lexical/src/LexicalNode.ts

Lines 151 to 154 in e96ee55

	export type DOMExportOutputMap = Map<
	Klass<LexicalNode>,
	(editor: LexicalEditor, target: LexicalNode) => DOMExportOutput
	>;

lexical/packages/lexical/src/LexicalEditor.ts

Lines 173 to 188 in e96ee55

	export type HTMLConfig = {
	export?: DOMExportOutputMap;
	import?: DOMConversionMap;
	};
	export type CreateEditorArgs = {
	disableEvents?: boolean;
	editorState?: EditorState;
	namespace?: string;
	nodes?: ReadonlyArray<Klass<LexicalNode> | LexicalNodeReplacement>;
	onError?: ErrorHandler;
	parentEditor?: LexicalEditor;
	editable?: boolean;
	theme?: EditorThemeClasses;
	html?: HTMLConfig;
	};

There's also the import property which is similar to importDOM

This is so cool, How did you do this?

[Kingscliq]

I mean, like referencing the files directly including the lines numbers and files

[Kingscliq]

So is it safe to day, it is documented already, I should go ahead and provide examples usage on the lexical-website package?

[etrepum]

The html property of the editor config (CreateEditorArgs) is not documented and it does not have any examples. It has two properties, import and export. import is similar to importDOM and export is similar to exportDOM.

[etrepum]

You can link to specific parts of a file on GitHub by clicking the line number and then shift-clicking another line number to select a range, then you click the […] button and copy the permalink. When you paste that permalink in a github issue/pr/discussion then its contents will be unfurled

[Kingscliq]

You can link to specific parts of a file on GitHub by clicking the line number and then shift-clicking another line number to select a range, then you click the […] button and copy the permalink. When you paste that permalink in a github issue/pr/discussion then its contents will be unfurled

Thanks for the tips

[Kingscliq]

The html property of the editor config (CreateEditorArgs) is not documented and it does not have any examples. It has two properties, import and export. import is similar to importDOM and export is similar to exportDOM.

Okay then, I will hop on it

[Kingscliq]

One more question, the changes I will be making should be on the should be on the lexical-website package right? which has been written with MarkDown all through, and for the example, can I put a link to the codesandbox or add to lexical-playground package.

Noot sure how to put this question, I hope its clear enough

[etrepum]

There are two places that this documentation can be added, one is directly in the source code via tsdoc/jsdoc block comments that get extracted by typedoc /** … */ and the other are the markdown files in lexical-website (the ones that are not automatically generated). It's up to you whether you choose to do one or both of those, any addition is a big improvement for a feature with no docs!

For an example of the feature I would recommend either adding it to one of the existing examples, the playground, or creating a new example project in the examples folder (which can be linked to in docs via stackblitz). Codesandbox examples are not great because they are not managed in the monorepo so they quickly become stale or stop working altogether when someone cleans up their account.

[Kingscliq]

There are two places that this documentation can be added, one is directly in the source code via tsdoc/jsdoc block comments that get extracted by typedoc /** … */ and the other are the markdown files in lexical-website (the ones that are not automatically generated). It's up to you whether you choose to do one or both of those, any addition is a big improvement for a feature with no docs!

For an example of the feature I would recommend either adding it to one of the existing examples, the playground, or creating a new example project in the examples folder (which can be linked to in docs via stackblitz). Codesandbox examples are not great because they are not managed in the monorepo so they quickly become stale or stop working altogether when someone cleans up their account.

This would be very helpful, thanks @etrepum

[Kingscliq]

Hi @etrepum, just before I raise a PR for this I wanted to be sure, I am putting the brief description and example in the right place

[etrepum]

I don't think that package is the best place to document it because you'd be using it from either lexical's createEditor or LexicalComposer's initialConfig. Maybe https://lexical.dev/docs/concepts/serialization would be the best place alongside other importDOM and exportDOM docs.

The example code in that screenshot is not correct at all, not sure if that is just a placeholder?

[Kingscliq]

I don't think that package is the best place to document it because you'd be using it from either lexical's createEditor or LexicalComposer's initialConfig. Maybe https://lexical.dev/docs/concepts/serialization would be the best place alongside other importDOM and exportDOM docs.

The example code in that screenshot is not correct at all, not sure if that is just a placeholder?

Got it! I am moving it to concepts/serialization.

yes, the example is a placeholder, I wanted to be sure that, that was the best place to put it or If I should put it in a different place. Then I also have a more concise doc for the HTML properties and the difference between the exportDOM/ importDOM properties and import/export. I need clarity on where to place the example

[Kingscliq]

I was also going throught the playground, wanted to ask about the exportDOM implementation. I left details on the screenshots @etrepum

[etrepum]

Yes that button triggers exportDOM, indirectly via $generateHtmlFromNodes. The exportDOM method is called on each node in the document to assemble the result. The html export config allows the method to be overridden without subclassing and node replacement.

[vadimkantorov]

Curious if slowness of export could be an issue for export as html as e.g. it is for export as markdown:

• Limitation/usecase discussion: playground hangs when converting to Markdown with an uploaded image of 1.1 megabyte because of doing base64 encoding on the UI thread and not in a WebWorker #6256

Images can take a lot of time to encode as base64, so having some solution for this might be good (e.g. allowing export as "virtual-urls" / hooks image export, so that the user can upload/manage images by themselves) and optionally somehow being able to do the export on a worker thread

[etrepum]

This issue doesn't really have anything to do with the bad strategy that the playground uses to represent images for demonstration purposes. If you were to change how it handles images, you would just modify that node's createDOM and exportDOM directly rather than configure exportDOM somewhere else. This configuration option is only relevant to exportDOM and importDOM (not createDOM) and is only useful for when you don't want to modify the class, but since that class isn't available on NPM and it would have to be copied into your project to use it there's no reason why you couldn't modify its exportDOM directly.