diff --git a/docs/src/demos/Examples/Book/content.js b/docs/src/demos/Examples/Book/content.js new file mode 100644 index 00000000..6371ff5c --- /dev/null +++ b/docs/src/demos/Examples/Book/content.js @@ -0,0 +1,4 @@ +export const content = ` +

Example

+

TODO

+` diff --git a/docs/src/demos/Examples/Book/index.spec.js b/docs/src/demos/Examples/Book/index.spec.js new file mode 100644 index 00000000..8403e1ff --- /dev/null +++ b/docs/src/demos/Examples/Book/index.spec.js @@ -0,0 +1,7 @@ +context('/examples/basic', () => { + before(() => { + cy.visit('/examples/basic') + }) + + // TODO: Write tests +}) diff --git a/docs/src/demos/Examples/Book/index.vue b/docs/src/demos/Examples/Book/index.vue new file mode 100644 index 00000000..44b31291 --- /dev/null +++ b/docs/src/demos/Examples/Book/index.vue @@ -0,0 +1,145 @@ + + + + + diff --git a/docs/src/demos/Examples/Links/index.spec.js b/docs/src/demos/Examples/Links/index.spec.js deleted file mode 100644 index 6a8317b5..00000000 --- a/docs/src/demos/Examples/Links/index.spec.js +++ /dev/null @@ -1,7 +0,0 @@ -context('/examples/links', () => { - before(() => { - cy.visit('/examples/links') - }) - - // TODO: Write tests -}) diff --git a/docs/src/demos/Examples/Links/index.vue b/docs/src/demos/Examples/Links/index.vue deleted file mode 100644 index 690a5e79..00000000 --- a/docs/src/demos/Examples/Links/index.vue +++ /dev/null @@ -1,80 +0,0 @@ - - - - - diff --git a/docs/src/demos/Examples/MarkdownShortcuts/index.vue b/docs/src/demos/Examples/MarkdownShortcuts/index.vue index c5f69fb3..59062178 100644 --- a/docs/src/demos/Examples/MarkdownShortcuts/index.vue +++ b/docs/src/demos/Examples/MarkdownShortcuts/index.vue @@ -7,6 +7,7 @@ + + diff --git a/docs/src/demos/Examples/ExportHtmlOrJson/index.spec.js b/docs/src/demos/Guide/StoreContent/ExportJSON/index.spec.js similarity index 67% rename from docs/src/demos/Examples/ExportHtmlOrJson/index.spec.js rename to docs/src/demos/Guide/StoreContent/ExportJSON/index.spec.js index 4e96f2a4..e4cb490a 100644 --- a/docs/src/demos/Examples/ExportHtmlOrJson/index.spec.js +++ b/docs/src/demos/Guide/StoreContent/ExportJSON/index.spec.js @@ -1,6 +1,6 @@ -context('/examples/export-html-or-json', () => { +context('/guide/store-content', () => { before(() => { - cy.visit('/examples/export-html-or-json') + cy.visit('/guide/store-content') }) beforeEach(() => { @@ -29,12 +29,4 @@ context('/examples/export-html-or-json', () => { }) }) }) - - it('should return html', () => { - cy.get('.ProseMirror').then(([{ editor }]) => { - const html = editor.getHTML() - - expect(html).to.equal('

Example Text

') - }) - }) }) diff --git a/docs/src/demos/Examples/ExportHtmlOrJson/index.vue b/docs/src/demos/Guide/StoreContent/ExportJSON/index.vue similarity index 80% rename from docs/src/demos/Examples/ExportHtmlOrJson/index.vue rename to docs/src/demos/Guide/StoreContent/ExportJSON/index.vue index cc17b2d2..63ccecb5 100644 --- a/docs/src/demos/Examples/ExportHtmlOrJson/index.vue +++ b/docs/src/demos/Guide/StoreContent/ExportJSON/index.vue @@ -18,8 +18,6 @@
-

HTML

-
{{ html }}

JSON

@@ -38,7 +36,6 @@ export default { return { editor: null, json: null, - html: null, } }, @@ -46,10 +43,7 @@ export default { this.editor = new Editor({ content: `

- What would be a text editor without content. At some point you want to get the content out of the editor and yes, we got you covered. There are two methods to export the current document as HTML or JSON. -

-

- You can hook into the update event to get the content after every single change. How cool is that? + Wow, this editor instance exports its content as JSON.

`, extensions: defaultExtensions(), @@ -57,18 +51,16 @@ export default { // Get the initial content … this.json = this.editor.getJSON() - this.html = this.editor.getHTML() // … and get the content after every change. this.editor.on('update', () => { this.json = this.editor.getJSON() - this.html = this.editor.getHTML() }) }, methods: { setContent() { - // You can pass a JSON document … + // You can pass a JSON document to the editor. this.editor.commands.setContent({ type: 'document', content: [{ @@ -82,9 +74,6 @@ export default { }], }, true) - // … but HTML strings are also supported. - // this.editor.setContent('

This is some inserted text. 👋

') - // It’s likely that you’d like to focus the Editor after most commands. this.editor.commands.focus() }, diff --git a/docs/src/demos/Examples/ReadOnly/index.spec.js b/docs/src/demos/Guide/StoreContent/ReadOnly/index.spec.js similarity index 87% rename from docs/src/demos/Examples/ReadOnly/index.spec.js rename to docs/src/demos/Guide/StoreContent/ReadOnly/index.spec.js index 2b1e4789..4b2d4b36 100644 --- a/docs/src/demos/Examples/ReadOnly/index.spec.js +++ b/docs/src/demos/Guide/StoreContent/ReadOnly/index.spec.js @@ -1,6 +1,6 @@ -context('/examples/read-only', () => { +context('/guide/store-content', () => { beforeEach(() => { - cy.visit('/examples/read-only') + cy.visit('/guide/store-content') }) it.skip('should be read-only', () => { diff --git a/docs/src/demos/Examples/ReadOnly/index.vue b/docs/src/demos/Guide/StoreContent/ReadOnly/index.vue similarity index 100% rename from docs/src/demos/Examples/ReadOnly/index.vue rename to docs/src/demos/Guide/StoreContent/ReadOnly/index.vue diff --git a/docs/src/docPages/examples/basic.md b/docs/src/docPages/examples/basic.md index c33b8158..00f923a6 100644 --- a/docs/src/docPages/examples/basic.md +++ b/docs/src/docPages/examples/basic.md @@ -1,3 +1,3 @@ -# Basic +# Basic text editor diff --git a/docs/src/docPages/examples/book.md b/docs/src/docPages/examples/book.md new file mode 100644 index 00000000..ca696161 --- /dev/null +++ b/docs/src/docPages/examples/book.md @@ -0,0 +1,3 @@ +# Write a book + + diff --git a/docs/src/docPages/examples/code-highlighting.md b/docs/src/docPages/examples/code-highlighting.md deleted file mode 100644 index 87f77d6f..00000000 --- a/docs/src/docPages/examples/code-highlighting.md +++ /dev/null @@ -1,3 +0,0 @@ -# Code Highlighting - - \ No newline at end of file diff --git a/docs/src/docPages/examples/drag-handle.md b/docs/src/docPages/examples/drag-handle.md deleted file mode 100644 index 858f193f..00000000 --- a/docs/src/docPages/examples/drag-handle.md +++ /dev/null @@ -1,3 +0,0 @@ -# Drag Handle - - diff --git a/docs/src/docPages/examples/embeds.md b/docs/src/docPages/examples/embeds.md deleted file mode 100644 index b6650b85..00000000 --- a/docs/src/docPages/examples/embeds.md +++ /dev/null @@ -1,3 +0,0 @@ -# Embeds - - \ No newline at end of file diff --git a/docs/src/docPages/examples/export-html-or-json.md b/docs/src/docPages/examples/export-html-or-json.md deleted file mode 100644 index 6a32ec1b..00000000 --- a/docs/src/docPages/examples/export-html-or-json.md +++ /dev/null @@ -1,3 +0,0 @@ -# Export HTML or JSON - - diff --git a/docs/src/docPages/examples/floating-menu.md b/docs/src/docPages/examples/floating-menu.md deleted file mode 100644 index ab15a33f..00000000 --- a/docs/src/docPages/examples/floating-menu.md +++ /dev/null @@ -1,3 +0,0 @@ -# Floating Menu - - \ No newline at end of file diff --git a/docs/src/docPages/examples/hiding-menu-bar.md b/docs/src/docPages/examples/hiding-menu-bar.md deleted file mode 100644 index 8ee88ba0..00000000 --- a/docs/src/docPages/examples/hiding-menu-bar.md +++ /dev/null @@ -1,3 +0,0 @@ -# Hiding Menu Bar - - \ No newline at end of file diff --git a/docs/src/docPages/examples/images.md b/docs/src/docPages/examples/images.md deleted file mode 100644 index 704cd2b7..00000000 --- a/docs/src/docPages/examples/images.md +++ /dev/null @@ -1,3 +0,0 @@ -# Images - - \ No newline at end of file diff --git a/docs/src/docPages/examples/links.md b/docs/src/docPages/examples/links.md deleted file mode 100644 index afc47c41..00000000 --- a/docs/src/docPages/examples/links.md +++ /dev/null @@ -1,3 +0,0 @@ -# Links - - diff --git a/docs/src/docPages/examples/menu-bubble.md b/docs/src/docPages/examples/menu-bubble.md deleted file mode 100644 index af2786ec..00000000 --- a/docs/src/docPages/examples/menu-bubble.md +++ /dev/null @@ -1,3 +0,0 @@ -# Menu Bubble - - \ No newline at end of file diff --git a/docs/src/docPages/examples/placeholder.md b/docs/src/docPages/examples/placeholder.md deleted file mode 100644 index b89aeaa8..00000000 --- a/docs/src/docPages/examples/placeholder.md +++ /dev/null @@ -1,3 +0,0 @@ -# Placeholder - - \ No newline at end of file diff --git a/docs/src/docPages/examples/read-only.md b/docs/src/docPages/examples/read-only.md deleted file mode 100644 index 048465a7..00000000 --- a/docs/src/docPages/examples/read-only.md +++ /dev/null @@ -1,3 +0,0 @@ -# Read-only - - diff --git a/docs/src/docPages/examples/search-and-replace.md b/docs/src/docPages/examples/search-and-replace.md deleted file mode 100644 index 8f091eb5..00000000 --- a/docs/src/docPages/examples/search-and-replace.md +++ /dev/null @@ -1,3 +0,0 @@ -# Search and Replace - - \ No newline at end of file diff --git a/docs/src/docPages/examples/suggestions.md b/docs/src/docPages/examples/suggestions.md deleted file mode 100644 index 875824a9..00000000 --- a/docs/src/docPages/examples/suggestions.md +++ /dev/null @@ -1,3 +0,0 @@ -# Suggestions - - \ No newline at end of file diff --git a/docs/src/docPages/examples/tables.md b/docs/src/docPages/examples/tables.md deleted file mode 100644 index 066bf657..00000000 --- a/docs/src/docPages/examples/tables.md +++ /dev/null @@ -1,3 +0,0 @@ -# Tables - - \ No newline at end of file diff --git a/docs/src/docPages/examples/title.md b/docs/src/docPages/examples/title.md deleted file mode 100644 index 935d87f2..00000000 --- a/docs/src/docPages/examples/title.md +++ /dev/null @@ -1,3 +0,0 @@ -# Title - - \ No newline at end of file diff --git a/docs/src/docPages/examples/todo-list.md b/docs/src/docPages/examples/todo-list.md deleted file mode 100644 index f93919a3..00000000 --- a/docs/src/docPages/examples/todo-list.md +++ /dev/null @@ -1,3 +0,0 @@ -# Todo List - - \ No newline at end of file diff --git a/docs/src/docPages/examples/trailing-paragraph.md b/docs/src/docPages/examples/trailing-paragraph.md deleted file mode 100644 index bc942b02..00000000 --- a/docs/src/docPages/examples/trailing-paragraph.md +++ /dev/null @@ -1,3 +0,0 @@ -# Trailing Paragraph - - \ No newline at end of file diff --git a/docs/src/docPages/guide/advanced-node-views.md b/docs/src/docPages/guide/node-views.md similarity index 74% rename from docs/src/docPages/guide/advanced-node-views.md rename to docs/src/docPages/guide/node-views.md index 207223e2..486b5d43 100644 --- a/docs/src/docPages/guide/advanced-node-views.md +++ b/docs/src/docPages/guide/node-views.md @@ -6,7 +6,9 @@ TODO -## Simple +## Different types of node views + +### Simple ```html
@@ -16,7 +18,7 @@ TODO
``` -## Without content +### Without content ```html
@@ -26,7 +28,7 @@ TODO
``` -## Advanced node views with content +### Advanced node views with content ```html
@@ -43,16 +45,7 @@ TODO
``` - diff --git a/docs/src/docPages/guide/store-content.md b/docs/src/docPages/guide/store-content.md index 8d62fbbf..c7a615bf 100644 --- a/docs/src/docPages/guide/store-content.md +++ b/docs/src/docPages/guide/store-content.md @@ -3,11 +3,11 @@ ## toc ## 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. +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: -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 do that, but tiptap wouldn’t care. +## Export -## Option 1: JSON +### Option 1: 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 the content as JSON: ```js @@ -18,19 +18,10 @@ You can store that in your database (or send it to an API) and restore the docum ```js new Editor({ - // … content: { "type": "document", "content": [ - { - "type": "paragraph", - "content": [ - { - "type": "text", - "text": "Example Text" - } - ] - } + // … ] }, }) @@ -42,20 +33,16 @@ Or if you need to wait for something, you can do it later through the editor ins editor.setContent({ "type": "document", "content": [ - { - "type": "paragraph", - "content": [ - { - "type": "text", - "text": "Example Text" - } - ] - } + // … ] }) ``` -## Option 2: HTML +Here is an interactive example where you can see that in action: + + + +### Option 2: 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 @@ -66,7 +53,6 @@ This can then be used to restore the document initially: ```js new Editor({ - // … content: `

Example Text

`, }) ``` @@ -76,7 +62,11 @@ Or if you want to restore the content later (e. g. after an API call has finishe editor.commands.setContent(`

Example Text

`) ``` -## Not an option: Markdown +Use this interactive example to fiddle around: + + + +### Not an option: Markdown Unfortunately, **tiptap doesn’t 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: @@ -90,10 +80,18 @@ If you still think you need Markdown, ProseMirror has an [example on how to deal That said, tiptap does support [Markdown shortcuts](/examples/markdown-shortcuts) to format your content. -## 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, you’ll probably want a way to do just that without an actual editor instance. +## Rendering -That’s what the `generateHTML()` is for. It’s a utility function that renders HTML without an actual editor instance. As an alternative, you can also use tiptap in a [read-only mode](/examples/read-only). +### Option 1: Read-only instance of tiptap + +To render the saved content, set the editor to read-only. That’s how you can achieve the exact same rendering as it’s in the editor, without duplicating your CSS and other code. + + + +### 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, you’ll probably want to do just that without an actual editor instance. + +That’s what the `generateHTML()` is for. It’s a helper function which renders HTML without an actual editor instance. :::info Browser-only rendering Import a lightweight implementation of `generateHTML()` from `@tiptap/core` if you’re using the function in a browser context only. diff --git a/docs/src/docPages/introduction.md b/docs/src/docPages/introduction.md index 289134b4..cee956e6 100644 --- a/docs/src/docPages/introduction.md +++ b/docs/src/docPages/introduction.md @@ -18,6 +18,9 @@ tiptap is a headless wrapper around [ProseMirror](https://ProseMirror.net) – a Create exactly the rich text editor you want out of customizable building blocks. tiptap comes with sensible defaults, a lot of extensions and a friendly API to customize every aspect. It’s backed by a welcoming community, open source, and free. +## Example + + ## Features **Headless.** We don’t tell you what a menu should look like or where it should be rendered in the DOM. That’s why tiptap is headless and comes without any CSS. You are in full control over markup, styling and behaviour. diff --git a/docs/src/links.yaml b/docs/src/links.yaml index 3ce72e60..189f2dc5 100644 --- a/docs/src/links.yaml +++ b/docs/src/links.yaml @@ -15,30 +15,23 @@ link: /examples redirect: /examples/basic items: - - title: Basic + - title: Basic text editor link: /examples/basic - title: Collaborative editing link: /examples/collaborative-editing pro: true - title: Markdown shortcuts link: /examples/markdown-shortcuts - # - title: Formatting - # link: /examples/formatting - # - title: Links - # link: /examples/links - - title: Todo App + - title: Formatting + link: /examples/formatting + - title: Todo app link: /examples/todo-app - # - title: Read-only - # link: /examples/read-only - # - title: Minimalist - # link: /examples/minimalist + - title: Write a book + link: /examples/book + - title: For minimalists + link: /examples/minimalist # - title: Use with v-model # link: /examples/v-model - # - title: Drag handle - # link: /examples/drag-handle - # draft: true - # - title: Export HTML or JSON - # link: /examples/export-html-or-json - title: Guide items: @@ -58,8 +51,8 @@ link: /guide/store-content - title: Build custom extensions link: /guide/build-custom-extensions - - title: Advanced node views - link: /guide/advanced-node-views + - title: Define node views + link: /guide/node-views draft: true - title: Working with TypeScript link: /guide/working-with-typescript