This is a radically reduced version of tiptap for minimalisits. It has only support for a document, paragraphs and text. That’s it.
', + content: ` ++ This is a radically reduced version of tiptap. It has only support for a document, paragraphs and text. That’s it. It’s probably too much for real minimalists though. +
++ The paragraph extension is not literally required, but you need at least one node. That node can be something different, for example to render a task list and only that task list. +
+ `, extensions: [ Document(), Paragraph(), diff --git a/docs/src/docPages/api/extensions/blockquote.md b/docs/src/docPages/api/extensions/blockquote.md index 392fb229..559faa11 100644 --- a/docs/src/docPages/api/extensions/blockquote.md +++ b/docs/src/docPages/api/extensions/blockquote.md @@ -1,7 +1,7 @@ # Blockquote The Blockquote extension enables you to use the `` HTML tag in the editor. This is great – you might have guessed – to use quotes in the editor. -Type `> ` at the beginning of a new line and it will be magically transformed to a blockquote. +Type `> ` at the beginning of a new line and it will be magically transformed to a blockquote. ## Options | Option | Type | Default | Description | diff --git a/docs/src/docPages/examples/simple.md b/docs/src/docPages/examples/simple.md index 7af42e80..681b3cbe 100644 --- a/docs/src/docPages/examples/simple.md +++ b/docs/src/docPages/examples/simple.md @@ -1,3 +1,3 @@ # Simple -\ No newline at end of file + \ No newline at end of file diff --git a/docs/src/docPages/guide/custom-styling.md b/docs/src/docPages/guide/custom-styling.md index 360d1d22..e80b2a92 100644 --- a/docs/src/docPages/guide/custom-styling.md +++ b/docs/src/docPages/guide/custom-styling.md @@ -1 +1,58 @@ -# Custom Styling \ No newline at end of file +# Custom styling +Tiptap is renderless, that doesn’t mean there is no styling provided. You can decided how your editor should look like. + +## Option 1: Styling the plain HTML +The content is rendered as HTML, so you can just use that to add styling: + +```css +p { + margin: 1em 0; +} +``` + +## Option 2: Adding custom classes everywhere +Every node has a `class` option, that you can use to add a custom class to the rendered HTML tag. + +```js +new Editor({ + extensions: [ + Document(), + Paragraph({ + class: 'my-custom-paragraph', + }), + Heading({ + class: 'my-custom-heading', + }), + Text(), + ] +}) +``` + +This will be the result then: + +```html + Example Text +
Wow, that’s really custom.
+``` + +## Option 3: Customizing the HTML markup +You can even customize the markup for every extension. This will make a custom bold extension that doesn’t render a `` tag, but a `` tag: + +```js +import Bold from '@tiptap/extension-bold' + +const CustomBold = Bold + .schema(() => ({ + toDOM: () => ['b', 0], + })) + .create() + +new Editor({ + extensions: [ + // … + CustomBold(), + ] +}) +``` + +You should put your custom extensions in separate files though, but I think you’ve got the idea. diff --git a/docs/src/docPages/guide/get-content.md b/docs/src/docPages/guide/get-content.md index 259392f0..4fdb19d9 100644 --- a/docs/src/docPages/guide/get-content.md +++ b/docs/src/docPages/guide/get-content.md @@ -1,14 +1,82 @@ -# Get Content +# Get content +You can store your content as JSON or you can get a good old HTML string. Both work fine. And of course, you can pass both formats to the editor to restore your content. -## Working with JSON +Funfact: You can store your content as JSON and restore the content from HTML, or the other way around. I don’t know why you would want to do that, but tiptap wouldn’t care. -## Working with HTML +## Option 1: Work with JSON +JSON is probably easier to loop through, for example to look for a mention and it’s more like what tiptap uses under the hood. Anyway, if you want to use JSON to store the content we provide a method to retrieve JSON: -## tiptap doesn’t work with Markdown +```js +const json = editor.json() +``` + +You can store that in your database or send it to an API and restore the document initially like that: + +```js +new Editor({ + // … + content: { + "type": "document", + "content": [ + { + "type": "paragraph", + "content": [ + { + "type": "text", + "text": "Example Text" + } + ] + } + ] + }, +}) +``` + +Or if you need to wait for something, you can do it later through the editor instance: + +```js +editor.setContent({ + "type": "document", + "content": [ + { + "type": "paragraph", + "content": [ + { + "type": "text", + "text": "Example Text" + } + ] + } + ] +}) +``` + +## Option 2: Work with HTML +HTML can be easily rendered in other places, for example in emails and it’s wildly used, so it’s probably easier to switch the editor at some point. Anyway, every editor instance provides a method to get HTML from the current document: + +```js +const html = editor.html() +``` + +This can then be used to restore the document initially: + +```js +new Editor({ + // … + content: `Example Text
`, +}) +``` + +Or if you want to restore the content later (e. g. after an API call has finished), you can do that too: +```js +editor.setContent(`Example Text
`) +``` + +## Not an option: Markdown Unfortunately, tiptap doesn’t support Markdown as input/output format. We considered to add support for it, but there are a few limitations: -* HTML or JSON can have deeply nested structures, Markdown not -* Tables are not part of the Markdown standard, and can’t be easily stored and restored from Markdown +* HTML and JSON can both have deeply nested structures, Markdown can’t have those +* Tables are not part of the Markdown standard, and can’t easily be stored and restored from Markdown -You should really consider to work with HTML or JSON to store your content. If you still think you need Markdown, Nextcloud uses tiptap to work with Markdown. There code is open source, so maybe you can learn from them. \ No newline at end of file +You should really consider to work with HTML or JSON to store your content. If you still think you need Markdown, [Nextcloud Text](https://github.com/nextcloud/text) uses tiptap to work with Markdown. Their code is open source, so maybe you can learn from them. diff --git a/docs/src/docPages/overview/upgrade-guide.md b/docs/src/docPages/overview/upgrade-guide.md index 665d294f..df195d26 100644 --- a/docs/src/docPages/overview/upgrade-guide.md +++ b/docs/src/docPages/overview/upgrade-guide.md @@ -58,3 +58,20 @@ const CustomExtension = … :::warning Breaking Change Currently, blockquotes must not be nested anymore. That said, we’re working on bringing it back. If you use nested blockquotes in your app, don’t upgrade yet. ::: + +### 5. Renamed API methods + +[We renamed a lot of commands](/api/commands), hopefully you can migrate to the new API with search & replace. Here is a list of what changed: + +| Old method name | New method name | +| --------------- | --------------- | +| ~~`getHTML`~~ | `html` | +| ~~`getJSON`~~ | `json` | + +### 6. .focus() isn’t called on every command anymore + +We tried to hide the `.focus()` command from you with tiptap 1 and executed that on every other command. That led to issues in specific use cases, where you want to run a command, but don’t want to focus the editor. With tiptap 2.x you have to explicitly call the `focus()` and you probably want to do that in a lot of places. Here is an example: + +```js +editor.focus().bold() +``` diff --git a/docs/src/links.yaml b/docs/src/links.yaml index 689b0c14..65987c8e 100644 --- a/docs/src/links.yaml +++ b/docs/src/links.yaml @@ -20,10 +20,8 @@ draft: true - title: Custom styling link: /guide/custom-styling - draft: true - title: Get content link: /guide/get-content - draft: true - title: Custom extensions link: /guide/custom-extensions draft: true