From f49a5caf55d0873c45d18d24274929dfeaaf5e32 Mon Sep 17 00:00:00 2001 From: Vincent Chan Date: Wed, 6 Dec 2023 16:17:47 +0800 Subject: [PATCH] feat(doc): enhance the docs --- packages/blocky-example/app/app.tsx | 4 +- .../documentations/documentation.module.scss | 8 +++ .../components/markdown/markdown.tsx | 1 + .../blocky-example/docs/builtin-plugins.md | 28 +++++++++ packages/blocky-example/docs/get-started.md | 61 +++++++++++++------ 5 files changed, 83 insertions(+), 19 deletions(-) diff --git a/packages/blocky-example/app/app.tsx b/packages/blocky-example/app/app.tsx index 2c99fed..62640ae 100644 --- a/packages/blocky-example/app/app.tsx +++ b/packages/blocky-example/app/app.tsx @@ -25,7 +25,7 @@ function makeEditorPlugins(): IPlugin[] { }), /** * Tell the editor how to render the banner. - * We use a banner written in Preact here. + * We use a banner written in React here. */ new SpannerPlugin({ factory: makeDefaultReactSpanner(), @@ -62,7 +62,7 @@ function makeController(userId: string, title: string): EditorController { /** * Tell the editor how to render the banner. - * We use a toolbar written in Preact here. + * We use a toolbar written in React here. */ toolbarFactory: makeDefaultReactToolbar(), diff --git a/packages/blocky-example/components/documentations/documentation.module.scss b/packages/blocky-example/components/documentations/documentation.module.scss index e61357c..ba9f6de 100644 --- a/packages/blocky-example/components/documentations/documentation.module.scss +++ b/packages/blocky-example/components/documentations/documentation.module.scss @@ -94,6 +94,14 @@ width: 60%; } } + + code { + font-size: 14px; + background-color: #F0F0F0; + padding: 2px 4px; + border-radius: 4px; + } + @media only screen and (max-width: 920px) { .sidebar { display: none; diff --git a/packages/blocky-example/components/markdown/markdown.tsx b/packages/blocky-example/components/markdown/markdown.tsx index eed25b6..66e1087 100644 --- a/packages/blocky-example/components/markdown/markdown.tsx +++ b/packages/blocky-example/components/markdown/markdown.tsx @@ -20,6 +20,7 @@ marked.marked.setOptions({ const language = hljs.getLanguage(lang) ? lang : "plaintext"; return hljs.highlight(code, { language }).value; }, + langPrefix: "hljs language-", }); function Markdown(props: MarkdownProps) { diff --git a/packages/blocky-example/docs/builtin-plugins.md b/packages/blocky-example/docs/builtin-plugins.md index 4be1782..074fbf7 100644 --- a/packages/blocky-example/docs/builtin-plugins.md +++ b/packages/blocky-example/docs/builtin-plugins.md @@ -1,5 +1,32 @@ # Builtin plugins +## Spanner Plugin + +A spanner is the plugin that will follow the blocks. It's used to render the menu for the blocks. + +You can also drag the spanner to move the blocks. + +The `blocky-react` package provides a default spanner. You can use it by calling `makeDefaultReactSpanner()`. + +```typescript +import { makeDefaultReactSpanner, } from "blocky-react"; + +new SpannerPlugin({ + factory: makeDefaultReactSpanner(), +}), +``` + +## Undo Plugin + +The undo plugin is used to provide undo/redo functionality. +Is's enabled **by default**. + +If you have you own undo/redo functionality, you can disable it by calling `unload` on the pluginRegistry + +```typescript +editorController.pluginRegistry.unload("undo"); +``` + ## Text block Text block is built in. It's the most important block in the BlockyEditor. You don't need to do anything to load it. @@ -17,6 +44,7 @@ interface TextBlockAttributes { Builtin types: +- Quoted - Checkbox - Numbered - Bulleted diff --git a/packages/blocky-example/docs/get-started.md b/packages/blocky-example/docs/get-started.md index 521bfa3..b16f366 100644 --- a/packages/blocky-example/docs/get-started.md +++ b/packages/blocky-example/docs/get-started.md @@ -33,9 +33,13 @@ You can choose what plugins the editor should load. You can define how the editor render the toolbar. ```tsx -import { EditorController } from "blocky-core"; -import { makeReactSpanner, makeReactToolbar } from "blocky-react"; -import BannerMenu from "./bannerMenu"; +import { EditorController, SpannerPlugin } from "blocky-core"; +import { + makeReactSpanner, + makeReactToolbar, + makeDefaultReactSpanner, + makeDefaultReactToolbar, +} from "blocky-react"; import ToolbarMenu from "./toolbarMenu"; import "blocky-core/css/blocky-core.css"; @@ -47,21 +51,21 @@ function makeController(): EditorController { /** * Define the plugins to implement customize features. */ - plugins: [], - /** - * Tell the editor how to render the banner. - * We use a banner written in React here. - */ - bannerFactory: makeReactBanner((editorController: EditorController) => ( - - )), + plugins: [ + /** + * Tell the editor how to render the spanner. + * A spanner is a plugin that will follow the blocks. + * We use a banner written in React here. + */ + new SpannerPlugin({ + factory: makeDefaultReactSpanner(), + }), + ], /** * Tell the editor how to render the banner. - * We use a toolbar written in Preact here. + * We use a toolbar written in React here. */ - toolbarFactory: makeReactToolbar((editorController: EditorController) => { - return ; - }), + toolbarFactory: makeDefaultReactToolbar(), }); } ``` @@ -105,7 +109,7 @@ editor.render(); ## Data representation -The data model in Blocky Editor is represented as an XML Document: +The data model in Blocky Editor is represented as an JSON Document: Example: @@ -132,7 +136,8 @@ your custom block. ### Define a block with React -Implementing a block in Preact is more easier. +We can define a block with VanillaJS. +You can choose React, which is more easier. ```tsx import { type Editor, type IPlugin } from "blocky-core"; @@ -221,6 +226,8 @@ export function makeMyBlockPlugin(): IPlugin { ### Add the plugin to the controller +When we construct the EditorController, we can pass the plugin to it. + ```tsx function makeController(): EditorController { return new EditorController({ @@ -233,6 +240,26 @@ function makeController(): EditorController { } ``` +### Insert a block + +You can insert a block by using the `Changeset` API. + +```tsx +new Changeset(editorState) + .insertChildrenAt(doc, index, [blk.element("BlockName)]) + .apply() +``` + +We also have hight-level API to insert a block. + +```tsx +editorController.insertBlockAfterId(textElement, id, { + autoFocus: true, +}); +``` + +When the data element is inserted, the editor will render the block. + ## Collaborative editing Currently, the document tree of BlockyEditor supports collaborative editing using operation transforming(known as OT).