improve the documentation

docs/src/docPages/api/schema.md

@@ -1,46 +1,13 @@
 # Schema
+Unlike many other editors, tiptap is based on a [schema](https://prosemirror.net/docs/guide/#schema) that defines how your content is structured. That enables you to define the kind of nodes that may occur in the document, its attributes and the way they can be nested.
 
-Tiptap is based on ProseMirror and just like ProseMirror does, tiptap works with an underlying schema. This schema has all the information about nodes, marks and your custom extension. It’s used to convert your content to HTML and vice-versa. Tiptap handles the schema for you, but there are a few use cases where you need the schema, without an actual editor.
+This schema is *very* strict. You can’t use any HTML element or attribute that is not defined in your schema.
 
-## Get the underlying ProseMirror schema
-
-If you just want to have the schema without initializing an actual editor, you can use the `getSchema` function. This function needs an array of available extensions and generates a ProseMirror schema for you:
-
-```js
-import { getSchema } from '@tiptap/core'
-import Document from '@tiptap/extension-document'
-import Paragraph from '@tiptap/extension-paragraph'
-import Text from '@tiptap/extension-text'
-
-const schema = getSchema([
-  new Document,
-  new Paragraph,
-  new Text,
-  // add more extensions here
-])
-```
-
-You might need this on the server side, if you’re using the collaborative text editing features of tiptap.
-
-## Generate HTML from ProseMirror JSON
-
-<demo name="Api/Schema" />
-
-## Old Content
-
-:::warning Out of date
-This content is written for tiptap 1 and needs an update.
-:::
-
-Unlike many other editors, tiptap is based on a [schema](https://prosemirror.net/docs/guide/#schema) that defines how your content is structured. This enables you to define the kind of nodes that may occur in the document, its attributes and the way they can be nested.
-
-This schema is *very* strict. You can’t use any HTML-element or attribute that is not defined in your schema.
-
-For example if you paste something like `This is <strong>important</strong>` into tiptap and don’t have registered any extension that handles `strong` tags, you’ll only see `This is important`.
+Let me give you one example: If you paste something like `This is <strong>important</strong>` into tiptap, don’t have any extension that handles `strong` tags registered, you’ll only see `This is important` – without the strong tags.
 
 ## How a schema looks like
 
-The most simple schema for a typical *ProseMirror* editor is looking something like that.
+The most simple schema for a typical *ProseMirror* editor is looking something like that:
 
 ```js
 {
@@ -61,6 +28,10 @@ The most simple schema for a typical *ProseMirror* editor is looking something l
 }
 ```
 
+:::warning Out of date
+This content is written for tiptap 1 and needs an update.
+:::
+
 We register three nodes here. `document`, `paragraph` and `text`. `document` is the root node which allows one or more block nodes as children (`content: 'block+'`). Since `paragraph` is in the group of block nodes (`group: 'block'`) our document can only contain paragraphs. Our paragraphs allow zero or more inline nodes as children (`content: 'inline*'`) so there can only be `text` in it. `parseDOM` defines how a node can be parsed from pasted HTML. `toDOM` defines how it will be rendered in the DOM.
 
 In tiptap we define every node in its own `Extension` class instead. This allows us to split logic per node. Under the hood the schema will be merged together.

docs/src/docPages/api/schema/generate-html.md

@@ -0,0 +1,15 @@
+# Generate HTML from ProseMirror JSON
+
+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.
+
+<demo name="Api/Schema" />
+
+That should work in the browser (client side) and in Node.js (browser side).
+
+## Converting JSON<>HTML with PHP
+
+We needed to do the same thing in PHP at some point, so we published libraries to convert ProseMirror JSON to HTML and vice-versa:
+
+* [ueberdosis/prosemirror-php](https://github.com/ueberdosis/prosemirror-php) (PHP)
+* [ueberdosis/prosemirror-to-html](https://github.com/ueberdosis/prosemirror-to-html) (PHP)
+* [ueberdosis/html-to-prosemirror](https://github.com/ueberdosis/html-to-prosemirror) (PHP)

docs/src/docPages/api/schema/get-schema.md

@@ -0,0 +1,41 @@
+# Get the underlying ProseMirror schema
+
+There are a few use cases where you need to work with the underlying schema. You’ll need that if you’re using the tiptap collaborative text editing features or if you want to manually render your content as HTML.
+
+## With an Editor
+If you need this on the client side and need an editor instance anyway, it’s available through the editor:
+
+```js
+import { Editor } from '@tiptap/core'
+import Document from '@tiptap/extension-document'
+import Paragraph from '@tiptap/extension-paragraph'
+import Text from '@tiptap/extension-text'
+
+const editor = new Editor({
+  extensions: [
+    new Document,
+    new Paragraph,
+    new Text,
+    // add more extensions here
+  ])
+})
+
+const schema = editor.schema
+```
+
+## Without an Editor
+If you just want to have the schema *without* initializing an actual editor, you can use the `getSchema` helper function. It needs an array of available extensions and conveniently generates a ProseMirror schema for you:
+
+```js
+import { getSchema } from '@tiptap/core'
+import Document from '@tiptap/extension-document'
+import Paragraph from '@tiptap/extension-paragraph'
+import Text from '@tiptap/extension-text'
+
+const schema = getSchema([
+  new Document,
+  new Paragraph,
+  new Text,
+  // add more extensions here
+])
+```

docs/src/links.yaml

@@ -192,4 +192,8 @@
       draft: true
     - title: Schema
       link: /api/schema
-      draft: true
+      items:
+        - title: getSchema
+          link: /api/schema/get-schema
+        - title: generateHtml
+          link: /api/schema/generate-html