tiptap/docs/guide/output.md
Lode Claassen d31e49b03a
docs: Improve introducing examples in the documentation (#4334)
* skip 'like that' when we don't need it anyway

* change to 'like this' because it is before the example instead of after
2023-08-18 10:53:07 -07:00

6.0 KiB
Raw Blame History

tableOfContents
true

Output

Introduction

You can store your content as a JSON object or as a good old HTML string. Both work fine. And of course, you can pass both formats to the editor to restore your content. Here is an interactive example, that exports the content as HTML and JSON when the document is changed:

Export

Option 1: JSON

JSON is probably easier to loop through, for example to look for a mention and its 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 the content as JSON:

const json = editor.getJSON()

You can store that in your database (or send it to an API) and restore the document initially:

new Editor({
  content: {
    "type": "doc",
    "content": [
      // …
    ]
  },
})

Or if you need to wait for something, you can do it later through the editor instance:

editor.commands.setContent({
  "type": "doc",
  "content": [
    // …
  ]
})

Here is an interactive example where you can see that in action:

https://embed.tiptap.dev/preview/GuideContent/ExportJSON?hideSource

Option 2: HTML

HTML can be easily rendered in other places, for example in emails and its wildly used, so its probably easier to switch the editor at some point. Anyway, every editor instance provides a method to get HTML from the current document:

const html = editor.getHTML()

This can then be used to restore the document initially:

new Editor({
  content: `<p>Example Text</p>`,
})

Or if you want to restore the content later (e. g. after an API call has finished), you can do that too:

editor.commands.setContent(`<p>Example Text</p>`)

Use this interactive example to fiddle around:

https://embed.tiptap.dev/preview/GuideContent/ExportHTML?hideSource

Option 3: Y.js

Our editor has top notch support for Y.js, which is amazing to add features like realtime collaboration, offline editing, or syncing between devices.

Internally, Y.js stores a history of all changes. That can be in the browser, on a server, synced with other connected clients, or on a USB stick. But, its important to know that Y.js needs those stored changes. A simple JSON document is not enough to merge changes.

Sure, you can import existing JSON documents to get started and get a JSON out of Y.js, but thats more like an import/export format. It wont be your single source. Thats important to consider when adding Y.js for one of the mentioned use cases.

That said, its amazing and were about to provide an amazing backend, that makes all that a breeze.

Not an option: Markdown

Unfortunately, Tiptap doesnt support Markdown as an input or output format. We considered to add support for it, but those are the reasons why we decided to not do it:

  • Both, HTML and JSON, can have deeply nested structures, Markdown is flat.
  • Markdown standards vary.
  • Tiptaps strength is customization, that doesnt work very well with Markdown.
  • There are enough packages to convert HTML to Markdown and vice-versa.

You should really consider to work with HTML or JSON to store your content, they are perfectly fine for most use cases.

If you still think you need Markdown, ProseMirror has an example on how to deal with Markdown, Nextcloud Text uses Tiptap 1 to work with Markdown. Maybe you can learn from them. Or if you are looking for a really good Markdown editor, try CodeMirror.

That said, Tiptap does support Markdown shortcuts to format your content. Also youre free to let your content look like Markdown, for example add a # before an <h1> with CSS.

Listening for changes

If you want to continuously store the updated content while people write, you can hook into events. Here is an example how that could look like:

const editor = new Editor({
  // intial content
  content: `<p>Example Content</p>`,

  // triggered on every change
  onUpdate: ({ editor }) => {
    const json = editor.getJSON()
    // send the content to an API here
  },
})

Rendering

Option 1: Read-only instance of Tiptap

To render the saved content, set the editor to read-only. Thats how you can achieve the exact same rendering as its in the editor, without duplicating your CSS and other code.

https://embed.tiptap.dev/preview/GuideContent/ReadOnly

Option 2: Generate HTML from ProseMirror JSON

If you need to render the content on the server side, for example to generate the HTML for a blog post, which has been written in Tiptap, youll probably want to do just that without an actual editor instance.

Thats what the generateHTML() is for. Its a helper function which renders HTML without an actual editor instance.

https://embed.tiptap.dev/preview/GuideContent/GenerateHTML

By the way, the other way is possible, too. The below examples shows how to generate JSON from HTML.

https://embed.tiptap.dev/preview/GuideContent/GenerateJSON

Migration

If youre migrating existing content to Tiptap we would recommend to get your existing output to HTML. Thats probably the best format to get your initial content into Tiptap, because ProseMirror ensures there is nothing wrong with it. Even if there are some tags or attributes that arent allowed (based on your configuration), Tiptap just throws them away quietly.

Were about to go through a few cases to help with that, for example we provide a PHP package to convert HTML to a compatible JSON structure: ueberdosis/prosemirror-to-html.

Share your experiences with us! Wed like to add more information here.

Security

There is no reason to use one or the other because of security concerns. If someone wants to send malicious content to your server, it doesnt matter if its JSON or HTML. It doesnt even matter if youre using Tiptap or not. You should always validate user input.