ianhitchman/tiptap
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: use regular case for Tiptap

Browse Source
This commit is contained in:
Hans Pagel
2021-10-19 22:30:45 +02:00
parent 3fe97621e7
commit f45c8d0ca7
77 changed files with 203 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/guide/accessibility.md
View File

@@ -5,11 +5,11 @@ tableOfContents: true
# Accessibility
:::pro Fund the development ♥
We need your support to maintain, update, support and develop tiptap. If you’re waiting for progress here, [become a sponsor and fund our work](/sponsor).
We need your support to maintain, update, support and develop Tiptap. If you’re waiting for progress here, [become a sponsor and fund our work](/sponsor).
:::
## Introduction
We strive to make tiptap accessible to everyone, but to be honest, there’s not much work done now. From our current understanding, that’s what needs to be done:
We strive to make Tiptap accessible to everyone, but to be honest, there’s not much work done now. From our current understanding, that’s what needs to be done:
## Interface
An interface needs to have well-defined contrasts, big enough click areas, semantic markup, must be keyboard accessible and well documented. Currently, we don’t even provide an interface, so for now that’s totally up to you.
@@ -17,7 +17,7 @@ An interface needs to have well-defined contrasts, big enough click areas, seman
But no worries, we’ll provide an interface soon and take accessibility into account early on.
## Output
The editor needs to produce semantic markup, must be keyboard accessible and well documented. The tiptap content is well structured so that’s a good foundation already. That said, we can add support and encourage the usage of additional attributes, for example the Alt-attribute for images.
The editor needs to produce semantic markup, must be keyboard accessible and well documented. The Tiptap content is well structured so that’s a good foundation already. That said, we can add support and encourage the usage of additional attributes, for example the Alt-attribute for images.
### Writing assistance (optional)
An optional writing assitance could help people writing content semanticly correct, for example pointing out an incorrect usage of heading levels. With that kind of assistance provided by the core developers, we could help to improve the content of a lot of applications.

22
docs/guide/collaborative-editing.md
View File

@@ -5,10 +5,10 @@ tableOfContents: true
# Collaborative editing
## Introduction
Real-time collaboration, syncing between different devices and working offline used to be hard. We provide everything you need to keep everything in sync, conflict-free with the power of [Y.js](https://github.com/yjs/yjs). The following guide explains all things to take into account when you consider to make tiptap collaborative. Don’t worry, a production-grade setup doesn’t require much code.
Real-time collaboration, syncing between different devices and working offline used to be hard. We provide everything you need to keep everything in sync, conflict-free with the power of [Y.js](https://github.com/yjs/yjs). The following guide explains all things to take into account when you consider to make Tiptap collaborative. Don’t worry, a production-grade setup doesn’t require much code.
## Configure the editor
The underyling schema tiptap uses is an excellent foundation to sync documents. With the [`Collaboration`](/api/extensions/collaboration) you can tell tiptap to track changes to the document with [Y.js](https://github.com/yjs/yjs).
The underyling schema Tiptap uses is an excellent foundation to sync documents. With the [`Collaboration`](/api/extensions/collaboration) you can tell Tiptap to track changes to the document with [Y.js](https://github.com/yjs/yjs).
Y.js is a conflict-free replicated data types implementation, or in other words: It’s reaaally good in merging changes. And to achieve that, changes don’t have to come in order. It’s totally fine to change a document while being offline and merge it with other changes when the device is online again.
@@ -27,7 +27,7 @@ npm install @tiptap/extension-collaboration yjs y-webrtc
yarn add @tiptap/extension-collaboration yjs y-webrtc
```
Now, create a new Y document, and register it with tiptap:
Now, create a new Y document, and register it with Tiptap:
```js
import { Editor } from '@tiptap/core'
@@ -43,7 +43,7 @@ const provider = new WebrtcProvider('example-document', ydoc)
const editor = new Editor({
extensions: [
// …
// Register the document with tiptap
// Register the document with Tiptap
Collaboration.configure({
document: ydoc,
}),
@@ -51,7 +51,7 @@ const editor = new Editor({
})
```
This should be enough to create a collaborative instance of tiptap. Crazy, isn’t it? Try it out, and open the editor in two different browsers. Changes should be synced between different windows.
This should be enough to create a collaborative instance of Tiptap. Crazy, isn’t it? Try it out, and open the editor in two different browsers. Changes should be synced between different windows.
So how does this magic work? All clients need to connect with eachother, that’s the job of a *provider*. The [WebRTC provider](https://github.com/yjs/y-webrtc) is the easiest way to get started with, as it requires a public server to connect clients directly with each other, but not to sync the actual changes. This has two downsides, though.
@@ -71,7 +71,7 @@ npm install @tiptap/extension-collaboration yjs y-websocket
yarn add @tiptap/extension-collaboration yjs y-websocket
```
And then register the WebSocket provider with tiptap:
And then register the WebSocket provider with Tiptap:
```js
import { Editor } from '@tiptap/core'
@@ -87,7 +87,7 @@ const provider = new WebsocketProvider('ws://127.0.0.1:1234', 'example-document'
const editor = new Editor({
extensions: [
// …
// Register the document with tiptap
// Register the document with Tiptap
Collaboration.configure({
document: ydoc,
}),
@@ -135,7 +135,7 @@ node ./index.js
<!-- TODO: This should output something like “Listening on ws://127.0.0.1:1234”. -->
Try opening http://127.0.0.1:1234 in your browser. You should see a plain text `OK` if everything works fine.
Go back to your tiptap editor and hit reload, it should now connect to the WebSocket server and changes should sync with all other clients. Amazing, isn’t it?
Go back to your Tiptap editor and hit reload, it should now connect to the WebSocket server and changes should sync with all other clients. Amazing, isn’t it?
### Multiple network providers
You can even combine multiple providers. That’s not needed, but could keep clients connected, even if one connection - for example the WebSocket server - goes down for a while. Here is an example:
@@ -239,7 +239,7 @@ In the backend, you can split the string to know the user is typing on a page wi
And if you’d like to sync multiple fields with one Y.js document, just pass different fragment names to the collaboration extension:
```js
// a tiptap instance for the field
// a Tiptap instance for the field
Collaboration.configure({
document: ydoc,
field: 'title',
@@ -354,11 +354,11 @@ hocuspocus.listen()
### Schema updates
tiptap is very strict with the [schema](/api/schema), that means, if you add something that’s not allowed according to the configured schema it’ll be thrown away. That can lead to a strange behaviour when multiple clients with different schemas share changes to a document.
Let’s say you added an editor to your app and the first people use it already. They have all a loaded instance of tiptap with all default extensions, and therefor a schema that only allows those. But you want to add task lists in the next update, so you add the extension and deploy again.
Let’s say you added an editor to your app and the first people use it already. They have all a loaded instance of Tiptap with all default extensions, and therefor a schema that only allows those. But you want to add task lists in the next update, so you add the extension and deploy again.
A new user opens your app and has the updated schema (with task lists), while all others still have the old schema (without task lists). The new user checks out the newly added tasks lists and adds it to a document to show that feature to other users in that document. But then, it magically disappears right after she added it. What happened?
When one user adds a new node (or mark), that change will be synced to all other connected clients. The other connected clients apply those changes to the editor, and tiptap, strict as it is, removes the newly added node, because it’s not allowed according to their (old) schema. Those changes will be synced to other connected clients and oops, it’s removed everywhere. To avoid this you have a few options:
When one user adds a new node (or mark), that change will be synced to all other connected clients. The other connected clients apply those changes to the editor, and Tiptap, strict as it is, removes the newly added node, because it’s not allowed according to their (old) schema. Those changes will be synced to other connected clients and oops, it’s removed everywhere. To avoid this you have a few options:
1. Never change the schema (not cool).
2. Force clients to update when you deploy a new schema (tough).

6
docs/guide/configuration.md
View File

@@ -5,7 +5,7 @@ tableOfContents: true
# Configuration
## Introduction
For most cases it’s enough to say where tiptap should be rendered (`element`), what functionalities you want to enable (`extensions`) and what the initial document should be (`content`).
For most cases it’s enough to say where Tiptap should be rendered (`element`), what functionalities you want to enable (`extensions`) and what the initial document should be (`content`).
A few more things can be configured though. Let’s look at a fully configured editor example.
@@ -34,7 +34,7 @@ new Editor({
This will do the following:
1. bind tiptap to `.element`,
1. bind Tiptap to `.element`,
2. load the `Document`, `Paragraph` and `Text` extensions,
3. set the initial content,
4. place the cursor in the editor after initialization,
@@ -63,7 +63,7 @@ new Editor({
```
### Configure extensions
Most extensions can be configured. Add a `.configure()` and pass an object to it.
Most extensions can be configured. Add a `.configure()` and pass an object to it.
The following example will disable the default heading levels 4, 5 and 6 and just allow 1, 2 and 3:

14
docs/guide/custom-extensions.md
View File

@@ -5,7 +5,7 @@ tableOfContents: true
# Custom extensions
## Introduction
One of the strengths of tiptap is its extendability. You don’t depend on the provided extensions, it is intended to extend the editor to your liking.
One of the strengths of Tiptap is its extendability. You don’t depend on the provided extensions, it is intended to extend the editor to your liking.
With custom extensions you can add new content types and new functionalities, on top of what already exists or from scratch. Let’s start with a few common examples of how you can extend existing nodes, marks and extensions.
@@ -65,7 +65,7 @@ The order in which extensions are loaded influences two things:
The [`Link`](/api/marks/link) mark for example has a higher priority, which means it will be rendered as `<a href="…"><strong>Example</strong></a>` instead of `<strong><a href="…">Example</a></strong>`.
### Settings
All settings can be configured through the extension anyway, but if you want to change the default settings, for example to provide a library on top of tiptap for other developers, you can do it like that:
All settings can be configured through the extension anyway, but if you want to change the default settings, for example to provide a library on top of Tiptap for other developers, you can do it like that:
```js
import Heading from '@tiptap/extension-heading'
@@ -124,7 +124,7 @@ const CustomParagraph = Paragraph.extend({
// <p color="pink">Example Text</p>
```
That is 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 from the content when initiated.
That is 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 from the content when initiated.
Let’s stick with the color example and assume you 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.
@@ -486,10 +486,10 @@ this.parent
```
### ProseMirror Plugins (Advanced)
After all, tiptap is built on ProseMirror and ProseMirror has a pretty powerful plugin API, too. To access that directly, use `addProseMirrorPlugins()`.
After all, Tiptap is built on ProseMirror and ProseMirror has a pretty powerful plugin API, too. To access that directly, use `addProseMirrorPlugins()`.
#### Existing plugins
You can wrap existing ProseMirror plugins in tiptap extensions like shown in the example below.
You can wrap existing ProseMirror plugins in Tiptap extensions like shown in the example below.
```js
import { history } from 'prosemirror-history'
@@ -507,7 +507,7 @@ const History = Extension.create({
#### Access the ProseMirror API
To hook into events, for example a click, double click or when content is pasted, you can pass [event handlers](https://prosemirror.net/docs/ref/#view.EditorProps) to `editorProps` on the [editor](/api/editor#editor-props).
Or you can add them to a tiptap extension like shown in the below example.
Or you can add them to a Tiptap extension like shown in the below example.
```js
import { Extension } from '@tiptap/core'
@@ -596,7 +596,7 @@ const CustomMark = Mark.create({
```
### Create an extension
Extensions add new capabilities to tiptap and you’ll read the word extension here very often, even for nodes and marks. But there are literal extensions. Those can’t add to the schema (like marks and nodes do), but can add functionality or change the behaviour of the editor.
Extensions add new capabilities to Tiptap and you’ll read the word extension here very often, even for nodes and marks. But there are literal extensions. Those can’t add to the schema (like marks and nodes do), but can add functionality or change the behaviour of the editor.
A good example to learn from is probably [`TextAlign`](/api/extensions/text-align).

2
docs/guide/menus.md
View File

@@ -46,7 +46,7 @@ Oh, that’s a long command, right? Actually, it’s a [chain of commands](/api/
editor.chain().focus().toggleBold().run()
```
1. `editor` should be a tiptap instance,
1. `editor` should be a Tiptap instance,
2. `chain()` is used to tell the editor you want to execute multiple commands,
3. `focus()` sets the focus back to the editor,
4. `toggleBold()` marks the selected text bold, or removes the bold mark from the text selection if it’s already applied and

8
docs/guide/node-views.md
View File

@@ -7,7 +7,7 @@ tableOfContents: true
## Introduction
Node views are the best thing since sliced bread, at least if you are a fan of customization (and bread). With node views you can add interactive nodes to your editor. That can literally be everything. If you can write it in JavaScript, you can use it in your editor.
Node views are amazing to improve the in-editor experience, but can also be used in a read-only instance of tiptap. They are unrelated to the HTML output by design, so you have full control about the in-editor experience *and* the output.
Node views are amazing to improve the in-editor experience, but can also be used in a read-only instance of Tiptap. They are unrelated to the HTML output by design, so you have full control about the in-editor experience *and* the output.
## Different types of node views
Depending on what you would like to build, node views work a little bit different and can have their verify specific capabilities, but also pitfalls. The main question is: How should your custom node look like?
@@ -40,7 +40,7 @@ tiptap adds a `contenteditable="false"` to those by default.
That’s how you could render mentions, which shouldn’t be editable. Users can add or delete them, but not delete single characters.
Statamic uses those for their Bard editor, which renders complex modules inside tiptap, which can have their own text inputs.
Statamic uses those for their Bard editor, which renders complex modules inside Tiptap, which can have their own text inputs.
### Mixed content
You can even mix non-editable and editable text. That’s great to build complex things, and still use marks like bold and italic inside the editable content.
@@ -63,7 +63,7 @@ You can even mix non-editable and editable text. That’s great to build complex
```
## Markup
But what happens if you [access the editor content](/guide/output)? If you’re working with HTML, you’ll need to tell tiptap how your node should be serialized.
But what happens if you [access the editor content](/guide/output)? If you’re working with HTML, you’ll need to tell Tiptap how your node should be serialized.
The editor **does not** export the rendered JavaScript node, and for a lot of use cases you wouldn’t want that anyway.
@@ -104,7 +104,7 @@ parseHTML() {
```
### Render JavaScript/Vue/React
But what if you want to render your actual JavaScript/Vue/React code? Consider using tiptap to render your output. Just set the editor to `editable: false` and no one will notice you’re using an editor to render the content. :-)
But what if you want to render your actual JavaScript/Vue/React code? Consider using Tiptap to render your output. Just set the editor to `editable: false` and no one will notice you’re using an editor to render the content. :-)
<!-- ## Reference

4
docs/guide/node-views/js.md
View File

@@ -13,7 +13,7 @@ Here is what you need to do to render a node view inside your editor:
1. [Create a node extension](/guide/custom-extensions)
2. Register a new node view with `addNodeView()`
3. Write your render function
4. [Configure tiptap to use your new node extension](/guide/configuration)
4. [Configure Tiptap to use your new node extension](/guide/configuration)
This is how your node extension could look like:
@@ -120,4 +120,4 @@ Got it? You’re free to do anything you like, as long as you return a container
https://embed.tiptap.dev/preview/GuideNodeViews/JavaScriptContent
Keep in mind that this content is rendered by tiptap. That means you need to tell what kind of content is allowed, for example with `content: 'inline*'` in your node extension (that’s what we use in the above example).
Keep in mind that this content is rendered by Tiptap. That means you need to tell what kind of content is allowed, for example with `content: 'inline*'` in your node extension (that’s what we use in the above example).

4
docs/guide/node-views/react.md
View File

@@ -14,7 +14,7 @@ Here is what you need to do to render React components inside your editor:
2. Create a React component
3. Pass that component to the provided `ReactNodeViewRenderer`
4. Register it with `addNodeView()`
5. [Configure tiptap to use your new node extension](/guide/configuration)
5. [Configure Tiptap to use your new node extension](/guide/configuration)
This is how your node extension could look like:
@@ -92,7 +92,7 @@ You don’t need to add those `className` attributes, feel free to remove them o
https://embed.tiptap.dev/preview/GuideNodeViews/ReactComponentContent
Keep in mind that this content is rendered by tiptap. That means you need to tell what kind of content is allowed, for example with `content: 'inline*'` in your node extension (that’s what we use in the above example).
Keep in mind that this content is rendered by Tiptap. That means you need to tell what kind of content is allowed, for example with `content: 'inline*'` in your node extension (that’s what we use in the above example).
The `NodeViewWrapper` and `NodeViewContent` components render a `<div>` HTML tag (`<span>` for inline nodes), but you can change that. For example `<NodeViewContent as="p">` should render a paragraph. One limitation though: That tag must not change during runtime.

4
docs/guide/node-views/vue.md
View File

@@ -14,7 +14,7 @@ Here is what you need to do to render Vue components inside your editor:
2. Create a Vue component
3. Pass that component to the provided `VueNodeViewRenderer`
4. Register it with `addNodeView()`
5. [Configure tiptap to use your new node extension](/guide/configuration)
5. [Configure Tiptap to use your new node extension](/guide/configuration)
This is how your node extension could look like:
@@ -114,7 +114,7 @@ You don’t need to add those `class` attributes, feel free to remove them or pa
https://embed.tiptap.dev/preview/GuideNodeViews/VueComponentContent
Keep in mind that this content is rendered by tiptap. That means you need to tell what kind of content is allowed, for example with `content: 'inline*'` in your node extension (that’s what we use in the above example).
Keep in mind that this content is rendered by Tiptap. That means you need to tell what kind of content is allowed, for example with `content: 'inline*'` in your node extension (that’s what we use in the above example).
The `NodeViewWrapper` and `NodeViewContent` components render a `<div>` HTML tag (`<span>` for inline nodes), but you can change that. For example `<node-view-content as="p">` should render a paragraph. One limitation though: That tag must not change during runtime.

16
docs/guide/output.md
View File

@@ -10,7 +10,7 @@ You can store your content as a JSON object or as a good old HTML string. Both w
## Export
### 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:
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.getJSON()
@@ -82,14 +82,14 @@ Unfortunately, **tiptap doesn’t support Markdown as an input or output format*
* Both, HTML and JSON, can have deeply nested structures, Markdown is flat.
* Markdown standards vary.
* tiptap’s strength is customization, that doesn’t work very well with Markdown.
* Tiptap’s strength is customization, that doesn’t 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](https://prosemirror.net/examples/markdown/), [Nextcloud Text](https://github.com/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](https://codemirror.net/).
If you still think you need Markdown, ProseMirror has an [example on how to deal with Markdown](https://prosemirror.net/examples/markdown/), [Nextcloud Text](https://github.com/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](https://codemirror.net/).
That said, tiptap does support [Markdown shortcuts](/examples/markdown-shortcuts) to format your content. Also you’re free to let your content look like Markdown, for example add a `#` before an `<h1>` with CSS.
That said, Tiptap does support [Markdown shortcuts](/examples/markdown-shortcuts) to format your content. Also you’re 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](/api/events). Here is an example how that could look like:
@@ -109,13 +109,13 @@ const editor = new Editor({
## Rendering
### Option 1: Read-only instance of tiptap
### 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.
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, you’ll probably want to do just that without an actual editor instance.
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.
@@ -126,11 +126,11 @@ By the way, the other way is possible, too. The below examples shows how to gene
https://embed.tiptap.dev/preview/GuideContent/GenerateJSON
## Migration
If you’re migrating existing content to tiptap we would recommend to get your existing output to HTML. That’s 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 aren’t allowed (based on your configuration), tiptap just throws them away quietly.
If you’re migrating existing content to Tiptap we would recommend to get your existing output to HTML. That’s 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 aren’t allowed (based on your configuration), Tiptap just throws them away quietly.
We’re 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](https://github.com/ueberdosis/html-to-prosemirror).
[Share your experiences with us!](mailto:humans@tiptap.dev) We’d 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 doesn’t matter if it’s JSON or HTML. It doesn’t even matter if you’re using tiptap or not. You should always validate user input.
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 doesn’t matter if it’s JSON or HTML. It doesn’t even matter if you’re using Tiptap or not. You should always validate user input.

6
docs/guide/typescript.md
View File

@@ -5,13 +5,13 @@ tableOfContents: true
# Working with TypeScript
## Introduction
The whole tiptap is code base is written in TypeScript. If you haven’t heard of it or never used it, no worries. You don’t have to.
The whole Tiptap is code base is written in TypeScript. If you haven’t heard of it or never used it, no worries. You don’t have to.
TypeScript extends JavaScript by adding types (hence the name). It adds new syntax, which doesn’t exist in Vanilla JavaScript. It’s actually removed before running in the browser, but this step – the compilation – is important to find bugs early. It checks if you passe the right types of data to functions. For a big and complex project, that’s very valuable. It means we’ll get notified of lot of bugs, before shipping code to you.
**Anyway, if you don’t use TypeScript in your project, that’s fine.** You will still be able to use tiptap and nevertheless get a nice autocomplete for the tiptap API (if your editor supports it, but most do).
**Anyway, if you don’t use TypeScript in your project, that’s fine.** You will still be able to use Tiptap and nevertheless get a nice autocomplete for the Tiptap API (if your editor supports it, but most do).
If you are using TypeScript in your project and want to extend tiptap, there are two types that are good to know about.
If you are using TypeScript in your project and want to extend Tiptap, there are two types that are good to know about.
## Types