[lexical-website] Documentation Update: Add Documentation for html Property in Lexical Editor Configuration

[Kingscliq]

Description

• Updated the Lexical documentation to include the html property in the editor configuration section.
• Provided a brief example demonstrating the use of import and export with html.

Closes #6762

Test plan

Before

The html property in CreateEditorArgs is undocumented, lacking examples for its import and export properties. These functions have similar functionality to importDOM and exportDOM but are undocumented, creating ambiguity for users looking to extend or customize HTML handling.

After

The html property is now fully documented, with examples illustrating the import and export properties. The import property demonstrates mappings for transforming HTML elements into Lexical nodes, while export shows how to convert nodes back to HTML. These examples provide clarity and guide users in extending or customizing their editor’s HTML handling, building on the concepts of importDOM and exportDOM.

[vercel]

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

Name	Status	Preview	Comments	Updated (UTC)
lexical	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 5, 2024 7:39pm
lexical-playground	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 5, 2024 7:39pm

[github-actions]

size-limit report 📦

Path	Size
lexical - cjs	29.92 KB (0%)
lexical - esm	29.78 KB (0%)
@lexical/rich-text - cjs	38.57 KB (0%)
@lexical/rich-text - esm	31.63 KB (0%)
@lexical/plain-text - cjs	37.22 KB (0%)
@lexical/plain-text - esm	28.94 KB (0%)
@lexical/react - cjs	40.33 KB (0%)
@lexical/react - esm	33.06 KB (0%)

[etrepum]

Was this written with ChatGPT or something like that? The code example doesn't really seem close to correct. I would recommend writing an example of this functionality in one of the example packages or the playground so you can verify that the types are correct and it behaves as expected. The theme usage isn't relevant here, I'd remove that.

[Kingscliq]

Was this written with ChatGPT or something like that? The code example doesn't really seem close to correct. I would recommend writing an example of this functionality in one of the example packages or the playground so you can verify that the types are correct and it behaves as expected. The theme usage isn't relevant here, I'd remove that.

Thanks for the feedback @etrepum , I will create an example I think that's probably the best way to verify the functionality.

Quick question though, can I use the pattern for the exportDom feature on the playground, like a button that calls the html.export() assuming that's how it is called to behave exactly like the exportDom feature, I highlighted earlier

[etrepum]

If you were using the playground, or another example that has the debug tree view, then the "Export DOM" button is sufficient. You don't need to add any additional UI. Only the configuration passed to createEditor or LexicalComposer would change to add the html property. The whole purpose is that this configuration can be used to alter the behavior of existing export functionality.

What the example would do is provide some configuration that makes it so some node (or perhaps multiple nodes) have a different output than their default exportDOM implementation. If this is configured correctly, then the change would be apparent in the tree view after clicking Export DOM. The export HTML output can also be observed by copying text from the editor and then pasting it somewhere to see the text/html content such as https://evercoder.github.io/clipboard-inspector/

Possibly a simple and useful example would be some configuration that removes style from the default output. <span style="white-space: pre-wrap;">Welcome to the playground</span> is how a TextNode in the playground is exported, but maybe the example could change that to <span>Welcome to the playground</span>

[Kingscliq]

> If you were using the playground, or another example that has the debug tree view, then the "Export DOM" button is sufficient. You don't need to add any additional UI. Only the configuration passed to createEditor or LexicalComposer would change to add the html property. The whole purpose is that this configuration can be used to alter the behavior of existing export functionality.

What the example would do is provide some configuration that makes it so some node (or perhaps multiple nodes) have a different output than their default exportDOM implementation. If this is configured correctly, then the change would be apparent in the tree view after clicking Export DOM. The export HTML output can also be observed by copying text from the editor and then pasting it somewhere to see the text/html content such as https://evercoder.github.io/clipboard-inspector/

Possibly a simple and useful example would be some configuration that removes style from the default output. <span style="white-space: pre-wrap;">Welcome to the playground</span> is how a TextNode in the playground is exported, but maybe the example could change that to <span>Welcome to the playground</span>

Got it! Just scanning through the examples dir, so do you suggest I create a new installation or use an already existing installation, from what I am seeing I think the react-rich dir is quite okay for what I am trying to achieve, what do you think?

I noticed that the TreeViewPlugin isn’t directly editable from the examples, as it’s part of an installed package. To modify it, I’d need to make changes within the lexical-react package itself if I want my examples to work with the React package. The same approach would apply to the lexical-playground. Could you confirm if the examples package and similar dependencies pull changes directly from the monorepo files, or if publishing is required before these changes are accessible?

[etrepum]

You don't need to touch the TreeViewPlugin. Its "Export DOM" functionality does exactly the right thing to demonstrate this without any modification. The only thing you will need to change is the configuration passed to createEditor or LexicalComposer.

Any of the examples is fine, or the playground.

[Kingscliq]

You don't need to touch the TreeViewPlugin. Its "Export DOM" functionality does exactly the right thing to demonstrate this without any modification. The only thing you will need to change is the configuration passed to createEditor or LexicalComposer.

Any of the examples is fine, or the playground.

Okay, got it!, I will go through the LexicalComposer API and see how I can update the configuration

[Kingscliq]

Hi @etrepum I was going through the source and realized that LexicalComposer was used in a lot of places, which means I can create a new react application with a new LexicalComposer Instance and ensure that I add the html attribute to the to the configuration and pass it as initialConfig on the LexicalComposer do you think it will overwrite the exportDOM called on the TreeView plugin?

Just like we have in

import {AutoFocusPlugin} from '@lexical/react/LexicalAutoFocusPlugin';
import {LexicalComposer} from '@lexical/react/LexicalComposer';
import {ContentEditable} from '@lexical/react/LexicalContentEditable';
import {LexicalErrorBoundary} from '@lexical/react/LexicalErrorBoundary';
import {HistoryPlugin} from '@lexical/react/LexicalHistoryPlugin';
import {RichTextPlugin} from '@lexical/react/LexicalRichTextPlugin';

import ExampleTheme from './ExampleTheme';
import ToolbarPlugin from './plugins/ToolbarPlugin';
import TreeViewPlugin from './plugins/TreeViewPlugin';

const placeholder = 'Enter some rich text...';

const editorConfig = {
  namespace: 'React.js Demo',
  nodes: [],
  // Handling of errors during update
  onError(error: Error) {
    throw error;
  },
  // The editor theme
  theme: ExampleTheme,
};

export default function App() {
  return (
    <LexicalComposer initialConfig={editorConfig}>
      <div className="editor-container">
        <ToolbarPlugin />
        <div className="editor-inner">
          <RichTextPlugin
            contentEditable={
              <ContentEditable
                className="editor-input"
                aria-placeholder={placeholder}
                placeholder={
                  <div className="editor-placeholder">{placeholder}</div>
                }
              />
            }
            ErrorBoundary={LexicalErrorBoundary}
          />
          <HistoryPlugin />
          <AutoFocusPlugin />
          <TreeViewPlugin />
        </div>
      </div>
    </LexicalComposer>
  );
}

I got this from examples/react-rich

[etrepum]

Yes, if the html property is set on that initialConfig then any effect its export property has would be observable from the TreeViewPlugin or the clipboard.

[Kingscliq]

Yes, if the html property is set on that initialConfig then any effect its export property has would be observable from the TreeViewPlugin or the clipboard.

okay! thanks, will do that then.

Can I create a new react-app on the examples folder?, what name do I give it(is there a convention for naming)?, or do I link a stackblitz URL to the .md file that have the field documented?

[Kingscliq]

I realized there was no color palette or fontSize on the toolbar so I will have that implemented to test the behaviour of the configuration

[etrepum]

I think this is very close! For the example to be helpful we need to link to it from the documentation, otherwise people won't know to look here

[Kingscliq]

I think this is very close! For the example to be helpful we need to link to it from the documentation, otherwise people won't know to look here

got it!

[Kingscliq]

Updated with a link to the example @etrepum