mirror/tiptap
1
0
Fork 0
mirror of https://github.com/ueberdosis/tiptap.git synced 2025-01-18 06:03:22 +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
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
| 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). |
| `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. |
## List of available settings
Check out the API documentation to see [all available options](/api/editor/).
## Methods
| Method | Parameters | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `getHTML()` | – | Returns the current content as HTML. |
| `getJSON()` | – | Returns the current content as JSON. |
| `destroy()` | – | Stops the editor instance and unbinds all events. |
| `chain()` | - | Create a command chain to call multiple commands at once. |
### Element
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:
```js
import { Editor } from '@tiptap/core'
import { defaultExtensions } from '@tiptap/starter-kit'
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. |
| `setOptions()` | `options` A list of options | Update editor options. |
| `isEditable()` | - | Returns whether the editor is editable. |
| `state()` | - | Returns the editor state. |
| `registerCommands()` | `commands` A list of commands | Register a list of commands. |
| `registerCommand()` | `name` The name of your command<br>`callback` The method of your command | Register a command. |
| `registerPlugin()` | `plugin` A ProseMirror plugin<br>`handlePlugins` Control how to merge the plugin into the existing plugins. | Register a ProseMirror plugin. |
| `unregisterPlugin()` | `name` The plugins name | Unregister a ProseMirror plugin. |
| `createDocument()` | `content` EditorContent<br>`parseOptions` | Creates a ProseMirror document. |
| `getNodeAttrs()` | `name` Name of the node | Get attributes of the currently selected node. |
| `getMarkAttrs()` | `name` Name of the mark | Get attributes of the currently selected mark. |
| `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. |
| `isEmpty()` | - | Check if there is no content. |
| `chain()` | - | Create a command chain to call multiple commands at once. |
| `createDocument()` | `content` EditorContent<br>`parseOptions` | Creates a ProseMirror document. |
| `destroy()` | – | Stops the editor instance and unbinds all events. |
| `getHTML()` | – | Returns the current content as HTML. |
| `getJSON()` | – | Returns the current content as JSON. |
| `getMarkAttrs()` | `state` State of the editor<br>`name` Name of the mark | Get attributes of the currently selected mark. |
| `getNodeAttrs()` | `state` State of the editor`name` Name of the node | Get attributes of the currently selected node. |
| `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. |
| `isEditable()` | - | Returns whether the editor is editable. |
| `isEmpty()` | - | Check if there is no content. |
| `registerCommand()` | `name` The name of your command<br>`callback` The method of your command | Register a command. |
| `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
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
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
@ -40,6 +42,9 @@ new Editor({
### 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.~~
### Removed methods
TODO: state()
### 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.

4
docs/src/links.yaml
View File

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