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

docs: minor text updates

Browse Source
This commit is contained in:
hanspagel
2021-08-27 23:47:51 +02:00
parent 195d79c9bb
commit 0977621148
3 changed files with 32 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -7,7 +7,9 @@ tableOfContents: true
## 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.
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:
@@ -42,7 +44,9 @@ This will do the following:
6. disable the loading of [the default CSS](https://github.com/ueberdosis/tiptap/tree/main/packages/core/src/style.ts) (which is not much anyway).
## Nodes, marks and extensions
Most features are packed into [nodes](/api/nodes), [marks](/api/marks) and [extensions](/api/extensions). Import what you need and pass them as an Array to the editor and you are good to go. Here is the minimal setup with only three extensions:
Most editing features are bundled as [node](/api/nodes), [mark](/api/marks) or [extension](/api/extensions). Import what you need and pass them as an array to the editor.
Here is the minimal setup with only three extensions:
```js
import { Editor } from '@tiptap/core'
@@ -61,7 +65,9 @@ new Editor({
```
### Configure extensions
Most extensions can be configured. Add a `.configure()` to pass an object to it. The following example will disable the default heading levels 4, 5 and 6:
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:
```js
import { Editor } from '@tiptap/core'
@@ -83,10 +89,10 @@ new Editor({
})
```
Have a look at the documentation of the extension you use to learn more about their settings.
Have a look at the documentation of the extension you are using to learn more about their settings.
### Default extensions
We have put together a few of the most common extensions and provide a `StarterKit` extension to load them. Here is how you to use that:
We have bundled a few of the most common extensions into a `StarterKit` extension. Here is how you to use that:
```js
import StarterKit from '@tiptap/starter-kit'
@@ -98,7 +104,7 @@ new Editor({
})
```
And you can even pass configuration for all default extensions as an object. Just prefix the configuration with the extension name:
You can even pass a configuration for all included extensions as an object. Just prefix the configuration with the extension name:
```js
import StarterKit from '@tiptap/starter-kit'
@@ -112,7 +118,7 @@ new Editor({
})
```
The `StarterKit` extension contains a list of extensions. If you want to load them and add some custom extensions you could write it like that:
The `StarterKit` extension loads the most common extensions, but not all available extensions. If you want to load additional extensions or add a custom extension, add them to the `extensions` array:
```js
import StarterKit from '@tiptap/starter-kit'
@@ -126,7 +132,7 @@ new Editor({
})
```
Don’t want to load a specific extension? Just filter it out:
Don’t want to load a specific extension from the `StarterKit`? Just pass `false` to the config:
```js
import StarterKit from '@tiptap/starter-kit'
@@ -140,4 +146,4 @@ new Editor({
})
```
You’ll probably see something like that in collaborative editing examples. The [`Collaboration`](/api/extensions/collaboration) comes with its own history extension, you need to remove the default [`History`](/api/extensions/history) extension to avoid conflicts.
You will probably see something like that in collaborative editing examples. The [`Collaboration`](/api/extensions/collaboration) comes with its own history extension. You need to remove or disable the default [`History`](/api/extensions/history) extension to avoid conflicts.

30
docs/src/docPages/guide/custom-extensions.md
View File

@@ -43,7 +43,7 @@ new Editor({
The same applies to every aspect of an existing extension, except to the name. Let’s look at all the things that you can change through the extend method. We focus on one aspect in every example, but you can combine all those examples and change multiple aspects in one `extend()` call too.
### Name
The extension name is used in a whole lot of places and changing it isn’t too easy. If you want to change the name of an existing extension, we would recommended to copy the whole extension and change the name in all occurrences.
The extension name is used in a whole lot of places and changing it isn’t too easy. If you want to change the name of an existing extension, you can copy the whole extension and change the name in all occurrences.
The extension name is also part of the JSON. If you [store your content as JSON](/guide/output#option-1-json), you need to change the name there too.
@@ -61,10 +61,10 @@ const CustomLink = Link.extend({
The order in which extensions are loaded influences two things:
1. #### Plugin order
Plugins of extensions with a higher priority will run first.
ProseMirror plugins of extensions with a higher priority will run first.
2. #### Schema order
The [`Link`](/api/marks/link) mark for example has a higher priority, which means it’ll be rendered as `<a href="…"><strong>Example</strong></a>` instead of `<strong><a href="…">Example</></strong>`.
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:
@@ -83,7 +83,7 @@ const CustomHeading = Heading.extend({
### Schema
tiptap works with a strict schema, which configures how the content can be structured, nested, how it behaves and many more things. You [can change all aspects of the schema](/api/schema) for existing extensions. Let’s walk through a few common use cases.
The default `Blockquote` extension can wrap other nodes, like headings. If you want to allow nothing but paragraphs in your blockquotes, this is how you could achieve it:
The default `Blockquote` extension can wrap other nodes, like headings. If you want to allow nothing but paragraphs in your blockquotes, set the `content` attribute accordingly:
```js
// Blockquotes must only include paragraphs
@@ -94,7 +94,7 @@ const CustomBlockquote = Blockquote.extend({
})
```
The schema even allows to make your nodes draggable, that’s what the `draggable` option is for, which defaults to `false`.
The schema even allows to make your nodes draggable, that’s what the `draggable` option is for. It defaults to `false`, but you can override that.
```js
// Draggable paragraphs
@@ -105,10 +105,10 @@ const CustomParagraph = Paragraph.extend({
})
```
That’s just two tiny examples, but [the underlying ProseMirror schema](https://prosemirror.net/docs/ref/#model.SchemaSpec) is really powerful. You should definitely read the documentation to understand all the nifty details.
That’s just two tiny examples, but [the underlying ProseMirror schema](https://prosemirror.net/docs/ref/#model.SchemaSpec) is really powerful.
### Attributes
You can use attributes to store additional information in the content. Let’s say you want to extend the default paragraph extension to enable paragraphs to have different colors:
You can use attributes to store additional information in the content. Let’s say you want to extend the default `Paragraph` node to have different colors:
```js
const CustomParagraph = Paragraph.extend({
@@ -126,11 +126,11 @@ const CustomParagraph = Paragraph.extend({
// <p color="pink">Example Text</p>
```
That’s 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 as attributes from the content.
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’ll 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.
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.
This examples adds a style HTML attribute based on the value of color:
This examples adds a style HTML attribute based on the value of `color`:
```js
const CustomParagraph = Paragraph.extend({
@@ -154,7 +154,7 @@ const CustomParagraph = Paragraph.extend({
// <p style="color: pink">Example Text</p>
```
You can also control how the attribute is parsed from the HTML. Let’s say you want to store the color in an attribute called `data-color`, here’s how you would do that:
You can also control how the attribute is parsed from the HTML. Maybe you want to store the color in an attribute called `data-color` (and not just `color`), here’s how you would do that:
```js
const CustomParagraph = Paragraph.extend({
@@ -184,10 +184,12 @@ const CustomParagraph = Paragraph.extend({
// <p data-color="pink" style="color: pink">Example Text</p>
```
You can disable the rendering of attributes, if you pass `rendered: false`.
You can completly disable the rendering of attributes with `rendered: false`.
#### Extend existing attributes
If you want to add an attribute to an extension and keep existing attributes, you can access them through `this.parent()`. In some cases, it is undefined, so make sure to check for that case, or use optional chaining `this.parent?.()`
If you want to add an attribute to an extension and keep existing attributes, you can access them through `this.parent()`.
In some cases, it is undefined, so make sure to check for that case, or use optional chaining `this.parent?.()`
```js
const CustomTableCell = TableCell.extend({
@@ -202,7 +204,7 @@ const CustomTableCell = TableCell.extend({
})
```
### Global Attributes
### Global attributes
Attributes can be applied to multiple extensions at once. That’s useful for text alignment, line height, color, font family, and other styling related attributes.
Take a closer look at [the full source code](https://github.com/ueberdosis/tiptap/tree/main/packages/extension-text-align) of the [`TextAlign`](/api/extensions/text-align) extension to see a more complex example. But here is how it works in a nutshell:

3
docs/src/docPages/jobs.md
View File

@@ -1,6 +1,5 @@
# Jobs
Some great companies are looking for developers with tiptap or hocuspocus experience right now. If you’re looking for a job to work with tiptap and/or hocuspocus, consider applying:
Some great companies are looking for developers right now. If you’re looking for a job to work with tiptap and/or hocuspocus, consider applying:
**[Frontend Developer](https://bitcrowd.net/jobs) @ bitcrowd**<br>
tiptap · Remote · Germany · Full-time