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

Merge branch 'main' into feature/new-highlight-extension

Browse Source 
# Conflicts:
#	packages/core/src/commands/toggleMark.ts
This commit is contained in:
Hans Pagel
2020-10-27 20:36:22 +01:00
parent 9a1bc8a8b1 fd7d0f03bd
commit da3618ec6f
164 changed files with 4827 additions and 2779 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/src/docPages/api/commands.md
View File

@@ -3,20 +3,38 @@
## Table of Contents
## Introduction
The editor provides a ton of commands to programmtically add or change content or alter the selection. If you want to build your own editor you definitely want to learn more about them.
## Execute a command
All available commands are accessible through an editor instance. Let’s say you want to make text bold when a user clicks on a button. That’s how that would look like:
```js
editor.bold()
```
While that’s perfectly fine and does make the selected bold, you’d likely want to change multiple commands in one run. Let’s have a look at how that works.
## Chain commands
Most commands can be executed combined to one call. First of all, that’s shorter than separate function call in most cases. Here is an example to make the selected text bold:
```js
editor.chain().focus().bold().run()
```
The `.chain()` is required to start a new chain and the `.run()` is needed to actually execute all the commands in between. Between those two functions, this example combines to different commands.
When a user clicks on a button outside of the content, the editor isn’t in focus anymore. That’s why you probably want to add a `.focus()` call to most of your commands, that brings back the focus to the editor and the user can continue to type.
All chained commands are kind of queued up. They are combined to one single transaction. That means, the content is only updated once, also the `update` event is only triggered once.
## List of commands
Have a look at all of the core commands listed below. They should give you a good first impression of what’s possible.
### Content
| Command | Description |
| --------------- | ----------------------------------------------------------- |
| .clearContent() | Clear the whole document. |
| .insertHTML() | Insert a string of HTML at the currently selected position. |
| .insertgetHTML() | Insert a string of HTML at the currently selected position. |
| .insertText() | Insert a string of text at the currently selected position. |
| .setContent() | Replace the whole document with new content. |
@@ -47,3 +65,6 @@ editor.chain().focus().bold().run()
| .focus() | Focus the editor at the given position. |
| .scrollIntoView() | Scroll the selection into view. |
| .selectAll() | Select the whole document. |
### Extensions
All extension can add additional commands (and most do), check out the specific [documentation for the provided extensions](/api/extensions) to learn more about that. Of course, you can [add your custom extensions](/guide/custom-extensions) with custom commands aswell.

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

@@ -20,13 +20,13 @@ This class is a central building block of tiptap. It does most of the heavy lift
| `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 `json()` and `html()` function and the `transaction` on every change. |
| `onUpdate` | `Function` | `undefined` | Returns an object with the current `state` of Prosemirror, a `getJSON()` and `getHTML()` function and the `transaction` on every change. |
## Methods
| Method | Parameters | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `html()` | – | Returns the current content as HTML. |
| `json()` | – | Returns the current content as JSON. |
| `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. |
| `setOptions()` | `options` A list of options | Update editor options. |

5
docs/src/docPages/api/extensions/code-block.md
View File

@@ -1,7 +1,7 @@
# CodeBlock
With the CodeBlock extension you can add fenced code blocks to your documents. It’ll wrap the code in `<pre>` and `<code>` HTML tags.
Type three backticks and a space <code>&grave;&grave;&grave;</code> and a code block is instantly added for you.
Type <code>&grave;&grave;&grave;&nbsp;</code> (three backticks and a space) or <code>&Tilde;&Tilde;&Tilde;&nbsp;</code> (three tildes and a space) and a code block is instantly added for you. You can even specify the language, try writing <code>&grave;&grave;&grave;css&nbsp;</code>. That should add a `language-css` class to the `<code>`-tag.
::: warning Restrictions
The CodeBlock extension doesn’t come with styling and has no syntax highlighting built-in. It’s on our roadmap though.
@@ -28,7 +28,8 @@ yarn add @tiptap/extension-code-block
| codeBlock | — | Wrap content in a code block. |
## Keyboard shortcuts
* `Shift`&nbsp;`Control`&nbsp;`\`
* Windows/Linux: `Control`&nbsp;`Shift`&nbsp;`C`
* macOS: `Cmd`&nbsp;`Shift`&nbsp;`C`
## Source code
[packages/extension-code-block/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code-block/)

2
docs/src/docPages/api/extensions/code.md
View File

@@ -23,7 +23,7 @@ yarn add @tiptap/extension-code
| code | — | Mark text as inline code. |
## Keyboard shortcuts
* `Alt&nbsp;`&nbsp;<code>`</code>
* `Alt`&nbsp;<code>`</code>
## Source code
[packages/extension-code/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code/)

16
docs/src/docPages/api/extensions/image.md Normal file
View File

@@ -0,0 +1,16 @@
# Image
## Installation
```bash
# With npm
npm install @tiptap/extension-image
# Or: With Yarn
yarn add @tiptap/extension-image
```
## Source code
[packages/extension-image/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-image/)
## Usage
<demo name="Extensions/Image" highlight="12,30" />

2
docs/src/docPages/api/extensions/strike.md
View File

@@ -1,7 +1,7 @@
# Strike
Use this extension to render ~~striked text~~. If you pass `<s>`, `<del>`, `<strike>` tags, or text with inline `style` attributes setting `text-decoration: line-through` in the editor’s initial content, they all will be rendered accordingly.
Type <code>~text between tildes~</code> and it will be magically ~~striked through~~ while you type.
Type <code>&Tilde;&Tilde;text between tildes&Tilde;&Tilde;</code> and it will be magically ~~striked through~~ while you type.
::: warning Restrictions
The extension will generate the corresponding `<s>` HTML tags when reading contents of the `Editor` instance. All text striked through, regardless of the method will be normalized to `<s>` HTML tags.

16
docs/src/docPages/api/extensions/text-align.md Normal file
View File

@@ -0,0 +1,16 @@
# Text Align
## Installation
```bash
# With npm
npm install @tiptap/extension-text-align
# Or: With Yarn
yarn add @tiptap/extension-text-align
```
## Source code
[packages/extension-text-align/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-text-align/)
## Usage
<demo name="Extensions/TextAlign" highlight="12,30" />

2
docs/src/docPages/api/schema.md
View File

@@ -128,7 +128,7 @@ const schema = getSchema([
If you need to render the content on the server side, e. g. for a blog post that was written with tiptap, you’ll probably need a way to do just that without an actual editor instance.
That’s what `generateHtml()` is for. It’s a utility function that renders HTML without an actual editor instance.
That’s what `generategetHTML()` is for. It’s a utility function that renders HTML without an actual editor instance.
:::warning Work in progress
Currently, that works only in the browser (client side), but we plan to bring this to Node.js (to use it on the server side).

2
docs/src/docPages/examples/basic.md
View File

@@ -1,4 +1,4 @@
# Basic
BUG: Headings can’t be transformed to a bullet or ordered list.
<live-demo name="Examples/Basic" />
<demo name="Examples/Basic" />

10
docs/src/docPages/examples/collaborative-editing.md
View File

@@ -1,6 +1,12 @@
# Collaborative editing
:::warning Public
The content of this editor is shared with other users.
This example shows how you can use tiptap to let different users collaboratively work on the same text in real-time.
It connects client with WebRTC and merges changes to the document (no matter where they come from) with the awesome library [Y.js](https://github.com/yjs/yjs) by Kevin Jahns. Be aware that in a real-world scenario you would probably add a server, which is also able to merge changes with Y.js.
If you want to learn more about collaborative text editing, [check out our guide on that topic](/guide/collaborative-editing). Anyway, it’s showtime now:
:::warning The content of this editor is shared with other users from the Internet.
Don’t share your password, credit card numbers or other things you wouldn’t make public.
:::
<!-- <demo name="Examples/Collaboration" :show-source="false"/> -->

2
docs/src/docPages/examples/focus.md
View File

@@ -1,3 +1,3 @@
# Focus
<demo name="Examples/Focus" highlight="13,33-36,38" />
<demo name="Examples/Focus" highlight="15,37-40,42" />

2
docs/src/docPages/examples/minimalist.md
View File

@@ -1,3 +1,3 @@
# Minimalist
<demo name="Examples/Minimalist" highlight="7-9,26-28" />
<demo name="Examples/Minimalist" highlight="7-9,25-27" />

24
docs/src/docPages/guide/collaborative-editing.md Normal file
View File

@@ -0,0 +1,24 @@
# Collaborative editing
## Table of Contents
## Introduction
Collaborative editing allows multiple users to work on the same text document in real-time. It’s a complex topic that you should be aware before adding it blindly to you app. No worries though, here is everything you need to know.
## Configure collaboration
### WebRTC provider
### Websocket provider
### Add cursors
### Offline support
## Store the content
### Client-only implementation
### Server implementation

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

@@ -3,7 +3,7 @@
## Table of Contents
## Introduction
Let’s extend tiptap with a custom extension!
One of the strength of tiptap is it’s extendability. You don’t depend on the provided extensions, it’s 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 on top of that.
## Option 1: Change defaults

6
docs/src/docPages/guide/custom-styling.md
View File

@@ -10,7 +10,7 @@ The whole editor is rendered inside of a container with the class `.ProseMirror`
```css
/* Scoped to the editor */
.ProseMirror p&nbsp;{
.ProseMirror p {
margin: 1em 0;
}
```
@@ -19,7 +19,7 @@ If you’re rendering the stored content somewhere, there won’t be a `.ProseMi
```css
/* Global styling */
p&nbsp;{
p {
margin: 1em 0;
}
```
@@ -29,7 +29,6 @@ p&nbsp;{
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(),
@@ -55,7 +54,6 @@ The rendered HTML will look like that:
You can even customize the markup for every extension. This will make a custom bold extension that doesn’t render a `<strong>` tag, but a `<b>` tag:
```js
/* Customizing the markup */
import Bold from '@tiptap/extension-bold'
const CustomBold = Bold

4
docs/src/docPages/guide/store-content.md
View File

@@ -11,7 +11,7 @@ You can store your content as JSON and restore the content from HTML, or the oth
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()
const json = editor.getJSON()
```
You can store that in your database (or send it to an API) and restore the document initially like that:
@@ -59,7 +59,7 @@ editor.setContent({
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
const html = editor.html()
const html = editor.getHTML()
```
This can then be used to restore the document initially:

4
docs/src/docPages/introduction.md
View File

@@ -17,9 +17,9 @@ Although tiptap tries to hide most of the complexity of ProseMirror, it’s buil
**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.
**Framework-agnostic.** We don’t care what framework you use. Tiptap is ready to be used with plain JavaScript or Vue.js. That makes it even possible to write a renderer for React, 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.
**TypeScript.** Tiptap 2 is written in TypeScript. That gives you a nice autocomplete for the API (if your IDE supports that), 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)