mirror/tiptap
1
0
Fork 0
mirror of https://github.com/ueberdosis/tiptap.git synced 2025-01-18 14:13:21 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs: add content

Browse Source
This commit is contained in:
Hans Pagel 2020-11-17 17:10:48 +01:00
parent 3d3dcdaf42
commit 4f36f30c75
5 changed files with 212 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
docs/src/docPages/api/editor.md
View File

@ -5,37 +5,147 @@
## Introduction ## Introduction
This class is a central building block of tiptap. It does most of the heavy lifting of creating a working [ProseMirror](https://ProseMirror.net/) editor such as creating the [`EditorView`](https://ProseMirror.net/docs/ref/#view.EditorView), setting the initial [`EditorState`](https://ProseMirror.net/docs/ref/#state.Editor_State) and so on. This class is a central building block of tiptap. It does most of the heavy lifting of creating a working [ProseMirror](https://ProseMirror.net/) editor such as creating the [`EditorView`](https://ProseMirror.net/docs/ref/#view.EditorView), setting the initial [`EditorState`](https://ProseMirror.net/docs/ref/#state.Editor_State) and so on.
## Configuration ## List of available settings
| Setting | Type | Default | Description | Check out the API documentation to see [all available options](/api/editor/).
| ------------------ | --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autofocus` | `Boolean` | `false` | Focus the editor on init. |
| `content` | `Object|String` | `null` | The editor state object used by Prosemirror. You can also pass HTML to the `content` slot. When used both, the `content` slot will be ignored. |
| `editable` | `Boolean` | `true` | When set to `false` the editor is read-only. |
| `editorProps` | `Object` | `{}` | A list of [Prosemirror editorProps](https://prosemirror.net/docs/ref/#view.EditorProps). |
| `extensions` | `Array` | `[]` | A list of extensions used, by the editor. This can be `Nodes`, `Marks` or `Plugins`. |
| `parseOptions` | `Object` | `{}` | A list of [Prosemirror parseOptions](https://prosemirror.net/docs/ref/#model.ParseOptions). |
| `onBlur` | `Function` | `undefined` | Returns an object with the `event` and current `state` and `view` of Prosemirror on blur. |
| `onFocus` | `Function` | `undefined` | Returns an object with the `event` and current `state` and `view` of Prosemirror on focus. |
| `onInit` | `Function` | `undefined` | Returns an object with the current `state` and `view` of Prosemirror on init. |
| `onUpdate` | `Function` | `undefined` | Returns an object with the current `state` of Prosemirror, a `getJSON()` and `getHTML()` function and the `transaction` on every change. |
## Methods ### Element
| Method | Parameters | Description | The `element` specifies the HTML element the editor will be binded too. The following code will add tiptap to an element with the `.element` class:
| -------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `getHTML()` | – | Returns the current content as HTML. | ```js
| `getJSON()` | – | Returns the current content as JSON. | import { Editor } from '@tiptap/core'
| `destroy()` | – | Stops the editor instance and unbinds all events. | import { defaultExtensions } from '@tiptap/starter-kit'
| `chain()` | - | Create a command chain to call multiple commands at once. |
new Editor({
element: document.querySelector('.element'),
extensions: defaultExtensions(),
})
```
### Extensions
It’s required to pass a list of extensions to the `extensions` property, even if you only want to allow paragraphs.
```js
import { Editor } from '@tiptap/core'
import { defaultExtensions } from '@tiptap/starter-kit'
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'
import Highlight from '@tiptap/extension-highlight'
new Editor({
// Use the default extensions
extensions: defaultExtensions(),
// … or use specific extensions
extensions: [
Document,
Paragraph,
Text,
],
// … or both
extensions: [
...defaultExtensions(),
Highlight,
]
})
```
### Content
With the `content` property you can provide the initial content for the editor. This can be HTML or JSON.
```js
import { Editor } from '@tiptap/core'
import { defaultExtensions } from '@tiptap/starter-kit'
new Editor({
content: `<p>Example Text</p>`,
extensions: defaultExtensions(),
})
```
### Editable
The `editable` property determines if users can write into the editor.
```js
import { Editor } from '@tiptap/core'
import { defaultExtensions } from '@tiptap/starter-kit'
new Editor({
content: `<p>Example Text</p>`,
extensions: defaultExtensions(),
editable: false,
})
```
### Autofocus
With `autofocus` you can force the cursor to jump in the editor on initialization.
```js
import { Editor } from '@tiptap/core'
import { defaultExtensions } from '@tiptap/starter-kit'
new Editor({
extensions: defaultExtensions(),
autofocus: false,
})
```
| Value | Description |
| --------- | ------------------------------------------------------ |
| `'start'` | Sets the focus to the beginning of the document. |
| `'end'` | Sets the focus to the end of the document. |
| number | Sets the focus to a specific position in the document. |
| `true` | Enables autofocus. |
| `false` | Disables autofocus. |
| `null` | Disables autofocus. |
### Inject CSS
By default, tiptap injects [a little bit of CSS](https://github.com/ueberdosis/tiptap-next/tree/main/packages/core/src/style.ts). With `injectCSS` you can disable that.
```js
import { Editor } from '@tiptap/core'
import { defaultExtensions } from '@tiptap/starter-kit'
new Editor({
extensions: defaultExtensions(),
injectCSS: false,
})
```
<!--
| Setting | Type | Default | Description |
| ------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autofocus` | `Boolean` | `false` | Focus the editor on init. |
| `content` | `Object|String` | `null` | The editor state object used by Prosemirror. You can also pass HTML to the `content` slot. When used both, the `content` slot will be ignored. |
| `editable` | `Boolean` | `true` | When set to `false` the editor is read-only. |
| ~~`editorProps`~~ | ~~`Object`~~ | ~~`{}`~~ | ~~A list of [Prosemirror editorProps](https://prosemirror.net/docs/ref/#view.EditorProps).~~ |
| `element` | `Element` | `false` | Focus the editor on init. |
| `extensions` | `Array` | `[]` | A list of extensions you would like to use. Can be [`Nodes`](/api/nodes), [`Marks`](/api/marks) or [`Extensions`](/api/extensions). |
| `injectCSS` | `Boolean` | `true` | When set to `false` tiptap won’t load [the default ProseMirror CSS](https://github.com/ueberdosis/tiptap-next/tree/main/packages/core/src/style.ts). |
| ~~`parseOptions`~~ | ~~`Object`~~ | ~~`{}`~~ | ~~A list of [Prosemirror parseOptions](https://prosemirror.net/docs/ref/#model.ParseOptions).~~ | -->
## List of available methods
An editor instance will provide the following public methods. They’ll help you to work with the editor.
Don’t confuse methods with [commands](/api/commands), which are used to change the state of editor (content, selection, and so on) and only return `true` or `false`.
| Method | Parameters | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `can()` | - | Check if a command or a command chain can be executed. Without executing it. | | `can()` | - | Check if a command or a command chain can be executed. Without executing it. |
| `setOptions()` | `options` A list of options | Update editor options. | | `chain()` | - | Create a command chain to call multiple commands at once. |
| `isEditable()` | - | Returns whether the editor is editable. | | `createDocument()` | `content` EditorContent<br>`parseOptions` | Creates a ProseMirror document. |
| `state()` | - | Returns the editor state. | | `destroy()` | – | Stops the editor instance and unbinds all events. |
| `registerCommands()` | `commands` A list of commands | Register a list of commands. | | `getHTML()` | – | Returns the current content as HTML. |
| `registerCommand()` | `name` The name of your command<br>`callback` The method of your command | Register a command. | | `getJSON()` | – | Returns the current content as JSON. |
| `registerPlugin()` | `plugin` A ProseMirror plugin<br>`handlePlugins` Control how to merge the plugin into the existing plugins. | Register a ProseMirror plugin. | | `getMarkAttrs()` | `state` State of the editor<br>`name` Name of the mark | Get attributes of the currently selected mark. |
| `unregisterPlugin()` | `name` The plugins name | Unregister a ProseMirror plugin. | | `getNodeAttrs()` | `state` State of the editor`name` Name of the node | Get attributes of the currently selected node. |
| `createDocument()` | `content` EditorContent<br>`parseOptions` | Creates a ProseMirror document. | | `isActive()` | `name` Name of the node or mark<br>`attrs` Attributes of the node or mark | Returns if the currently selected node or mark is active. |
| `getNodeAttrs()` | `name` Name of the node | Get attributes of the currently selected node. | | `isEditable()` | - | Returns whether the editor is editable. |
| `getMarkAttrs()` | `name` Name of the mark | Get attributes of the currently selected mark. | | `isEmpty()` | - | Check if there is no content. |
| `isActive()` | `name` Name of the node or mark<br>`attrs` Attributes of the node or mark | Returns if the currently selected node or mark is active. | | `registerCommand()` | `name` The name of your command<br>`callback` The method of your command | Register a command. |
| `isEmpty()` | - | Check if there is no content. | | `registerCommands()` | `commands` A list of commands | Register a list of commands. |
| `registerPlugin()` | `plugin` A ProseMirror plugin<br>`handlePlugins` Control how to merge the plugin into the existing plugins. | Register a ProseMirror plugin. |
| `setOptions()` | `options` A list of options | Update editor options. |
| `unregisterPlugin()` | `name` The plugins name | Unregister a ProseMirror plugin. |

25
docs/src/docPages/guide/configuration.md
View File

@ -1,25 +0,0 @@
# Configuration
## toc
## Introduction
tiptap is all about customization. There are a ton of options to configure the behavior and functionality of the editor. Most of those settings can be set before creating the Editor. Give tiptap a JSON with all the settings you would like to overwrite.
## Overwrite the default settings
See an example with `autofocus: true` here:
```js
import { Editor } from '@tiptap/core'
import { defaultExtensions } from '@tiptap/starter-kit'
new Editor({
element: document.querySelector('.element'),
extensions: defaultExtensions(),
content: '<p>Hey there!</p>',
autofocus: true,
})
```
This will set the focus to tiptap after the editor is initialized. Of course, there are way more options available.
Check out the API documentation to see [all available options](/api/editor/).

63
docs/src/docPages/guide/configure-the-editor.md Normal file
View File

@ -0,0 +1,63 @@
# Configure the editor
## toc
## Introduction
There are a few things you can control when initializing a new editor. 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.
## Configure the editor
To add your configuration, pass [an object with settings](/api/editor) to the `Editor` class, like shown here:
```js
import { Editor } from '@tiptap/core'
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'
new Editor({
element: document.querySelector('.element'),
extensions: [
Document,
Paragraph,
Text,
],
content: '<p>Example Text</p>',
autofocus: true,
editable: true,
injectCSS: false,
})
```
This will do the following:
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,
5. make the text editable (but that’s the default anyway), and
6. disable the loading of [the default CSS](https://github.com/ueberdosis/tiptap-next/tree/main/packages/core/src/style.ts) (which is not much anyway).
## Configure extensions
A lot of the extension can be configured, too. Add an `.configure()` to the extension and pass an object to it. The following example will disable the default heading levels 4, 5 and 6:
```js
import { Editor } from '@tiptap/core'
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'
import Heading from '@tiptap/extension-heading'
new Editor({
element: document.querySelector('.element'),
extensions: [
Document,
Paragraph,
Text,
Heading.configure({
level: [1, 2, 3],
}),
],
})
```
Have a look at the documentation of the extension you’re using to learn more about their settings.

5
docs/src/docPages/overview/upgrade-guide.md
View File

@ -22,6 +22,8 @@ We’re waiting for Gridsome to be compatible with Vue.js 3.
### Explicitly register the Document, Text and Paragraph extensions ### Explicitly register the Document, Text and Paragraph 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/nodes/document), [Paragraph](/api/nodes/paragraph) and [Text](/api/nodes/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/nodes/document), [Paragraph](/api/nodes/paragraph) and [Text](/api/nodes/text) extensions.
TODO: removed dropCursor, enableDropCursor, enableGapCursor
```js ```js
import Document from '@tiptap/extension-document' import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph' import Paragraph from '@tiptap/extension-paragraph'
@ -40,6 +42,9 @@ new Editor({
### New document type ### 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.~~ ~~**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.~~
### Removed methods
TODO: state()
### New extension API ### New extension API
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. 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.

4
docs/src/links.yaml
View File

@ -45,8 +45,8 @@
link: /guide/getting-started link: /guide/getting-started
new: true new: true
- title: Configure the editor - title: Configure the editor
link: /guide/configuration link: /guide/configure-the-editor
draft: true new: true
- title: Create a new toolbar - title: Create a new toolbar
link: /guide/create-your-editor link: /guide/create-your-editor
draft: true draft: true