[SuperEditor][Web][Guides]: Updates guides for version 0.3.0 (#2429)

doc/website/source/super-editor/guides/_data.yaml

@@ -2,6 +2,8 @@ layout: layouts/docs_page.jinja
 
 base_path: super-editor/guides/
 
+super_editor_version: "^0.3.0"
+
 navigation:
   show_contributors: false
 

doc/website/source/super-editor/guides/assemble-a-document.md

@@ -20,8 +20,8 @@ The `MutableDocument` constructor accepts a list of `DocumentNode`s as initial c
 final document = MutableDocument(
   nodes: [
     ParagraphNode(
-      id: Editor.createNodeId(),
-      text: AttributedText(text: "Hello, world!"),
+      id: "node1", 
+      text: AttributedText("Hello, world!"),
     ),
   ],
 );
@@ -33,24 +33,29 @@ A `MutableDocument` can be altered after construction.
 You can insert nodes.
 
 ```dart
-document.insertNodeAt(1, ParagraphNode(
-  id: Editor.createNodeId(),
-  text: AttributedText(text: "New paragraph"),
-),);
+document.insertNodeAt(
+  1,
+  ParagraphNode(
+    id: Editor.createNodeId(),
+    text: AttributedText("New paragraph"),
+  ),
+);
 ```
 
+`Editor.createNodeId()` is a convenience method that generates a random UUID string for the node.
+
 You can move nodes.
 
 ```dart
-document.moveNode(nodeId: "node1", targetIndex: 2);
+document.moveNode(nodeId: "node1", targetIndex: 1);
 ```
 
 You can remove nodes.
 
 ```dart
-document.deleteNodeAt(2);
+document.deleteNodeAt(0);
 ```
 
 If your goal is to use a `MutableDocument` in an editor experience, consider wrapping the
 `MutableDocument` in an `Editor`, and then use the standard edit pipeline to alter the document's
-content.
+content. [TODO: what is the standard editor pipeline? Let's link to those docs or give a brief explanation.]

doc/website/source/super-editor/guides/markdown/parsing.md

@@ -14,6 +14,8 @@ dependencies:
   super_editor_markdown: ^{{ pub.super_editor_markdown.version }}
 ```
 
+[TODO: we use `any` for one and `^{{ pub.super_editor_markdown.version }}` for the other and in another guide we use a variable from `_data.yaml`. Should we use a consistent method or keep them as they are?]
+
 Parse a Markdown document by calling the provided global function:
 
 ```dart
@@ -77,20 +79,22 @@ final superEditorDocument = deserializeMarkdownToDocument(
 Markdown is sometimes extended with custom block syntaxes. These are non-standard syntaxes,
 and they're not understood by standard parsers, like the `markdown` package parser. However,
 the `markdown` package parser accepts `BlockSyntax` objects to parse custom Markdown blocks,
-and Super Editor Markdown forwards those `BlockSyntax`s.
+and Super Editor Markdown forwards those `BlockSyntax`es.
 
 To parse custom Markdown block syntaxes, pass your `BlockSyntax`s to 
 `deserializeMarkdownToDocument()`:
 
 ```dart
 final superEditorDocument = deserializeMarkdownToDocument(
-   markdownText,
-   customBockSyntax: [
-     const TableSyntax(),
-   ],
+  markdownText,
+  customBlockSyntax: [
+    const TableSyntax(),
+  ],
 );
 ```
 
+`TableSyntax` is an example custom `BlockSyntax` that you could create.
+
 ### Custom Super Editor Nodes
 When parsing custom Markdown syntaxes, you'll need to tell Super Editor Markdown how to
 convert those syntaxes into Super Editor `DocumentNode`s. Also, sometimes you might want
@@ -103,11 +107,13 @@ To customize how Markdown converts into Super Editor documents, provide custom
 ```dart
 final superEditorDocument = deserializeMarkdownToDocument(
    markdownText,
-   customBockSyntax: [
+   customBlockSyntax: [
      const TableSyntax(),
    ],
    customElementToNodeConverters: [
      const MarkdownTableToNodeConverter(),
    ],
 );
-```
+```
+
+[TODO: Is there any documentation anywhere how to create a `BlockSyntax` or a `TableSyntax` or `MarkdownTableToNodeConverter`? This should be added here.]

doc/website/source/super-editor/guides/quickstart.md

@@ -2,68 +2,63 @@
 title: Super Editor Quickstart
 contentRenderers: ["jinja", "markdown"]
 ---
+
 # Super Editor Quickstart
-Super Editor comes with sane defaults to help you get started with an editor experience, quickly. These defaults include support for images, list items, blockquotes, and horizontal rules, as well as selection gestures, and various keyboard shortcuts.
+Super Editor comes with sane defaults to help you get started quickly with an editor experience. These defaults include support for images, list items, blockquotes, and horizontal rules, as well as selection gestures and various keyboard shortcuts.
 
 Drop in the default editor and start editing.
 
-## Add <code>super_editor</code> to your project
-To use <code>super_editor</code>, add a dependency in your <code>pubspec.yaml</code>.
+## Add `super_editor` to your project
+To use `super_editor`, add a dependency in your `pubspec.yaml`.
 
 ```yaml
 dependencies:
-  super_editor: {{ pub.super_editor.version }}
+  super_editor: {{ super_editor_version }}
 ```
 
 ## Display an editor
-A visual editor first requires a logical editor. A logical editor holds an underlying document, which the user edits, and a composer to manage the user's selection.
+Super Editor is both the visual editor that users see and interact with, as well as the logical editor that handles those interactions behind the scenes. 
 
-Initialize the logical editor.
+Start by initializing the logical editor:
 
 ```dart
-class MyApp extends StatefulWidget {
-    State<MyApp> createState() => _MyApp();
-}
+import 'package:flutter/widgets.dart';
+import 'package:super_editor/super_editor.dart';
+
+class MyEditorPage extends StatefulWidget {
+  const MyEditorPage({super.key});
 
-class _MyApp extends State<MyApp> {
-    late final Editor _editor;
-    late final MutableDocument _document;
-    late final MutableDocumentComposer _composer;
-
-    void initState() {
-        super.initState();
-
-        _document = MutableDocument.empty();
-
-        _composer = MutableDocumentComposer();
-
-        _editor = Editor();
-    }
-
-    void dispose() {
-        _editor.dispose();
-        _composer.dispose();
-        _document.dispose();
-
-        super.dispose();
-    }
+  @override
+  State<MyEditorPage> createState() => _MyEditorPageState();
 }
-```
-
-With the logical pieces ready, you can now display a visual editor. Build a <code>SuperEditor</code> widget and return it from your <code>build()</code> method.
-
-```dart
-class _MyApp extends State<MyApp> {
-    // ...
-
-    Widget build(BuildContext context) {
-      return SuperEditor(
-          editor: _editor,
-      );
-    }
+
+class _MyEditorPageState extends State<MyEditorPage> {
+  late Editor _editor;
+
+  @override
+  void initState() {
+    super.initState();
+    _editor = createDefaultDocumentEditor(
+      document: MutableDocument.empty(),
+      composer: MutableDocumentComposer(),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return SuperEditor(
+      editor: _editor,
+    );
+  }
 }
 ```
 
+Multiple objects work together to edit documents. A `Document` provides a consistent structure for content within a document. A `DocumentComposer` holds the user's current selection, along with any styles that should be applied to newly typed text. An `Editor` alters the `Document`.
+
+The `Editor` fulfills a number of responsibilities, each of which is configurable. Rather than force every user to fully configure an `Editor`, `super_editor` provides a global factory called `createDefaultDocumentEditor`, which configures an `Editor` with sane defaults. To adjust those defaults, consider copying the implementation of `createDefaultDocumentEditor` and then altering the implementation to meet your needs.
+
+The `SuperEditor` widget creates a user interface for visualizing the `Document`, changing the selection in the `DocumentComposer`, and submitting change requests to the `Editor`. The `SuperEditor` widget is the part that most people think of when they think of "document editing". The `SuperEditor` widget includes many configurable properties, all of which focus on user interactions, e.g., selection and focus policies, gesture interceptors, scroll control, mobile selection handles, and more.
+
 That's all it takes to get started with your very own editor. Run your app, tap in the editor, and start typing!
 
-The next step is configuration. Check out the other guides for more help.
+Check out the other guides for more help.

doc/website/source/super-editor/guides/quill/parsing.md

@@ -4,7 +4,7 @@ contentRenderers:
   - jinja
   - markdown
 ---
-Super Editor supports parsing of Quill Delta documents into Super Editor documents.
+Super Editor supports parsing of [Quill Delta documents](https://quilljs.com/docs/delta/) into Super Editor documents.
 
 To get started with parsing Quill documents, add the Super Editor Quill package:
 

doc/website/source/super-editor/guides/style-a-document.md

@@ -14,7 +14,7 @@ A `Stylesheet` is a priority list of `StyleRule`s. Each `StyleRule` has a `Block
 The easiest way is to create a custom stylesheet is to copy the `defaultStylesheet` and add your rules at the end. For example, to make all level one headers green, create the following stylesheet:
 
 ```dart
-const myStyleSheet = defaultStylesheet.copyWith(
+final myStyleSheet = defaultStylesheet.copyWith(
   addRulesAfter: [
     StyleRule(
       // Matches all level one headers.
@@ -50,7 +50,7 @@ See the `Styles` class for the list of keys to the style metadata used by `Super
 Multiple `StyleRule`s can match a single node. When that happens, `SuperEditor` attempts to merge them, by looking at each key. For example, consider the following stylesheet:
 
 ```dart
-const myStyleSheet = defaultStylesheet.copyWith(
+final myStyleSheet = defaultStylesheet.copyWith(
   addRulesAfter: [
     StyleRule(
       // Matches all level one headers.
@@ -79,7 +79,7 @@ Both styles will be applied. Each level one header will have green text with a f
 If the styles can't be merged, the first one wins. For example, consider the following stylesheet:
 
 ```dart
-const myStyleSheet = defaultStylesheet.copyWith(
+final myStyleSheet = defaultStylesheet.copyWith(
   addRulesAfter: [
     StyleRule(
       // Matches all nodes. 
@@ -108,7 +108,7 @@ Since we cannot match two different text alignments, the first one is used. All
 However, non-conflicting keys are preserved. For example, consider the following stylesheet:
 
 ```dart
-const myStyleSheet = defaultStylesheet.copyWith(
+final myStyleSheet = defaultStylesheet.copyWith(
   addRulesAfter: [
     StyleRule(
       // Matches all nodes.