That’s a boring paragraph followed by a fenced code block:
++ That’s a boring paragraph followed by a fenced code block: +
for (var i=1; i <= 20; i++)
{
if (i % 15 == 0)
@@ -48,7 +50,9 @@ export default {
else
console.log(i);
}Press Command/Ctrl + Enter to leave the fenced code block and continue typing in boring paragraphs. +
+ Press Command/Ctrl + Enter to leave the fenced code block and continue typing in boring paragraphs. +
`, }) }, diff --git a/docs/src/demos/React/index.jsx b/docs/src/demos/React/index.jsx index 71974c17..734aad7a 100644 --- a/docs/src/demos/React/index.jsx +++ b/docs/src/demos/React/index.jsx @@ -57,7 +57,7 @@ export default () => {` 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 magically transform to a blockquote. + +## Installation +```bash +# With npm +npm install @tiptap/extension-blockquote + +# Or: With Yarn +yarn add @tiptap/extension-blockquote +``` ## Options | Option | Type | Default | Description | @@ -17,7 +26,7 @@ Type `> ` at the beginning of a new line and it will be magically transformed * Windows & Linux: `Control` + `Shift` + `9` * macOS: `Command` + `Shift` + `9` -## Source Code +## Source code [packages/extension-blockquote/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-blockquote/) ## Usage diff --git a/docs/src/docPages/api/extensions/bold.md b/docs/src/docPages/api/extensions/bold.md index c3a7e75d..b9005f1c 100644 --- a/docs/src/docPages/api/extensions/bold.md +++ b/docs/src/docPages/api/extensions/bold.md @@ -1,7 +1,7 @@ # Bold Use this extension to render text in **bold**. If you pass ``, `` tags, or text with inline `style` attributes setting the `font-weight` CSS rule in the editor’s initial content, they all will be rendered accordingly. -Type `**two asterisks**` or `__two underlines__` and it will be magically transformed to **bold** text while you type. +Type `**two asterisks**` or `__two underlines__` and it will magically transform to **bold** text while you type. ::: warning Restrictions The extension will generate the corresponding `` HTML tags when reading contents of the `Editor` instance. All text marked bold, regardless of the method will be normalized to `` HTML tags. @@ -21,7 +21,7 @@ The extension will generate the corresponding `` HTML tags when reading * Windows & Linux: `Control` + `B` * macOS: `Command` + `B` -## Source Code +## Source code [packages/extension-bold/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bold/) ## Usage diff --git a/docs/src/docPages/api/extensions/bullet-list.md b/docs/src/docPages/api/extensions/bullet-list.md index 2a68f14f..34ffa757 100644 --- a/docs/src/docPages/api/extensions/bullet-list.md +++ b/docs/src/docPages/api/extensions/bullet-list.md @@ -1,7 +1,7 @@ # BulletList This extension enables you to use bullet lists in the editor. They are rendered as `` HTML tags, -Type `* `, `- ` or `+ ` at the beginning of a new line and it will be magically transformed to a bullet list. +Type `* `, `- ` or `+ ` at the beginning of a new line and it will magically transform to a bullet list. ::: warning Use with ListItem The `BulletList` extension is intended to be used with the [`ListItem`](/api/extensions/list-item) extension. Make sure to import that one too, otherwise you’ll get a SyntaxError. @@ -20,7 +20,7 @@ The `BulletList` extension is intended to be used with the [`ListItem`](/api/ext ## Keyboard shortcuts * `Control` + `Shift` + `8` -## Source Code +## Source code [packages/extension-bullet-list/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/) ## Usage diff --git a/docs/src/docPages/api/extensions/code-block.md b/docs/src/docPages/api/extensions/code-block.md index 3edc00be..69b70f4f 100644 --- a/docs/src/docPages/api/extensions/code-block.md +++ b/docs/src/docPages/api/extensions/code-block.md @@ -20,7 +20,7 @@ The CodeBlock extension doesn’t come with styling and has no syntax highlighti ## Keyboard shortcuts * `Shift` + `Control` + `\` -## Source Code +## Source code [packages/extension-code-block/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code-block/) ## Usage diff --git a/docs/src/docPages/api/extensions/code.md b/docs/src/docPages/api/extensions/code.md index 33303010..d6329a16 100644 --- a/docs/src/docPages/api/extensions/code.md +++ b/docs/src/docPages/api/extensions/code.md @@ -1,7 +1,7 @@ # Code The Code extensions enables you to use the `
` HTML tag in the editor. If you paste in text with `` tags it will rendered accordingly. -Type something with \`back-ticks around\` and it will be magically transformed to `inline code` while you type. +Type something with \`back-ticks around\` and it will magically transform to `inline code` while you type. ## Options | Option | Type | Default | Description | @@ -16,7 +16,7 @@ Type something with \`back-ticks around\` and it will be magically transformed t ## Keyboard shortcuts * `Alt` + ` -## Source Code +## Source code [packages/extension-code/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code/) ## Usage diff --git a/docs/src/docPages/api/extensions/document.md b/docs/src/docPages/api/extensions/document.md index 017eec5b..2ac899a5 100644 --- a/docs/src/docPages/api/extensions/document.md +++ b/docs/src/docPages/api/extensions/document.md @@ -7,7 +7,7 @@ The node is very tiny though. It defines a name of the node (`document`), is con Tiptap 1 tried to hide that node from you, but it has always been there. A tiny, but important change though: **We renamed the default type from `doc` to `document`.** To keep it like that, use your own implementation of the `Document` node or migrate the stored JSON to use the new name. ::: -## Source Code +## Source code [packages/extension-document/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-document/) ## Usage diff --git a/docs/src/docPages/api/extensions/hard-break.md b/docs/src/docPages/api/extensions/hard-break.md index 7b47bf98..1bf9c857 100644 --- a/docs/src/docPages/api/extensions/hard-break.md +++ b/docs/src/docPages/api/extensions/hard-break.md @@ -14,7 +14,7 @@ The HardBreak extensions adds support for the `
` HTML tag, which forces a li * Windows & Linux: `Control` + `Enter` * macOS: `Command` + `Enter` -## Source Code +## Source code [packages/extension-hard-break/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-hard-break/) ## Usage diff --git a/docs/src/docPages/api/extensions/heading.md b/docs/src/docPages/api/extensions/heading.md index a6087725..26cf08c3 100644 --- a/docs/src/docPages/api/extensions/heading.md +++ b/docs/src/docPages/api/extensions/heading.md @@ -1,7 +1,7 @@ # Heading The Heading extension adds support for headings of different levels. Headings are rendered with ``, `
`, `
`, `
`, `
` or `
` HTML tags. By default all six headline levels are enabled, but you can pass an array to only allow a few levels. Check the usage example to see how this is done. -Type `# ` at the beginning of a new line and it will be magically transformed to a headline, same for `## `, `### `, `#### `, `##### ` and `###### `. +Type `# ` at the beginning of a new line and it will magically transform to a headline, same for `## `, `### `, `#### `, `##### ` and `###### `. ## Options | Option | Type | Default | Description | @@ -22,7 +22,7 @@ Type `# ` at the beginning of a new line and it will be magically transformed * `Control` + `Shift` + `5` → H5 * `Control` + `Shift` + `6` → H6 -## Source Code +## Source code [packages/extension-heading/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-heading/) ## Usage diff --git a/docs/src/docPages/api/extensions/history.md b/docs/src/docPages/api/extensions/history.md index a4900072..9009198f 100644 --- a/docs/src/docPages/api/extensions/history.md +++ b/docs/src/docPages/api/extensions/history.md @@ -18,7 +18,7 @@ This extension provides history support. All changes to the document will be tra * Windows & Linux: `Shift` + `Control` + `Z` * macOS: `Shift` + `Command` + `Z` -## Source Code +## Source code [packages/extension-history/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-history/) ## Usage diff --git a/docs/src/docPages/api/extensions/horizontal-rule.md b/docs/src/docPages/api/extensions/horizontal-rule.md index f2a496f3..e5c9c26d 100644 --- a/docs/src/docPages/api/extensions/horizontal-rule.md +++ b/docs/src/docPages/api/extensions/horizontal-rule.md @@ -1,7 +1,7 @@ # HorizontalRule Use this extension to render a `
` HTML tag. If you pass `
` in the editor’s initial content, it’ll be rendered accordingly. -Type three dashes (`---`) or three underscores and a space (`___ `) at the beginning of a new line and it will be magically transformed to a horizontal rule. +Type three dashes (`---`) or three underscores and a space (`___ `) at the beginning of a new line and it will magically transform to a horizontal rule. ## Options | Option | Type | Default | Description | @@ -16,7 +16,7 @@ Type three dashes (`---`) or three underscores and a space (`___ `) at the be ## Keyboard shortcuts *None* -## Source Code +## Source code [packages/extension-horizontal-rule/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-horizontal-rule/) ## Usage diff --git a/docs/src/docPages/api/extensions/italic.md b/docs/src/docPages/api/extensions/italic.md index 398f725e..9d2f57c8 100644 --- a/docs/src/docPages/api/extensions/italic.md +++ b/docs/src/docPages/api/extensions/italic.md @@ -19,7 +19,7 @@ The extension will generate the corresponding `` HTML tags when reading cont * Windows & Linux: `Control` + `I` * macOS: `Command` + `I` -## Source Code +## Source code [packages/extension-italic/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-italic/) ## Usage diff --git a/docs/src/docPages/api/extensions/paragraph.md b/docs/src/docPages/api/extensions/paragraph.md index b6326538..3ab58b99 100644 --- a/docs/src/docPages/api/extensions/paragraph.md +++ b/docs/src/docPages/api/extensions/paragraph.md @@ -12,7 +12,7 @@ Yes, the schema is very strict. Without this extension you won’t even be able ## Keyboard shortcuts *None* -## Source Code +## Source code [packages/extension-paragraph/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-paragraph/) ## Usage diff --git a/docs/src/docPages/api/extensions/strike.md b/docs/src/docPages/api/extensions/strike.md index 36913e65..9da05886 100644 --- a/docs/src/docPages/api/extensions/strike.md +++ b/docs/src/docPages/api/extensions/strike.md @@ -21,7 +21,7 @@ The extension will generate the corresponding `` HTML tags when reading conte * Windows & Linux: `Control` + `D` * macOS: `Command` + `D` -## Source Code +## Source code [packages/extension-strike/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-strike/) ## Usage diff --git a/docs/src/docPages/api/extensions/text.md b/docs/src/docPages/api/extensions/text.md index 4e256c44..53a67f0e 100644 --- a/docs/src/docPages/api/extensions/text.md +++ b/docs/src/docPages/api/extensions/text.md @@ -5,7 +5,7 @@ Tiptap 1 tried to hide that node from you, but it has always been there. ::: -## Source Code +## Source code [packages/extension-text/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-text/) ## Usage diff --git a/docs/src/docPages/api/extensions/underline.md b/docs/src/docPages/api/extensions/underline.md index ab27c3ce..0aa359b9 100644 --- a/docs/src/docPages/api/extensions/underline.md +++ b/docs/src/docPages/api/extensions/underline.md @@ -19,7 +19,7 @@ The extension will generate the corresponding `` HTML tags when reading conte * Windows & Linux: `Control` + `U` * macOS: `Command` + `U` -## Source Code +## Source code [packages/extension-underline/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-underline/) ## Usage diff --git a/docs/src/docPages/guide/custom-extensions.md b/docs/src/docPages/guide/custom-extensions.md index 84c4caee..0431fd3e 100644 --- a/docs/src/docPages/guide/custom-extensions.md +++ b/docs/src/docPages/guide/custom-extensions.md @@ -1 +1,31 @@ -# Custom Extensions \ No newline at end of file +# Custom Extensions + +Let’s extend tiptap with a custom extension! + +## Option 1: Change defaults + +Let’s say you want to change the keyboard shortcuts for the bullet list. You should start by looking at [the source code of the `Bold` extension](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bold/index.ts) and find the default you’d like to change. In that case, the keyboard shortcut. + +```js +// 1. Import the extension +import BulletList from '@tiptap/extension-bullet-list' + +// 2. Overwrite the keyboard shortcuts +const CustomBulletList = new Node() + .keys(({ editor }) => ({ + 'Mod-l': () => editor.bulletList(), + })) + .create() // Don’t forget that! + +// 3. Add the custom extension to your editor +new Editor({ + extensions: [ + CustomBulletList(), + // … + ] +}) +``` + +## Option 2: Extend existing extensions + +## Option 3: Start from scratch \ 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 e80b2a92..962da01e 100644 --- a/docs/src/docPages/guide/custom-styling.md +++ b/docs/src/docPages/guide/custom-styling.md @@ -1,19 +1,31 @@ # 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: +## Option 1: Style the plain HTML +The whole editor is rendered inside of a container with the class `.ProseMirror`. You can use that to scope your styling to the editor content: ```css +/* Scoped to the editor */ +.ProseMirror p { + margin: 1em 0; +} +``` + +If you’re rendering the stored content somewhere, there won’t be a `.ProseMirror` container, so you can just globally add styling to the used HTML tags: + +```css +/* Global styling */ 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. + +## Option 2: Add custom classes +Most extensions have a `class` option, which you can use to add a custom CSS class to the HTML tag. ```js +/* Add custom classes */ new Editor({ extensions: [ Document(), @@ -28,17 +40,18 @@ new Editor({ }) ``` -This will be the result then: +The rendered HTML will look like that: ```htmlExample Text
Wow, that’s really custom.
``` -## Option 3: Customizing the HTML markup +## Option 3: Customize the HTML 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 +/* Customizing the markup */ import Bold from '@tiptap/extension-bold' const CustomBold = Bold diff --git a/docs/src/docPages/guide/getting-started.md b/docs/src/docPages/guide/getting-started.md index 00dc0565..dcade3d5 100644 --- a/docs/src/docPages/guide/getting-started.md +++ b/docs/src/docPages/guide/getting-started.md @@ -27,7 +27,3 @@ If you are using Nuxt.js, note that tiptap needs to run in the client, not on th ::: Congrats! You’ve got it! 🎉 Let’s start to configure your editor in the next step. - -### Related links - -* [tiptap doesn’t have a default styling](#) diff --git a/docs/src/docPages/guide/get-content.md b/docs/src/docPages/guide/store-content.md similarity index 64% rename from docs/src/docPages/guide/get-content.md rename to docs/src/docPages/guide/store-content.md index 4fdb19d9..a94c533e 100644 --- a/docs/src/docPages/guide/get-content.md +++ b/docs/src/docPages/guide/store-content.md @@ -1,16 +1,16 @@ -# 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. +# Store 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. -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. +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. -## 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: +## 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 const json = editor.json() ``` -You can store that in your database or send it to an API and restore the document initially like that: +You can store that in your database (or send it to an API) and restore the document initially like that: ```js new Editor({ @@ -51,7 +51,7 @@ editor.setContent({ }) ``` -## Option 2: Work with HTML +## 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 @@ -74,9 +74,13 @@ 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: +Unfortunately, **tiptap doesn’t support Markdown as an input or output format**. We considered to add support for it, but there are a few limitations: * 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 Text](https://github.com/nextcloud/text) uses tiptap to work with Markdown. Their code is open source, so maybe you can learn from them. +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, [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. + +That said, tiptap **does** support Markdown shortcuts to format your content. Try typing `**two asterisk**` to make your text bold for example. \ No newline at end of file diff --git a/docs/src/docPages/introduction.md b/docs/src/docPages/introduction.md index 33b4710d..1f56e8e7 100644 --- a/docs/src/docPages/introduction.md +++ b/docs/src/docPages/introduction.md @@ -1,16 +1,25 @@ +:::warning Don’t try this at home +This version of tiptap is not production-ready, don’t use it anywhere. +::: + # Introduction -tiptap is a renderless wrapper around [ProseMirror](https://ProseMirror.net) – a toolkit for building rich-text editors that are already in use at many well-known companies such as *New York Times*, *The Guardian* or *Atlassian*. -Although tiptap tries to hide most of the complexity of ProseMirror, it’s is built on top of its APIs and we strongly recommend you to read through the [ProseMirror Guide](https://ProseMirror.net/docs/guide/). You’ll have a better understanding of how everything works under the hood and get familiar with many terms and jargon used by tiptap. +[](https://www.npmjs.com/package/@tiptap/core) +[](https://npmcharts.com/compare/@tiptap/core?minimal=true) +[](https://www.npmjs.com/package/@tiptap/core) +[](https://github.com/sponsors/ueberdosis) -## Renderless -The implementation of a text editor can be very specific for each use case. We don’t want to tell you what a menu should look like or where it should be rendered in the DOM. That’s why tiptap is renderless and comes without any CSS. You’ll have full control over markup and styling. +tiptap is a renderless wrapper around [ProseMirror](https://ProseMirror.net) – a toolkit for building rich-text editors that is already in use at many well-known companies such as *New York Times*, *The Guardian* or *Atlassian*. -## TypeScript -Tiptap 2 is written in TypeScript. That gives you a nice autocomplete for the API (if your IDE supports those), helps us to find bugs early and makes it possible to generate [a complete API documentation](#) on top of the extensive human written 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. -## Framework-agnostic -We don’t care what framework you use. Tiptap is ready to be used with plain JavaScript, Vue.js or React. That makes it even possible to write a renderer for Svelte and others. +## Features + +**Renderless.** 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 renderless and comes without any CSS. You are in full control over markup and styling. + +**Framework-agnostic.** We don’t care what framework you use. Tiptap is ready to be used with plain JavaScript, Vue.js or React. That makes it even possible to write a renderer for Svelte and others. + +**TypeScript.** Tiptap 2 is written in TypeScript. That gives you a nice autocomplete for the API (if your IDE for it), helps to find bugs early and makes it possible to generate [a complete API documentation](#) on top of the extensive human written documentation. ## Who uses tiptap? - [GitLab](https://gitlab.com) @@ -19,5 +28,4 @@ We don’t care what framework you use. Tiptap is ready to be used with plain Ja - [ApostropheCMS](https://apostrophecms.com) - [Directus CMS](https://directus.io) - [Nextcloud](https://apps.nextcloud.com/apps/text) -- [Craft CMS](https://craftcms.com/) - [and many more →](https://github.com/ueberdosis/tiptap/network/dependents?package_id=UGFja2FnZS0xMzE5OTg0ODc%3D) diff --git a/docs/src/docPages/overview/contributing.md b/docs/src/docPages/overview/contributing.md index 63c8e4e0..db621d2d 100644 --- a/docs/src/docPages/overview/contributing.md +++ b/docs/src/docPages/overview/contributing.md @@ -1,8 +1,8 @@ # Contributing -Tiptap would be nothing, without its lively community. Contributions have always been and will always be welcome. Here is a little bit you should know, before you send your contributions: +Tiptap would be nothing without its lively community. Contributions have always been and will always be welcome. Here is a little bit you should know, before you send your contribution: -## What kind of contributions are welcome +## Examples * Improved documentation, e. g. fixing typos, new sections, further explanation …) * New features for existing extensions, e. g. a new option diff --git a/docs/src/docPages/overview/installation.md b/docs/src/docPages/overview/installation.md index 0384cf60..6165b073 100644 --- a/docs/src/docPages/overview/installation.md +++ b/docs/src/docPages/overview/installation.md @@ -1,10 +1,16 @@ # Installation -tiptap has a very modular package structure and is independent of any framework. Depending on what you want to do with tiptap there are a few different ways to install tiptap in your project. Choose the way that fits your project best. +You’re free to use tiptap with the framework of your choice. Depending on what you want to do, there are a few different ways to install tiptap in your project. Choose the way that fits your workflow. -## Plain JavaScript +## Overview -Use tiptap with vanilla JavaScript for a very lightweight and raw experience. If you feel like it, you can even use it to connect the tiptap core with other frameworks not mentioned here. +- [Option 1: Vanilla JavaScript](#option-1-vanilla-javascript) +- [Option 2: Vue.js](#option-2-vuejs) +- [Option 3: CodeSandbox](#option-3-codesandbox) + +## Option 1: Vanilla JavaScript + +Use tiptap with vanilla JavaScript for a very lightweight and raw experience. If you feel like it, you can even use it to connect tiptap with other frameworks not mentioned here. ```bash # With npm @@ -14,6 +20,11 @@ npm install @tiptap/core @tiptap/starter-kit yarn add @tiptap/core @tiptap/starter-kit ``` +| Package | Description | +| ---------------------------------------------------------------------------- | -------------------------- | +| [@tiptap/core](https://www.npmjs.com/package/@tiptap/core) | The actual editor | +| [@tiptap/starter-kit](https://www.npmjs.com/package/@tiptap/vue-starter-kit) | The most common extensions | + Great, that should be enough to start. Here is the most essential code you need to get a running instance of tiptap: ```js @@ -27,26 +38,32 @@ new Editor({ }) ``` -## Vue.js +## Option 2: Vue.js -To use tiptap with Vue.js (and tools that are based on Vue.js) install the Vue.js adapter in your project: +To use tiptap with Vue.js (and tools that are based on Vue.js) install tiptap together with the Vue.js rendering adapter in your project. We even prepared a Vue.js starter kit, which gives you a good headstart. ```bash # With npm -npm install @tiptap/vue @tiptap/vue-starter-kit +npm install @tiptap/core @tiptap/vue @tiptap/vue-starter-kit # Or: With Yarn -yarn add @tiptap/vue @tiptap/vue-starter-kit +yarn add @tiptap/core @tiptap/vue @tiptap/vue-starter-kit ``` -We even prepared a Vue.js starter kit for you. That should give you a good headstart. Create a new component and add the following content to get a basic version of tiptap: +| Package | Description | +| -------------------------------------------------------------------------------- | --------------------------------------------- | +| [@tiptap/core](https://www.npmjs.com/package/@tiptap/core) | The actual editor | +| [@tiptap/vue](https://www.npmjs.com/package/@tiptap/vue) | Rendering for Vue.js | +| [@tiptap/vue-starter-kit](https://www.npmjs.com/package/@tiptap/vue-starter-kit) | The most common extensions wrapped for Vue.js | + +Create a new component and add the following content to get a basic version of tiptap:-## CodeSandbox +## Option 3: CodeSandbox -CodeSandbox is an online coding environment. It’s great to fiddle around without setting up a local project and it’s great to share your code with others. +CodeSandbox is an online coding environment. It’s great to fiddle around without setting up a local project and to share your code with others. -It’s also amazing for bug reports. Try to recreate a bug there and share it with us before you [file an issue on GitHub](https://github.com/ueberdosis/tiptap-next/issues/new). This helps a ton to fix bugs faster. +It’s also amazing for bug reports. Found it a bug? Try to recreate it there and share it with us before you [file an issue on GitHub](https://github.com/ueberdosis/tiptap-next/issues/new). That helps to fix bugs faster. * [Vue.js/tiptap on CodeSandbox](https://codesandbox.io/s/vue-issue-template-h0g28) diff --git a/docs/src/docPages/overview/upgrade-guide.md b/docs/src/docPages/overview/upgrade-guide.md index 1fb70bdb..27b89540 100644 --- a/docs/src/docPages/overview/upgrade-guide.md +++ b/docs/src/docPages/overview/upgrade-guide.md @@ -1,19 +1,20 @@ # Upgrade Guide ## Reasons to upgrade to tiptap 2.x -* autocomplete in your IDE (thanks to TypeScript) -* an amazing documentation with 100+ pages -* active development, new features in the making -* tons of new extensions planned -* well-tested code base +Yes, it’s tedious work to upgrade your favorite text editor to a new API, but we made sure you’ve got enough reasons to upgrade to the newest version + +* Autocomplete in your IDE (thanks to TypeScript) +* Amazing documentation with 100+ pages +* Active development, new features in the making +* Tons of new extensions planned +* Well-tested code base ## Upgrading from 1.x to 2.x - The new API will look pretty familiar too you, but there are a ton of changes though. To make the upgrade a little bit easier, here is everything you need to know: ### 1. Explicitly register the Document, Text and Paragraph extensions -Tiptap 1 tried to hide a few required extensions from you. Be sure to explicitly import the [Document](/api/extensions/document), [Paragraph](/api/extensions/paragraph) and [Text](/api/extensions/text) extensions. +Tiptap 1 tried to hide a few required extensions from you with the default setting `useBuiltInExtensions: true`. That setting has been removed and you’re required to import all extensions. Be sure to explicitly import at least the [Document](/api/extensions/document), [Paragraph](/api/extensions/paragraph) and [Text](/api/extensions/text) extensions. ```js import Document from '@tiptap/extension-document' @@ -25,16 +26,19 @@ new Editor({ Document(), Paragraph(), Text(), - … + // all your other extensions ] }) ``` + + ### 2. New document type **We renamed the default `Document` type from `doc` to `document`.** To keep it like that, use your own implementation of the `Document` node or migrate the stored JSON to use the new name. ```js import Document from '@tiptap/extension-document' + const CustomDocument = Document.name('doc').create() new Editor({ @@ -46,13 +50,36 @@ new Editor({ ``` ### 3. New extension API - -In case you’ve built some custom extensions for your project, you’ll need to rewrite them to fit the new API. No worries, though, you can keep a lot of your work though. The schema, commands, keys, inputRules, pasteRules all work like they did before. It’s just different how you register them. +In case you’ve built some custom extensions for your project, you’re required to rewrite them to fit the new API. No worries, you can keep a lot of your work though. The `schema`, `commands`, `keys`, `inputRules` and `pasteRules` all work like they did before. It’s just different how you register them. ```js -const CustomExtension = … +import { Node } from '@tiptap/core' + +const CustomExtension = new Node() + .name('custom_extension') + .defaults({ + // … + }) + .schema(() => ({ + // … + })) + .commands(({ editor, name }) => ({ + // … + })) + .keys(({ editor }) => ({ + // … + })) + .inputRules(({ type }) => [ + // … + ]) + .pasteRules(({ type }) => [ + // … + ]) + .create() ``` +Don’t forget to call `create()` in the end! Read more about [all the nifty details building custom extensions](/guide/custom-extensions) in our guide. + ### 4. Blockquotes must not be nested anymore :::warning Breaking Change diff --git a/docs/src/layouts/App/index.vue b/docs/src/layouts/App/index.vue index 84b0e317..c0da1990 100644 --- a/docs/src/layouts/App/index.vue +++ b/docs/src/layouts/App/index.vue @@ -107,15 +107,10 @@ export default { return this.$route.matched[0].path }, editLink () { - let path = this.currentPath + const currentPath = this.currentPath + const filePath = currentPath === '' ? '/introduction' : currentPath - if (path === '') { - path = 'docs/src/pages/Index.vue' - } else { - path = `docs/src/docPages${path}.md` - } - - return `https://github.com/ueberdosis/tiptap-next/blob/main/${path}` + return `https://github.com/ueberdosis/tiptap-next/blob/main/docs/src/docPages${filePath}.md` }, }, diff --git a/docs/src/links.yaml b/docs/src/links.yaml index 65987c8e..0024f707 100644 --- a/docs/src/links.yaml +++ b/docs/src/links.yaml @@ -20,8 +20,8 @@ draft: true - title: Custom styling link: /guide/custom-styling - - title: Get content - link: /guide/get-content + - title: Store content + link: /guide/store-content - title: Custom extensions link: /guide/custom-extensions draft: true @@ -98,7 +98,6 @@ items: - title: Editor link: /api/editor/ - draft: true - title: Extensions link: /api/extensions/ items: