diff --git a/doc/website/source/super-editor/guides/_data.yaml b/doc/website/source/super-editor/guides/_data.yaml index bd224f6199..5b96ffb4ba 100644 --- a/doc/website/source/super-editor/guides/_data.yaml +++ b/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 diff --git a/doc/website/source/super-editor/guides/assemble-a-document.md b/doc/website/source/super-editor/guides/assemble-a-document.md index 9c69024ffd..a2821faf5b 100644 --- a/doc/website/source/super-editor/guides/assemble-a-document.md +++ b/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. \ No newline at end of file +content. [TODO: what is the standard editor pipeline? Let's link to those docs or give a brief explanation.] \ No newline at end of file diff --git a/doc/website/source/super-editor/guides/document-from-markdown.md b/doc/website/source/super-editor/guides/document-from-markdown.md index 5cfa0073b7..54463c5086 100644 --- a/doc/website/source/super-editor/guides/document-from-markdown.md +++ b/doc/website/source/super-editor/guides/document-from-markdown.md @@ -17,13 +17,27 @@ dependencies: De-serialize a Markdown `String` with the supplied top-level function. ```dart +const markdown = ''' +# Header +This is a _Super_ Editor! +'''; + final document = deserializeMarkdownToDocument(markdown); ``` -The de-serialized document is a `MutableDocument`. Check other guides to find out how to use it. +The de-serialized document is a `MutableDocument`. Add it to your `Editor` similarly to how you did it in the Quickstart guide: + +```dart +_editor = createDefaultDocumentEditor( + document: document, + composer: MutableDocumentComposer(), +); +``` + +Run that, and you'll see the document rendered on the screen. ## Serialize Markdown -Serialize a `Document` to a Markdown `String`. +You can also go the other direction. Here's how you would serialize a `Document` to a Markdown `String`: ```dart final markdown = serializeDocumentToMarkdown(document); diff --git a/doc/website/source/super-editor/guides/markdown/parsing.md b/doc/website/source/super-editor/guides/markdown/parsing.md index 7705963ae4..8856c620f8 100644 --- a/doc/website/source/super-editor/guides/markdown/parsing.md +++ b/doc/website/source/super-editor/guides/markdown/parsing.md @@ -14,9 +14,16 @@ 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 +const markdownText = ''' +# Header +This is a _Super_ Editor! +'''; + final superEditorDocument = deserializeMarkdownToDocument(markdownText); ``` @@ -77,20 +84,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 +112,13 @@ To customize how Markdown converts into Super Editor documents, provide custom ```dart final superEditorDocument = deserializeMarkdownToDocument( markdownText, - customBockSyntax: [ + customBlockSyntax: [ const TableSyntax(), ], customElementToNodeConverters: [ const MarkdownTableToNodeConverter(), ], ); -``` \ No newline at end of file +``` + +[TODO: Is there any documentation anywhere how to create a `BlockSyntax` or a `TableSyntax` or `MarkdownTableToNodeConverter`? This should be added here.] \ No newline at end of file diff --git a/doc/website/source/super-editor/guides/quickstart.md b/doc/website/source/super-editor/guides/quickstart.md index d406f8e5ba..9cffcaafae 100644 --- a/doc/website/source/super-editor/guides/quickstart.md +++ b/doc/website/source/super-editor/guides/quickstart.md @@ -2,68 +2,69 @@ 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 super_editor to your project -To use super_editor, add a dependency in your pubspec.yaml. +## 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 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 { - 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 createState() => _MyEditorPageState(); } -``` - -With the logical pieces ready, you can now display a visual editor. Build a SuperEditor widget and return it from your build() method. - -```dart -class _MyApp extends State { - // ... - - Widget build(BuildContext context) { - return SuperEditor( - editor: _editor, - ); - } + +class _MyEditorPageState extends State { + 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. \ No newline at end of file +Continue your Super Editor journey with more beginner guides: + +- [Document](TODO) +- [DocumentComposer](TODO) +- [Editor](TODO) +- [SuperEditor](TODO) +- TODO: other useful next step guides. diff --git a/doc/website/source/super-editor/guides/quill/parsing.md b/doc/website/source/super-editor/guides/quill/parsing.md index a828f211d6..d27ce1f275 100644 --- a/doc/website/source/super-editor/guides/quill/parsing.md +++ b/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: diff --git a/doc/website/source/super-editor/guides/style-a-document.md b/doc/website/source/super-editor/guides/style-a-document.md index 17330e540e..6d7daea53f 100644 --- a/doc/website/source/super-editor/guides/style-a-document.md +++ b/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. @@ -45,12 +45,14 @@ class MyApp extends StatelessWidget { See the `Styles` class for the list of keys to the style metadata used by `SuperEditor`. +[TODO: what is the meaning of "key" in this context?] + ## Multiple matching rules 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 +81,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 +110,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.