update the content

docs/src/docPages/guide/custom-extensions.md

@@ -1 +1,7 @@
-# Custom Extensions
+# Custom Extensions
+
+## Option 1: Change defaults
+
+## Option 2: Extend existing extensions
+
+## Option 3: Start from scratch

docs/src/docPages/guide/custom-styling.md

@@ -1,19 +1,31 @@
 # Custom styling
 Tiptap is renderless, that doesn’t mean there is no styling provided. You can decided how your editor should look like.
 
-## Option 1: Styling the plain HTML
-The content is rendered as HTML, so you can just use that to add styling:
+## Option 1: Style the plain HTML
+The whole editor is rendered inside of a container with the class `.ProseMirror`. You can use that to scope your styling to the editor content:
 
 ```css
+/* Scoped to the editor */
+.ProseMirror p {
+  margin: 1em 0;
+}
+```
+
+If you’re rendering the stored content somewhere, there won’t be a `.ProseMirror` container, so you can just globally add styling to the used HTML tags:
+
+```css
+/* Global styling */
 p {
   margin: 1em 0;
 }
 ```
 
-## Option 2: Adding custom classes everywhere
-Every node has a `class` option, that you can use to add a custom class to the rendered HTML tag.
+
+## Option 2: Add custom classes
+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(),
@@ -28,17 +40,18 @@ new Editor({
 })
 ```
 
-This will be the result then:
+The rendered HTML will look like that:
 
 ```html
 <h1 class="my-custom-heading">Example Text</p>
 <p class="my-custom-paragraph">Wow, that’s really custom.</p>
 ```
 
-## Option 3: Customizing the HTML markup
+## Option 3: Customize the HTML
 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

docs/src/docPages/guide/getting-started.md

@@ -27,7 +27,3 @@ If you are using Nuxt.js, note that tiptap needs to run in the client, not on th
 :::
 
 Congrats! You’ve got it! 🎉 Let’s start to configure your editor in the next step.
-
-### Related links
-
-* [tiptap doesn’t have a default styling](#)

docs/src/docPages/guide/store-content.md

@@ -1,16 +1,16 @@
-# Get content
-You can store your content as JSON or you can get a good old HTML string. Both work fine. And of course, you can pass both formats to the editor to restore your content.
+# Store content
+You can store your content as a JSON object or as a good old HTML string. Both work fine. And of course, you can pass both formats to the editor to restore your content.
 
-Funfact: You can store your content as JSON and restore the content from HTML, or the other way around. I don’t know why you would want to do that, but tiptap wouldn’t care.
+You can store your content as JSON and restore the content from HTML, or the other way around. I don’t know why you would do that, but tiptap wouldn’t care.
 
-## Option 1: Work with JSON
-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 JSON:
+## Option 1: JSON
+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()
 ```
 
-You can store that in your database or send it to an API and restore the document initially like that:
+You can store that in your database (or send it to an API) and restore the document initially like that:
 
 ```js
 new Editor({
@@ -51,7 +51,7 @@ editor.setContent({
 })
 ```
 
-## Option 2: Work with HTML
+## Option 2: HTML
 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
@@ -74,9 +74,13 @@ editor.setContent(`<p>Example Text</p>`)
 
 ## Not an option: Markdown
 
-Unfortunately, tiptap doesn’t support Markdown as input/output format. We considered to add support for it, but there are a few limitations:
+Unfortunately, **tiptap doesn’t support Markdown as an input or output format**. We considered to add support for it, but there are a few limitations:
 
 * HTML and JSON can both have deeply nested structures, Markdown can’t have those
 * Tables are not part of the Markdown standard, and can’t easily be stored and restored from Markdown
 
-You should really consider to work with HTML or JSON to store your content. If you still think you need Markdown, [Nextcloud Text](https://github.com/nextcloud/text) uses tiptap to work with Markdown. Their code is open source, so maybe you can learn from them.
+You should really consider to work with HTML or JSON to store your content, they are perfectly fine for most use cases.
+
+If you still think you need Markdown, [Nextcloud Text](https://github.com/nextcloud/text) uses tiptap to work with Markdown. Their code is open source, so maybe you can learn from them.
+
+That said, tiptap **does** support Markdown shortcuts to format your content. Try typing `**two asterisk**` to make your text bold for example.

docs/src/links.yaml

@@ -20,8 +20,8 @@
       draft: true
     - title: Custom styling
       link: /guide/custom-styling
-    - title: Get content
-      link: /guide/get-content
+    - title: Store content
+      link: /guide/store-content
     - title: Custom extensions
       link: /guide/custom-extensions
       draft: true