Example Text
+//Example Text
``` -That’s already enough to tell tiptap about the new attribute, and set `'pink'` as the default value. All attributes will be rendered as a data-attributes by default, and parsed as data-attributes from the content. +That’s already enough to tell tiptap about the new attribute, and set `'pink'` as the default value. All attributes will be rendered as a HTML attribute by default, and parsed as attributes from the content. Let’s stick with the color example and assume you’ll want to add an inline style to actually color the text. With the `renderHTML` function you can return HTML attributes which will be rendered in the output. @@ -123,10 +130,10 @@ const CustomParagraph = Paragraph.extend({ }) // Result: -//Example Text
+//Example Text
``` -You can also control how the attribute is parsed from the HTML. Let’s say you want to store the color in an attribute called `data-my-fancy-color-attribute`. Legit, right? Anyway, here’s how you would do that: +You can also control how the attribute is parsed from the HTML. Let’s say you want to store the color in an attribute called `data-color`, here’s how you would do that: ```js const CustomParagraph = Paragraph.extend({ @@ -137,13 +144,13 @@ const CustomParagraph = Paragraph.extend({ // Customize the HTML parsing (for example, to load the initial content) parseHTML: element => { return { - color: element.getAttribute('data-my-fancy-color-attribute'), + color: element.getAttribute('data-color'), } }, // … and customize the HTML rendering. renderHTML: attributes => { return { - 'data-my-fancy-color-attribute': atttributes.color, + 'data-color': atttributes.color, style: `color: ${attributes.color}`, } }, @@ -153,9 +160,11 @@ const CustomParagraph = Paragraph.extend({ }) // Result: -//Example Text
+//Example Text
``` +You can disable the rendering of attributes, if you pass `rendered: false`. + ### Global Attributes Attributes can be applied to multiple extensions at once. That’s useful for text alignment, line height, color, font family, and other styling related attributes. @@ -219,10 +228,46 @@ renderHTML({ attributes }) { ``` ### Parse HTML -> Associates DOM parser information with this mark (see the corresponding node spec field). The mark field in the rules is implied. +The `parseHTML()` function tries to load the editor document from HTML. The function gets the HTML DOM element passed as a parameter, and is expected to return an object with attributes and their values. Here is a simplified example from the [`Bold`](/api/marks/bold) mark: + +```js + parseHTML() { + return [ + { + tag: 'strong', + }, + ] + }, +``` + +This defines a rule to convert all `` tags to `Bold` marks. But you can get more advanced with this, here is the full example from the extension: + +```js + parseHTML() { + return [ + // + { + tag: 'strong', + }, + // + { + tag: 'b', + getAttrs: node => node.style.fontWeight !== 'normal' && null, + }, + // + { + style: 'font-weight', + getAttrs: value => /^(bold(er)?|[5-9]\d{2,})$/.test(value as string) && null, + }, + ] + }, +``` + +This looks for `` and `` tags, and any HTML tag with an inline style setting the `font-weight` to bold. + +As you can see, you can optionally pass a `getAttrs` callback, to add more complex checks, for example for specific HTML attributes. The callback gets passed the HTML DOM node, except when checking for the `style` attribute, then it’s the value. ### Commands - ```js import Paragraph from '@tiptap/extension-paragraph' @@ -254,7 +299,6 @@ const CustomBulletList = BulletList.extend({ ``` ### Input rules - ```js // Use the ~single tilde~ markdown shortcut import Strike from '@tiptap/extension-strike' @@ -272,7 +316,6 @@ const CustomStrike = Strike.extend({ ``` ### Paste rules - ```js // Overwrite the underline regex for pasted text import Underline from '@tiptap/extension-underline' @@ -289,17 +332,52 @@ const CustomUnderline = Underline.extend({ }) ``` -### Node views +### Node views (Advanced) +```js +import Link from '@tiptap/extension-underline' -## Option 2: Start from scratch +const CustomLink = Link.extend({ + addNodeView() { + return () => { + const container = document.createElement('div') -### Read the documentation -Although tiptap tries to hide most of the complexity of ProseMirror, it’s built on top of its APIs and we recommend you to read through the [ProseMirror Guide](https://ProseMirror.net/docs/guide/) for advanced usage. You’ll have a better understanding of how everything works under the hood and get more familiar with many terms and jargon used by tiptap. + container.addEventListener('change', event => { + alert('clicked on the container') + }) -### Have a look at existing extensions + return { + dom: container, + } + } + }, +}) +``` -### Get started +## Start from scratch -### Ask questions +### Create a node +```js +import { createNode } from '@tiptap/core' -### Share your extension +const CustomNode = createNode({ + // Your code goes here. +}) +``` + +### Create a mark +```js +import { createMark } from '@tiptap/core' + +const CustomMark = createMark({ + // Your code goes here. +}) +``` + +### Create an extension +```js +import { createExtension } from '@tiptap/core' + +const CustomExtension = createExtension({ + // Your code goes here. +}) +``` diff --git a/docs/src/docPages/sponsor.md b/docs/src/docPages/sponsor.md index 40a16564..53b11185 100644 --- a/docs/src/docPages/sponsor.md +++ b/docs/src/docPages/sponsor.md @@ -9,7 +9,7 @@ If you’re using tiptap in a commercial project or just want to give back to th * Your issues and pull requests get a `sponsor 💖` label * Get a sponsor badge in all your comments on GitHub * Show the support in your GitHub profile -* Receive monthly reports related to our open source work +* Receive monthly reports about to our open source work Does that sound good? [Sponsor us on GitHub!](https://github.com/sponsors/ueberdosis)