From 3a6ab05e96b2aaf5f59206513b62d0c3e7b0de6a Mon Sep 17 00:00:00 2001 From: Yifeng Wang Date: Thu, 25 Jan 2024 15:39:11 +0800 Subject: [PATCH] docs: reorg guide and reference sidebar (#6115) --- README.md | 4 +- packages/docs/{main => }/.gitignore | 0 packages/docs/.vitepress/config.ts | 210 ++++++++++++++++++ .../docs/{main => }/.vitepress/theme/index.ts | 0 .../docs/{main => }/.vitepress/theme/logo.vue | 0 .../{main => }/.vitepress/theme/style.css | 0 .../{main => }/components/code-sandbox.vue | 0 packages/docs/{main => guide}/adapter.md | 0 packages/docs/{main => guide}/block-schema.md | 0 .../docs/{main => guide}/block-service.md | 0 packages/docs/{main => guide}/block-spec.md | 2 +- packages/docs/{main => guide}/block-view.md | 0 .../docs/{main => guide}/block-widgets.md | 0 packages/docs/{main => guide}/command.md | 0 .../docs/{main => guide}/component-types.md | 8 +- .../{main => guide}/crdt-native-data-flow.md | 6 +- .../{main => guide}/data-synchronization.md | 2 +- .../docs/{main => guide}/design-philosophy.md | 26 +-- packages/docs/{main => guide}/event.md | 0 packages/docs/{main => guide}/inline.md | 2 +- packages/docs/{main => guide}/lit.md | 0 packages/docs/{main => guide}/overview.md | 8 +- packages/docs/{main => guide}/quick-start.md | 0 packages/docs/{main => guide}/selection.md | 4 +- packages/docs/{main => guide}/slot.md | 0 packages/docs/{main => guide}/store.md | 0 .../working-with-block-tree.md | 12 +- .../docs/{main => }/images/affine-demo.jpg | Bin .../docs/{main => }/images/attach-editors.png | Bin .../images/bidirectional-data-flow.png | Bin .../docs/{main => }/images/block-nesting.png | Bin .../images/block-selection-example.png | Bin .../docs/{main => }/images/block-spec.png | Bin .../{main => }/images/block-std-data-flow.png | Bin .../{main => }/images/blocksuite-cover.jpg | Bin .../{main => }/images/component-types.png | Bin .../{main => }/images/composing-editors-1.png | Bin .../{main => }/images/composing-editors-2.png | Bin .../images/context-interleaving.png | Bin .../images/crdt-native-data-flow.png | Bin .../{main => }/images/editor-structure.png | Bin .../{main => }/images/encoded-crdt-binary.png | Bin .../docs/{main => }/images/flat-inlines.png | Bin .../{main => }/images/framework-agnostic.png | Bin .../{main => }/images/hello-blocksuite.png | Bin .../docs/{main => }/images/inline-example.png | Bin .../{main => }/images/package-overview.png | Bin .../{main => }/images/pluggable-providers.png | Bin .../{main => }/images/selection-types.png | Bin .../images/showcase-doc-edgeless-editors.jpg | Bin .../images/showcase-edgeless-perf.jpg | Bin .../images/showcase-fragments-1.jpg | Bin .../images/showcase-fragments-2.jpg | Bin .../images/text-selection-example.png | Bin packages/docs/{main => }/index.md | 8 +- packages/docs/main/.vitepress/config.ts | 200 ----------------- packages/docs/{main => }/package.json | 6 +- .../docs/{main => }/presets/doc-editor.md | 0 .../{main => }/presets/edgeless-editor.md | 0 pnpm-lock.yaml | 8 +- pnpm-workspace.yaml | 2 +- typedoc.json | 2 +- 62 files changed, 260 insertions(+), 250 deletions(-) rename packages/docs/{main => }/.gitignore (100%) create mode 100644 packages/docs/.vitepress/config.ts rename packages/docs/{main => }/.vitepress/theme/index.ts (100%) rename packages/docs/{main => }/.vitepress/theme/logo.vue (100%) rename packages/docs/{main => }/.vitepress/theme/style.css (100%) rename packages/docs/{main => }/components/code-sandbox.vue (100%) rename packages/docs/{main => guide}/adapter.md (100%) rename packages/docs/{main => guide}/block-schema.md (100%) rename packages/docs/{main => guide}/block-service.md (100%) rename packages/docs/{main => guide}/block-spec.md (97%) rename packages/docs/{main => guide}/block-view.md (100%) rename packages/docs/{main => guide}/block-widgets.md (100%) rename packages/docs/{main => guide}/command.md (100%) rename packages/docs/{main => guide}/component-types.md (94%) rename packages/docs/{main => guide}/crdt-native-data-flow.md (95%) rename packages/docs/{main => guide}/data-synchronization.md (98%) rename packages/docs/{main => guide}/design-philosophy.md (95%) rename packages/docs/{main => guide}/event.md (100%) rename packages/docs/{main => guide}/inline.md (99%) rename packages/docs/{main => guide}/lit.md (100%) rename packages/docs/{main => guide}/overview.md (86%) rename packages/docs/{main => guide}/quick-start.md (100%) rename packages/docs/{main => guide}/selection.md (97%) rename packages/docs/{main => guide}/slot.md (100%) rename packages/docs/{main => guide}/store.md (100%) rename packages/docs/{main => guide}/working-with-block-tree.md (97%) rename packages/docs/{main => }/images/affine-demo.jpg (100%) rename packages/docs/{main => }/images/attach-editors.png (100%) rename packages/docs/{main => }/images/bidirectional-data-flow.png (100%) rename packages/docs/{main => }/images/block-nesting.png (100%) rename packages/docs/{main => }/images/block-selection-example.png (100%) rename packages/docs/{main => }/images/block-spec.png (100%) rename packages/docs/{main => }/images/block-std-data-flow.png (100%) rename packages/docs/{main => }/images/blocksuite-cover.jpg (100%) rename packages/docs/{main => }/images/component-types.png (100%) rename packages/docs/{main => }/images/composing-editors-1.png (100%) rename packages/docs/{main => }/images/composing-editors-2.png (100%) rename packages/docs/{main => }/images/context-interleaving.png (100%) rename packages/docs/{main => }/images/crdt-native-data-flow.png (100%) rename packages/docs/{main => }/images/editor-structure.png (100%) rename packages/docs/{main => }/images/encoded-crdt-binary.png (100%) rename packages/docs/{main => }/images/flat-inlines.png (100%) rename packages/docs/{main => }/images/framework-agnostic.png (100%) rename packages/docs/{main => }/images/hello-blocksuite.png (100%) rename packages/docs/{main => }/images/inline-example.png (100%) rename packages/docs/{main => }/images/package-overview.png (100%) rename packages/docs/{main => }/images/pluggable-providers.png (100%) rename packages/docs/{main => }/images/selection-types.png (100%) rename packages/docs/{main => }/images/showcase-doc-edgeless-editors.jpg (100%) rename packages/docs/{main => }/images/showcase-edgeless-perf.jpg (100%) rename packages/docs/{main => }/images/showcase-fragments-1.jpg (100%) rename packages/docs/{main => }/images/showcase-fragments-2.jpg (100%) rename packages/docs/{main => }/images/text-selection-example.png (100%) rename packages/docs/{main => }/index.md (89%) delete mode 100644 packages/docs/main/.vitepress/config.ts rename packages/docs/{main => }/package.json (82%) rename packages/docs/{main => }/presets/doc-editor.md (100%) rename packages/docs/{main => }/presets/edgeless-editor.md (100%) diff --git a/README.md b/README.md index bf647170cb7d..8be31c2ed7e8 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ BlockSuite is a toolkit for building collaborative editors and applications. It - [**`DocEditor`**](https://blocksuite.io/presets/doc-editor.html): **Built entirely from scratch**, `DocEditor` is a comprehensive block-based document editor, offering extensive customization and flexibility. - [**`EdgelessEditor`**](https://blocksuite.io/presets/edgeless-editor.html): **Featuring canvas-based graphics rendering** at its core with sophisticated rich-text features, `EdgelessEditor` offers unique functionalities and decent performance in whiteboard editing. -![showcase-doc-edgeless-editors](./packages/docs/main/images/showcase-doc-edgeless-editors.jpg) +![showcase-doc-edgeless-editors](./packages/docs/images/showcase-doc-edgeless-editors.jpg) The BlockSuite project is structured around key packages that are categorized into two groups: a headless framework and prebuilt editing components. @@ -72,7 +72,7 @@ The BlockSuite project is structured around key packages that are categorized in This can be illustrated as the diagram below: -![package-overview.png](./packages/docs/main/images/package-overview.png) +![package-overview.png](./packages/docs/images/package-overview.png) In addition to extending custom blocks, here are what you can also conveniently achieve with BlockSuite: diff --git a/packages/docs/main/.gitignore b/packages/docs/.gitignore similarity index 100% rename from packages/docs/main/.gitignore rename to packages/docs/.gitignore diff --git a/packages/docs/.vitepress/config.ts b/packages/docs/.vitepress/config.ts new file mode 100644 index 000000000000..c0df3af4891a --- /dev/null +++ b/packages/docs/.vitepress/config.ts @@ -0,0 +1,210 @@ +import { DefaultTheme, defineConfig } from 'vitepress'; +import wasm from 'vite-plugin-wasm'; +import container from 'markdown-it-container'; +import { renderSandbox } from 'vitepress-plugin-sandpack'; + +const guide: DefaultTheme.NavItem[] = [ + { + text: 'Getting Started', + items: [ + { text: 'Overview', link: 'guide/overview' }, + { text: 'Quick Start', link: 'guide/quick-start' }, + ], + }, + { + text: 'Framework Tutorial', + items: [ + { text: 'Component Types', link: 'guide/component-types' }, + { + text: 'Working with Block Tree', + // @ts-ignore + link: 'guide/working-with-block-tree', + items: [ + { + text: 'Block Tree Basics', + link: 'guide/working-with-block-tree#block-tree-basics', + }, + { + text: 'Block Tree in Editor', + link: 'guide/working-with-block-tree#block-tree-in-editor', + }, + { + text: 'Selecting Blocks', + link: 'guide/working-with-block-tree#selecting-blocks', + }, + { + text: 'Service and Commands', + link: 'guide/working-with-block-tree#service-and-commands', + }, + { + text: 'Defining New Blocks', + link: 'guide/working-with-block-tree#defining-new-blocks', + }, + ], + }, + { text: 'Data Synchronization', link: 'guide/data-synchronization' }, + ], + }, + { + text: 'Editor In-Depth', + items: [ + // { text: 'Design Philosophy', link: 'guide/design-philosophy' }, + { + text: 'CRDT-Native Data Flow', + link: 'guide/crdt-native-data-flow', + }, + ], + }, + { + text: 'API Walkthrough', + items: [ + { + text: 'block-std', + items: [ + { + text: 'Block Spec', + link: 'guide/block-spec', + // @ts-ignore + items: [ + { text: 'Block Schema', link: 'guide/block-schema' }, + { text: 'Block Service', link: 'guide/block-service' }, + { text: 'Block View', link: 'guide/block-view' }, + { text: 'Block Widgets', link: 'guide/block-widgets' }, + ], + }, + { + text: 'Selection', + link: 'guide/selection', + }, + { text: 'Event', link: 'guide/event' }, + { text: 'Command', link: 'guide/command' }, + ], + }, + { + text: 'store', + items: [ + { text: 'Page', link: 'guide/store#page' }, + { text: 'Workspace', link: 'guide/store#workspace' }, + { text: 'Slot', link: 'guide/slot' }, + { text: 'Adapter', link: 'guide/adapter' }, + ], + }, + { + text: 'inline', + link: 'guide/inline', + }, + { + text: 'lit', + link: 'guide/lit', + }, + ], + }, + { + text: 'Developing BlockSuite', + items: [ + { + text: 'Building Packages', + link: '//github.com/toeverything/blocksuite/blob/master/BUILDING.md', + }, + { + text: 'Running Tests', + link: '//github.com/toeverything/blocksuite/blob/master/BUILDING.md#testing', + }, + ], + }, +]; + +const reference: DefaultTheme.NavItem[] = [ + { + text: 'API Reference', + items: [ + { text: '@blocksuite/store', link: 'api/@blocksuite/store/index' }, + { + text: '@blocksuite/block-std', + link: 'api/@blocksuite/block-std/index', + }, + { text: '@blocksuite/lit', link: 'api/@blocksuite/lit/index' }, + { text: '@blocksuite/inline', link: 'api/@blocksuite/inline/index' }, + { + text: '@blocksuite/presets', + link: 'api/@blocksuite/presets/index', + }, + { text: '@blocksuite/blocks', link: 'api/@blocksuite/blocks/index' }, + ], + }, +]; + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + vite: { + build: { + target: 'ES2022', + }, + plugins: [wasm()], + }, + lang: 'en-US', + title: 'BlockSuite', + description: 'The Editor Framework', + themeConfig: { + // https://vitepress.dev/reference/default-theme-config + nav: [ + { + text: 'Presets', + items: [ + { text: '📝 DocEditor', link: '/presets/doc-editor' }, + { text: '🎨 EdgelessEditor', link: '/presets/edgeless-editor' }, + ], + }, + { text: 'Guide', link: '/guide/overview' }, + { text: 'API', link: '/api/' }, + // { text: 'Blog', link: '#' }, + { + text: 'Releases', + link: 'https://github.com/toeverything/blocksuite/releases', + }, + ], + + sidebar: { + '/guide/': { base: '/', items: guide }, + '/api/': { base: '/', items: reference }, + }, + + socialLinks: [ + { icon: 'github', link: 'https://github.com/toeverything/blocksuite' }, + { + icon: { + svg: '', + }, + link: 'https://twitter.com/AffineDev', + }, + ], + + footer: { + copyright: 'Copyright © 2022-present Toeverything', + }, + + search: { + provider: 'local', + }, + }, + head: [ + [ + 'link', + { + rel: 'icon', + type: 'image/png', + sizes: '32x32', + href: 'https://raw.githubusercontent.com/toeverything/blocksuite/master/assets/logo.svg', + }, + ], + ], + markdown: { + config(md) { + md.use(container, 'code-sandbox', { + render(tokens, idx) { + return renderSandbox(tokens, idx, 'code-sandbox'); + }, + }); + }, + }, +}); diff --git a/packages/docs/main/.vitepress/theme/index.ts b/packages/docs/.vitepress/theme/index.ts similarity index 100% rename from packages/docs/main/.vitepress/theme/index.ts rename to packages/docs/.vitepress/theme/index.ts diff --git a/packages/docs/main/.vitepress/theme/logo.vue b/packages/docs/.vitepress/theme/logo.vue similarity index 100% rename from packages/docs/main/.vitepress/theme/logo.vue rename to packages/docs/.vitepress/theme/logo.vue diff --git a/packages/docs/main/.vitepress/theme/style.css b/packages/docs/.vitepress/theme/style.css similarity index 100% rename from packages/docs/main/.vitepress/theme/style.css rename to packages/docs/.vitepress/theme/style.css diff --git a/packages/docs/main/components/code-sandbox.vue b/packages/docs/components/code-sandbox.vue similarity index 100% rename from packages/docs/main/components/code-sandbox.vue rename to packages/docs/components/code-sandbox.vue diff --git a/packages/docs/main/adapter.md b/packages/docs/guide/adapter.md similarity index 100% rename from packages/docs/main/adapter.md rename to packages/docs/guide/adapter.md diff --git a/packages/docs/main/block-schema.md b/packages/docs/guide/block-schema.md similarity index 100% rename from packages/docs/main/block-schema.md rename to packages/docs/guide/block-schema.md diff --git a/packages/docs/main/block-service.md b/packages/docs/guide/block-service.md similarity index 100% rename from packages/docs/main/block-service.md rename to packages/docs/guide/block-service.md diff --git a/packages/docs/main/block-spec.md b/packages/docs/guide/block-spec.md similarity index 97% rename from packages/docs/main/block-spec.md rename to packages/docs/guide/block-spec.md index ca42ef4de7ca..afbab563fc61 100644 --- a/packages/docs/main/block-spec.md +++ b/packages/docs/guide/block-spec.md @@ -10,7 +10,7 @@ A block spec contains the following properties: - `component`: The primary user interface element of the block. - `widgets`: Additional interactive elements enhancing the block's functionality. -![block-spec](./images/block-spec.png) +![block-spec](../images/block-spec.png) ## Lit-Based Example diff --git a/packages/docs/main/block-view.md b/packages/docs/guide/block-view.md similarity index 100% rename from packages/docs/main/block-view.md rename to packages/docs/guide/block-view.md diff --git a/packages/docs/main/block-widgets.md b/packages/docs/guide/block-widgets.md similarity index 100% rename from packages/docs/main/block-widgets.md rename to packages/docs/guide/block-widgets.md diff --git a/packages/docs/main/command.md b/packages/docs/guide/command.md similarity index 100% rename from packages/docs/main/command.md rename to packages/docs/guide/command.md diff --git a/packages/docs/main/component-types.md b/packages/docs/guide/component-types.md similarity index 94% rename from packages/docs/main/component-types.md rename to packages/docs/guide/component-types.md index 44f0f8322205..0bce59f815b9 100644 --- a/packages/docs/main/component-types.md +++ b/packages/docs/guide/component-types.md @@ -12,7 +12,7 @@ The `@blocksuite/presets` package includes reusable editors like `DocEditor` and The distinction between editors and fragments lies in their complexity and functionality. **Fragments typically offer more simplified capabilities, serving specific UI purposes, whereas editors provide comprehensive editing capabilities over the block tree**. Nevertheless, both editors and fragments shares similar tech stacks and [data flows](./crdt-native-data-flow). -![showcase-fragments-2](./images/showcase-fragments-2.jpg) +![showcase-fragments-2](../images/showcase-fragments-2.jpg) ## Blocks and Widgets @@ -20,7 +20,7 @@ To address the complexity and diversity of editing needs, BlockSuite architects Within each block spec, there can be [`Widget`](./block-widgets)s specific to that block's implementation, enhancing interactivity within the editor. BlockSuite leverages this widget mechanism to register dynamic UI components such as drag handles and slash menus within the doc editor. -![component-types](./images/component-types.png) +![component-types](../images/component-types.png) ## Composing Editors by Blocks @@ -66,7 +66,7 @@ With very little overhead. So, as long as there is a corresponding `host` implementation, you can use the component model of frameworks like react or vue to implement your BlockSuite editors: -![framework-agnostic](./images/framework-agnostic.png) +![framework-agnostic](../images/framework-agnostic.png) Explore the [`DocEditor` source code](https://github.com/toeverything/blocksuite/blob/master/packages/presets/src/editors/doc-editor.ts) to see how this pattern allows composing minimal real-world editors. @@ -74,7 +74,7 @@ Explore the [`DocEditor` source code](https://github.com/toeverything/blocksuite BlockSuite encourages the derivation of various block spec implementations from a single block model to enrich the editing experience. For instance, the root node of the block tree, the _page block_, is implemented differently for `DocEditor` and `EdgelessEditor` through two different specs **but with the same shared `PageBlockModel`**. The two block specs serve as the top-level UI components for their respective editors: -![showcase-doc-edgeless-editors](./images/showcase-doc-edgeless-editors.jpg) +![showcase-doc-edgeless-editors](../images/showcase-doc-edgeless-editors.jpg) This allows you to **implement various editors easily on top of the same document**, providing diverse editing experiences and great potentials in customizability. diff --git a/packages/docs/main/crdt-native-data-flow.md b/packages/docs/guide/crdt-native-data-flow.md similarity index 95% rename from packages/docs/main/crdt-native-data-flow.md rename to packages/docs/guide/crdt-native-data-flow.md index 066d9782682c..d91515124096 100644 --- a/packages/docs/main/crdt-native-data-flow.md +++ b/packages/docs/guide/crdt-native-data-flow.md @@ -15,7 +15,7 @@ Traditionally, CRDTs have often been seen as a technology specialized in conflic - When the local model is updated, the state of the native model is synchronized to the CRDT model. - When a remote peer is updated, the data resolved from the CRDT model is synchronized back to the native model. -![bidirectional-data-flow](./images/bidirectional-data-flow.png) +![bidirectional-data-flow](../images/bidirectional-data-flow.png) Although this is an intuitive and common practice, it requires synchronization between two heterogeneous models, resulting in a bidirectional data flow. The main issues here are: @@ -30,7 +30,7 @@ As an alternative, BlockSuite chooses to directly use the CRDT model as the sing This design can be represented by the following diagram: -![crdt-native-data-flow](./images/crdt-native-data-flow.png) +![crdt-native-data-flow](../images/crdt-native-data-flow.png) The advantage of this approach is that the application-layer code can **completely ignore whether updates to the block model come from local editing, history stack, or collaboration with other users**. Just subscribing to model update events is adequate. @@ -46,7 +46,7 @@ The complete state update process in BlockSuite involves several distinct steps, 2. **State Manipulation via Commands**: Commands can manipulate the editor state to accomplish UI updates. 3. **State-Driven View Updates**: Upon state changes, slot events are used to notify and update view components accordingly. -![block-std-data-flow](./images/block-std-data-flow.png) +![block-std-data-flow](../images/block-std-data-flow.png) This update mechanism is depicted in the diagram above. Concepts such as [command](./command), [view](./block-view) and [event](./event) are further elaborated in other documentation sections for detailed understanding. diff --git a/packages/docs/main/data-synchronization.md b/packages/docs/guide/data-synchronization.md similarity index 98% rename from packages/docs/main/data-synchronization.md rename to packages/docs/guide/data-synchronization.md index cc178181c893..b764945ff297 100644 --- a/packages/docs/main/data-synchronization.md +++ b/packages/docs/guide/data-synchronization.md @@ -81,6 +81,6 @@ In both cases, whether the document is **loaded** or **created**, the [`page.slo Furthermore, by connecting multiple providers, documents can automatically be synchronized to a variety of different backends: -![pluggable-providers](./images/pluggable-providers.png) +![pluggable-providers](../images/pluggable-providers.png) This brings great flexibility and is the pattern currently being used in [AFFiNE](https://github.com/toeverything/AFFiNE). diff --git a/packages/docs/main/design-philosophy.md b/packages/docs/guide/design-philosophy.md similarity index 95% rename from packages/docs/main/design-philosophy.md rename to packages/docs/guide/design-philosophy.md index b45139f02acf..1b1db32bcea2 100644 --- a/packages/docs/main/design-philosophy.md +++ b/packages/docs/guide/design-philosophy.md @@ -12,7 +12,7 @@ Hence, when discussing front-end collaborative editing (or rich text editing), t In the past years, our team has been dedicated to building a notable open-source knowledge base product ([24k stars on GitHub](https://github.com/toeverything/AFFiNE)). To visualize and organize complex knowledge structures better, we wanted our the editor in our product to be powerful enough, so as to provide an immersive editing and collaboration experience - imagine nesting Google Docs or Notion in an infinite canvas like Figma, as shown below: -![affine-demo](./images/affine-demo.jpg) +![affine-demo](../images/affine-demo.jpg) However, before finding the best practice, our journey in developing editors was full of challenges. At first glance, the front-end community offers many great rich text editors (like [Slate](https://github.com/ianstormtaylor/slate), [Tiptap](https://tiptap.dev/), [Lexical](https://lexical.dev/)) and whiteboard editors (like [tldraw](https://github.com/tldraw/tldraw)), which usually allows the _embedding_ of React components. Bundling various React-compatible editors together seemed convenient - but proved impractical. To some extent, this is like trying to cram several devices supporting the USB protocol into the same shell. Despite sharing the same interface, there's no guarantee the resulting product will work correctly. @@ -29,7 +29,7 @@ We believe that the current mainstream editing frameworks design their data flow Consider a simple example where a text editor A and an image editor B are used together: -![composing-editors-1](./images/composing-editors-1.png) +![composing-editors-1](../images/composing-editors-1.png) For a simple user operation sequence: @@ -37,13 +37,13 @@ For a simple user operation sequence: - Delete the image, which will usually dispose its UI component. - Continue editing the text. -![composing-editors-2](./images/composing-editors-2.png) +![composing-editors-2](../images/composing-editors-2.png) If A and B are independently implemented editors, how should the user operation history be managed? Allowing A and B to maintain their history states seems easier, but neither can hold a complete user operation history. When an editor instance is destroyed, the history stack recording user operations generally disappears. Therefore, this often requires bookkeeping outside these editor instances, which is only the beginning of a series of complexities. Alternatively, in the document-centric model, **we believe that the _document_ - the data layer of the editor, should be maintained completely independent of the editor, allowing the document to persist throughout the application lifecycle**. Thus, no matter if a UI component is part of an editor or not, it should work by simply _**attaching**_ to this document, like this: -![attach-editors](./images/attach-editors.png) +![attach-editors](../images/attach-editors.png) Once the document is separated from the editor, it becomes easy to overcome many difficulties under the editor-centric approach: @@ -115,13 +115,13 @@ To some extent, **this API design is precisely a representation of the document- As shown in the following diagram, the entire `Y.Doc` can be encoded into binary updates like the ones depicted, and all subsequent updates such as `yMap.set()` can also be incrementally encoded into the same binary patch: -![encoded-crdt-binary](./images/encoded-crdt-binary.png) +![encoded-crdt-binary](../images/encoded-crdt-binary.png) This mechanism is similar to git. Each `Y.Doc` works like a git repository, and every operation on the CRDT document, such as `yMap.set()`, is akin to performing a `git commit`. This is because, like git, CRDT records all historical operations but without merge conflicts. Naturally, this also makes history management based on CRDT (akin to `git revert`) possible. These capabilities are sufficient for implementing a complete data layer based on CRDT. Therefore, we chose to implement a common document data layer based on Yjs. This results in the following application data flow: -![crdt-native-data-flow](./images/crdt-native-data-flow.png) +![crdt-native-data-flow](../images/crdt-native-data-flow.png) The blue part owns the full capability to drive UI in complex collaborative applications, including the management of rich text, history, conflict resolution, model update events, etc. This part has a well-defined isolation boundary from UI components and can be used independently of editors. We believe this is the data layer needed for being document-centric. @@ -146,31 +146,31 @@ document.body.appendChild(editor); BlockSuite advocates for assembling the top-level `DocEditor` component from smaller editable components, as all editable components can connect to different nodes in the block tree document. For example, instead of using existing complex rich text editors, BlockSuite implemented a `@blocksuite/inline` rich text component that only supports rendering linear text sequences. Complex rich text content can be assembled from atomic inline editor components, as illustrated: -![inline-example](./images/inline-example.png) +![inline-example](../images/inline-example.png) In the diagram, each inline editor instance connects to a `Y.Text` node in the document tree. It models the data format of rich text as a linear sequence, with expressive power equivalent to the [delta](https://quilljs.com/docs/delta/) format. Thus, all rich text content in the document tree can be split into separate inline editors for rendering, **eliminating the nesting between inline editors**. This significantly lowers the cost of implementing rich text features, as depicted: -![flat-inlines](./images/flat-inlines.png) +![flat-inlines](../images/flat-inlines.png) Since various editors can be loaded and unloaded independently of the document, this allows BlockSuite to support switching between different editors using the same block tree document. Thus, when switching content between document editors and whiteboard editors (which we call `EdgelessEditor`), all operation history recorded on the page can be preserved, rather than reset: -![showcase-doc-edgeless-editors](./images/showcase-doc-edgeless-editors.jpg) +![showcase-doc-edgeless-editors](../images/showcase-doc-edgeless-editors.jpg) Moreover, the separation of document and editor also allows pages to be used independently of editors. This is why BlockSuite not only provides various editor UI components but also many peripheral UI components that rely on page state yet are not part of the editor. We refer to these components as _fragments_. The lifecycle of a fragment can be completely independent of the editor, and it can be implemented with a different technology stack than that used for the editor. For example, the right sidebar in the following diagram belongs to `OutlineFragment`, which facilitates panel arrangement by the application layer (rather than an all-in-one editor): -![showcase-fragments-1](./images/showcase-fragments-1.jpg) +![showcase-fragments-1](../images/showcase-fragments-1.jpg) Furthermore, by supporting a document data layer independent of the editor, we are also able to split traditionally editor-embedded components into independent fragments, thus providing a more unopinionated and reusable `DocEditor`. Areas like the title and page info panel, intuitively part of the editor's internals, can also become examples of fragments: -![showcase-fragments-2](./images/showcase-fragments-2.jpg) +![showcase-fragments-2](../images/showcase-fragments-2.jpg) Additionally, the document-centric approach aids in better separation between the data layer and rendering layer, enabling developers to break free from the typically DOM-based editors, to implement better performance optimization strategies. For example, the BlockSuite document supports a surface block specially designed for rendering graphic content, which could take the advantage of the HTML5 ``. BlockSuite allows these graphic contents to interleave with other block tree contents rendered to the DOM, automatically merging graphic elements into as few canvases as possible to enhance rendering performance: -![context-interleaving](./images/context-interleaving.png) +![context-interleaving](../images/context-interleaving.png) In contrast, when there are 2000 canvas shapes in the documenzt, tldraw, the DOM-based open-source whiteboard, would reaches its limit. At this point, it exhibits noticeable frame drops during viewport panning and zooming, degrading the content to placeholders with React suspense. However, the canvas renderer in BlockSuite could still maintain a frame rate of over 100fps at this time - and don't forget, you can still use the complete DOM-based rich text editing capability! -![showcase-edgeless-perf](./images/showcase-edgeless-perf.jpg) +![showcase-edgeless-perf](../images/showcase-edgeless-perf.jpg) A year after creating BlockSuite, we have not only implemented a collaborative editing framework under the document-centric approach but also delivered an editor product with powerful document editing and canvas whiteboard editing capabilities. Considering the time traditionally required to implement complex rich text editors from scratch, we believe this is a highly efficient pattern. Of course, as a young open-source project, BlockSuite still has many areas for continuous improvement, and we hope you could stay tuned! diff --git a/packages/docs/main/event.md b/packages/docs/guide/event.md similarity index 100% rename from packages/docs/main/event.md rename to packages/docs/guide/event.md diff --git a/packages/docs/main/inline.md b/packages/docs/guide/inline.md similarity index 99% rename from packages/docs/main/inline.md rename to packages/docs/guide/inline.md index 369569c6a9a3..692b0fff8743 100644 --- a/packages/docs/main/inline.md +++ b/packages/docs/guide/inline.md @@ -2,7 +2,7 @@ This package is a minimal rich text component for inline editing. It uses an external [`Y.Text`](https://docs.yjs.dev/api/shared-types/y.text) as it source of truth. Every `inlineEditor` instance attaches to an independant `Y.Text`, so rich text content in different block nodes can be splitted into different inline editors, making complex content conveniently composable. This significantly reduces the complexity required to implement traditional rich text editing features. -![flat-inlines](./images/flat-inlines.png) +![flat-inlines](../images/flat-inlines.png) You can use `InlineEditor` without other BlockSuite dependencies: diff --git a/packages/docs/main/lit.md b/packages/docs/guide/lit.md similarity index 100% rename from packages/docs/main/lit.md rename to packages/docs/guide/lit.md diff --git a/packages/docs/main/overview.md b/packages/docs/guide/overview.md similarity index 86% rename from packages/docs/main/overview.md rename to packages/docs/guide/overview.md index 4fc54b34d4a1..381709f72bb0 100644 --- a/packages/docs/main/overview.md +++ b/packages/docs/guide/overview.md @@ -4,10 +4,10 @@ BlockSuite is a toolkit for building collaborative editors and applications. It - Build new editors from the ground up based on the BlockSuite framework. - Or, reuse multiple first-party BlockSuite editors right out of the box: - - [**`DocEditor`**](./presets/doc-editor): **Built entirely from scratch**, `DocEditor` is a comprehensive block-based document editor, offering extensive customization and flexibility. - - [**`EdgelessEditor`**](./presets/edgeless-editor): **Featuring canvas-based graphics rendering** at its core with sophisticated rich-text features, `EdgelessEditor` offers unique functionalities and decent performance in whiteboard editing. + - [**`DocEditor`**](../presets/doc-editor): **Built entirely from scratch**, `DocEditor` is a comprehensive block-based document editor, offering extensive customization and flexibility. + - [**`EdgelessEditor`**](../presets/edgeless-editor): **Featuring canvas-based graphics rendering** at its core with sophisticated rich-text features, `EdgelessEditor` offers unique functionalities and decent performance in whiteboard editing. -![showcase-doc-edgeless-editors](./images/showcase-doc-edgeless-editors.jpg) +![showcase-doc-edgeless-editors](../images/showcase-doc-edgeless-editors.jpg) The BlockSuite project is structured around key packages that are categorized into two groups: a headless framework and prebuilt editing components. @@ -49,7 +49,7 @@ The BlockSuite project is structured around key packages that are categorized in This can be illustrated as the diagram below: -![package-overview.png](./images/package-overview.png) +![package-overview.png](../images/package-overview.png) In addition to extending custom blocks, here are what you can also conveniently achieve with BlockSuite: diff --git a/packages/docs/main/quick-start.md b/packages/docs/guide/quick-start.md similarity index 100% rename from packages/docs/main/quick-start.md rename to packages/docs/guide/quick-start.md diff --git a/packages/docs/main/selection.md b/packages/docs/guide/selection.md similarity index 97% rename from packages/docs/main/selection.md rename to packages/docs/guide/selection.md index bbfa2ce038a1..ceb247c60b06 100644 --- a/packages/docs/main/selection.md +++ b/packages/docs/guide/selection.md @@ -23,7 +23,7 @@ Page Block So if you select the text partially via mouse drag as following: -![text-selection-example](./images/text-selection-example.png) +![text-selection-example](../images/text-selection-example.png) The selection model will be: @@ -48,7 +48,7 @@ The selection model will be: If you select the blocks via block level selection like this: -![block-selection-example](./images/block-selection-example.png) +![block-selection-example](../images/block-selection-example.png) The selection model will be: diff --git a/packages/docs/main/slot.md b/packages/docs/guide/slot.md similarity index 100% rename from packages/docs/main/slot.md rename to packages/docs/guide/slot.md diff --git a/packages/docs/main/store.md b/packages/docs/guide/store.md similarity index 100% rename from packages/docs/main/store.md rename to packages/docs/guide/store.md diff --git a/packages/docs/main/working-with-block-tree.md b/packages/docs/guide/working-with-block-tree.md similarity index 97% rename from packages/docs/main/working-with-block-tree.md rename to packages/docs/guide/working-with-block-tree.md index 3d5449cee808..7f24efabfec9 100644 --- a/packages/docs/main/working-with-block-tree.md +++ b/packages/docs/guide/working-with-block-tree.md @@ -42,9 +42,9 @@ page.deleteBlock(modelA); This example creates a subset of the block tree hierarchy defaultly used in `@blocksuite/presets`, illustrated as follows: -![block-nesting](./images/block-nesting.png) +![block-nesting](../images/block-nesting.png) -As a document-centric framework, **you need to initialize a valid document structure before attaching it to editors**, which is also why it requires `init()` after `createEmptyPage()`. See [creating new block tree](./data-synchronization#creating-new-block-tree) for more details. +In BlockSuite, you need to initialize a valid document structure before attaching it to editors, which is also why it requires `init()` after `createEmptyPage()`. ::: info The block tree hierarchy is specific to the preset editors. At the framework level, `@blocksuite/store` does **NOT** treat the "first-party" `affine:*` blocks with any special way. Feel free to add blocks from different namespaces for the block tree! @@ -87,7 +87,7 @@ Firstly, let's explain the newly introduced `host` and `std`, which are determin As the runtime for the block tree, this is the mental model inside the `editor`: -![editor-structure](./images/editor-structure.png) +![editor-structure](../images/editor-structure.png) ## Selecting Blocks @@ -111,7 +111,7 @@ In `block-std`, BlockSuite implements several atomic selection types for `Select This allows the selection manager to handle different types of selections, as shown in the following illustration, using the same API: -![selection-types](./images/selection-types.png) +![selection-types](../images/selection-types.png) In `selection.value`, different types of selection states can coexist simultaneously. Each selection object records at least the `id` and `path` of the corresponding selected block (i.e., the sequence of ids of all blocks from the root block to that block). Moreover, you can further categorize different types of selections using the `group` field. For example in `DocEditor`, both `TextSelection` and `BlockSelection` belong to the `note` group. Hence, the example structure of block selection in the above image is as follows: @@ -132,7 +132,7 @@ In `selection.value`, different types of selection states can coexist simultaneo For the more complex native [selection](https://developer.mozilla.org/en-US/docs/Web/API/Selection), the `TextSelection` can be used to model it. It marks the start and end positions of the native selection in the block through the `from` and `to` fields, recording only the `index` and `length` of the inline text sequence in the respective block. This simplification is made possible by the architecture of BlockSuite, where editable blocks use `@blocksuite/inline` as the rich text editing component. Each block tree node's rich text content is rendered independently into different inline editors, eliminating nesting between rich text instances: -![flat-inlines](./images/flat-inlines.png) +![flat-inlines](../images/flat-inlines.png) Additionally, the entire `selection.value` object is isolated under the `clientId` scope of the current session. During collaborative editing, selection instances between different clients will be distributed in real-time (via [providers](./data-synchronization#document-streaming)), facilitating the implementation of UI states like remote cursors. @@ -300,7 +300,7 @@ This design aims at balancing ease of use with customizability. Both the service - A single block to be configured with different widget combinations. For instance, you can remove all widgets to compose read-only editors. - A single block to even be implemented based on different frontend frameworks, by simply providing an `EditorHost` middleware implementation for the respective framework. -![framework-agnostic](./images/framework-agnostic.png) +![framework-agnostic](../images/framework-agnostic.png) ::: info diff --git a/packages/docs/main/images/affine-demo.jpg b/packages/docs/images/affine-demo.jpg similarity index 100% rename from packages/docs/main/images/affine-demo.jpg rename to packages/docs/images/affine-demo.jpg diff --git a/packages/docs/main/images/attach-editors.png b/packages/docs/images/attach-editors.png similarity index 100% rename from packages/docs/main/images/attach-editors.png rename to packages/docs/images/attach-editors.png diff --git a/packages/docs/main/images/bidirectional-data-flow.png b/packages/docs/images/bidirectional-data-flow.png similarity index 100% rename from packages/docs/main/images/bidirectional-data-flow.png rename to packages/docs/images/bidirectional-data-flow.png diff --git a/packages/docs/main/images/block-nesting.png b/packages/docs/images/block-nesting.png similarity index 100% rename from packages/docs/main/images/block-nesting.png rename to packages/docs/images/block-nesting.png diff --git a/packages/docs/main/images/block-selection-example.png b/packages/docs/images/block-selection-example.png similarity index 100% rename from packages/docs/main/images/block-selection-example.png rename to packages/docs/images/block-selection-example.png diff --git a/packages/docs/main/images/block-spec.png b/packages/docs/images/block-spec.png similarity index 100% rename from packages/docs/main/images/block-spec.png rename to packages/docs/images/block-spec.png diff --git a/packages/docs/main/images/block-std-data-flow.png b/packages/docs/images/block-std-data-flow.png similarity index 100% rename from packages/docs/main/images/block-std-data-flow.png rename to packages/docs/images/block-std-data-flow.png diff --git a/packages/docs/main/images/blocksuite-cover.jpg b/packages/docs/images/blocksuite-cover.jpg similarity index 100% rename from packages/docs/main/images/blocksuite-cover.jpg rename to packages/docs/images/blocksuite-cover.jpg diff --git a/packages/docs/main/images/component-types.png b/packages/docs/images/component-types.png similarity index 100% rename from packages/docs/main/images/component-types.png rename to packages/docs/images/component-types.png diff --git a/packages/docs/main/images/composing-editors-1.png b/packages/docs/images/composing-editors-1.png similarity index 100% rename from packages/docs/main/images/composing-editors-1.png rename to packages/docs/images/composing-editors-1.png diff --git a/packages/docs/main/images/composing-editors-2.png b/packages/docs/images/composing-editors-2.png similarity index 100% rename from packages/docs/main/images/composing-editors-2.png rename to packages/docs/images/composing-editors-2.png diff --git a/packages/docs/main/images/context-interleaving.png b/packages/docs/images/context-interleaving.png similarity index 100% rename from packages/docs/main/images/context-interleaving.png rename to packages/docs/images/context-interleaving.png diff --git a/packages/docs/main/images/crdt-native-data-flow.png b/packages/docs/images/crdt-native-data-flow.png similarity index 100% rename from packages/docs/main/images/crdt-native-data-flow.png rename to packages/docs/images/crdt-native-data-flow.png diff --git a/packages/docs/main/images/editor-structure.png b/packages/docs/images/editor-structure.png similarity index 100% rename from packages/docs/main/images/editor-structure.png rename to packages/docs/images/editor-structure.png diff --git a/packages/docs/main/images/encoded-crdt-binary.png b/packages/docs/images/encoded-crdt-binary.png similarity index 100% rename from packages/docs/main/images/encoded-crdt-binary.png rename to packages/docs/images/encoded-crdt-binary.png diff --git a/packages/docs/main/images/flat-inlines.png b/packages/docs/images/flat-inlines.png similarity index 100% rename from packages/docs/main/images/flat-inlines.png rename to packages/docs/images/flat-inlines.png diff --git a/packages/docs/main/images/framework-agnostic.png b/packages/docs/images/framework-agnostic.png similarity index 100% rename from packages/docs/main/images/framework-agnostic.png rename to packages/docs/images/framework-agnostic.png diff --git a/packages/docs/main/images/hello-blocksuite.png b/packages/docs/images/hello-blocksuite.png similarity index 100% rename from packages/docs/main/images/hello-blocksuite.png rename to packages/docs/images/hello-blocksuite.png diff --git a/packages/docs/main/images/inline-example.png b/packages/docs/images/inline-example.png similarity index 100% rename from packages/docs/main/images/inline-example.png rename to packages/docs/images/inline-example.png diff --git a/packages/docs/main/images/package-overview.png b/packages/docs/images/package-overview.png similarity index 100% rename from packages/docs/main/images/package-overview.png rename to packages/docs/images/package-overview.png diff --git a/packages/docs/main/images/pluggable-providers.png b/packages/docs/images/pluggable-providers.png similarity index 100% rename from packages/docs/main/images/pluggable-providers.png rename to packages/docs/images/pluggable-providers.png diff --git a/packages/docs/main/images/selection-types.png b/packages/docs/images/selection-types.png similarity index 100% rename from packages/docs/main/images/selection-types.png rename to packages/docs/images/selection-types.png diff --git a/packages/docs/main/images/showcase-doc-edgeless-editors.jpg b/packages/docs/images/showcase-doc-edgeless-editors.jpg similarity index 100% rename from packages/docs/main/images/showcase-doc-edgeless-editors.jpg rename to packages/docs/images/showcase-doc-edgeless-editors.jpg diff --git a/packages/docs/main/images/showcase-edgeless-perf.jpg b/packages/docs/images/showcase-edgeless-perf.jpg similarity index 100% rename from packages/docs/main/images/showcase-edgeless-perf.jpg rename to packages/docs/images/showcase-edgeless-perf.jpg diff --git a/packages/docs/main/images/showcase-fragments-1.jpg b/packages/docs/images/showcase-fragments-1.jpg similarity index 100% rename from packages/docs/main/images/showcase-fragments-1.jpg rename to packages/docs/images/showcase-fragments-1.jpg diff --git a/packages/docs/main/images/showcase-fragments-2.jpg b/packages/docs/images/showcase-fragments-2.jpg similarity index 100% rename from packages/docs/main/images/showcase-fragments-2.jpg rename to packages/docs/images/showcase-fragments-2.jpg diff --git a/packages/docs/main/images/text-selection-example.png b/packages/docs/images/text-selection-example.png similarity index 100% rename from packages/docs/main/images/text-selection-example.png rename to packages/docs/images/text-selection-example.png diff --git a/packages/docs/main/index.md b/packages/docs/index.md similarity index 89% rename from packages/docs/main/index.md rename to packages/docs/index.md index 81a8e25504ae..457127ea1655 100644 --- a/packages/docs/main/index.md +++ b/packages/docs/index.md @@ -12,7 +12,7 @@ hero: actions: - theme: brand text: Get Started - link: /overview + link: /guide/overview - theme: alt text: DocEditor link: /presets/doc-editor @@ -23,14 +23,14 @@ hero: features: - title: 🧩 Headless Editor Framework details: BlockSuite defines the meta framework for building various editors, enabling the design of diverse and adaptable editing interfaces. - link: /overview + link: /guide/overview linkText: Learn More - title: 🧬 Collaborative at Core details: Powered by CRDT, BlockSuite supports document streaming and conflict resolution at its heart, ready for collaboration inherently. - link: /crdt-native-data-flow + link: /guide/crdt-native-data-flow linkText: Learn More - title: 🎨 Extensive Components details: BlockSuite ships a comprehensive set of editing component presets, assisting development with adaptable building blocks. - link: /component-types + link: /guide/component-types linkText: Learn More --- diff --git a/packages/docs/main/.vitepress/config.ts b/packages/docs/main/.vitepress/config.ts deleted file mode 100644 index f362b8adf09b..000000000000 --- a/packages/docs/main/.vitepress/config.ts +++ /dev/null @@ -1,200 +0,0 @@ -import { defineConfig } from 'vitepress'; -import wasm from 'vite-plugin-wasm'; -import container from 'markdown-it-container'; -import { renderSandbox } from 'vitepress-plugin-sandpack'; - -// https://vitepress.dev/reference/site-config -export default defineConfig({ - vite: { - build: { - target: 'ES2022', - }, - plugins: [wasm()], - }, - lang: 'en-US', - title: 'BlockSuite', - description: 'The Editor Framework', - themeConfig: { - // https://vitepress.dev/reference/default-theme-config - nav: [ - { - text: 'Presets', - items: [ - { text: '📝 DocEditor', link: '/presets/doc-editor' }, - { text: '🎨 EdgelessEditor', link: '/presets/edgeless-editor' }, - ], - }, - { text: 'Docs', link: '/overview' }, - // { text: 'Blog', link: '#' }, - { - text: 'Releases', - link: 'https://github.com/toeverything/blocksuite/releases', - }, - ], - - sidebar: [ - { - text: 'Getting Started', - items: [ - { text: 'Overview', link: '/overview' }, - { text: 'Quick Start', link: '/quick-start' }, - ], - }, - { - text: 'Tutorial', - items: [ - { text: 'Component Types', link: '/component-types' }, - { - text: 'Working with Block Tree', - link: '/working-with-block-tree', - items: [ - { - text: 'Block Tree Basics', - link: '/working-with-block-tree#block-tree-basics', - }, - { - text: 'Block Tree in Editor', - link: '/working-with-block-tree#block-tree-in-editor', - }, - { - text: 'Selecting Blocks', - link: '/working-with-block-tree#selecting-blocks', - }, - { - text: 'Service and Commands', - link: '/working-with-block-tree#service-and-commands', - }, - { - text: 'Defining New Blocks', - link: '/working-with-block-tree#defining-new-blocks', - }, - ], - }, - { text: 'Data Synchronization', link: '/data-synchronization' }, - ], - }, - { - text: 'Editor In-Depth', - items: [ - // { text: 'Design Philosophy', link: '/design-philosophy' }, - { - text: 'CRDT-Native Data Flow', - link: '/crdt-native-data-flow', - }, - ], - }, - { - text: 'API Walkthrough', - items: [ - { - text: 'block-std', - items: [ - { - text: 'Block Spec', - link: '/block-spec', - items: [ - { text: 'Block Schema', link: '/block-schema' }, - { text: 'Block Service', link: '/block-service' }, - { text: 'Block View', link: '/block-view' }, - { text: 'Block Widgets', link: '/block-widgets' }, - ], - }, - { - text: 'Selection', - link: '/selection', - }, - { text: 'Event', link: '/event' }, - { text: 'Command', link: '/command' }, - ], - }, - { - text: 'store', - items: [ - { text: 'Page', link: '/store#page' }, - { text: 'Workspace', link: '/store#workspace' }, - { text: 'Slot', link: '/slot' }, - // { text: 'Transformer 🚧' }, - { text: 'Adapter', link: '/adapter' }, - ], - }, - { - text: 'inline', - link: '/inline', - }, - { - text: 'lit', - link: '/lit', - }, - ], - }, - { - text: 'API Reference', - items: [ - { text: '@blocksuite/store', link: '/api/@blocksuite/store/index' }, - { - text: '@blocksuite/block-std', - link: '/api/@blocksuite/block-std/index', - }, - { text: '@blocksuite/lit', link: '/api/@blocksuite/lit/index' }, - { text: '@blocksuite/inline', link: '/api/@blocksuite/inline/index' }, - { - text: '@blocksuite/presets', - link: '/api/@blocksuite/presets/index', - }, - { text: '@blocksuite/blocks', link: '/api/@blocksuite/blocks/index' }, - ], - }, - { - text: 'Developing BlockSuite', - items: [ - { - text: 'Building Packages', - link: 'https://github.com/toeverything/blocksuite/blob/master/BUILDING.md', - }, - { - text: 'Running Tests', - link: 'https://github.com/toeverything/blocksuite/blob/master/BUILDING.md#testing', - }, - ], - }, - ], - - socialLinks: [ - { icon: 'github', link: 'https://github.com/toeverything/blocksuite' }, - { - icon: { - svg: '', - }, - link: 'https://twitter.com/AffineDev', - }, - ], - - footer: { - copyright: 'Copyright © 2022-present Toeverything', - }, - - search: { - provider: 'local', - }, - }, - head: [ - [ - 'link', - { - rel: 'icon', - type: 'image/png', - sizes: '32x32', - href: 'https://raw.githubusercontent.com/toeverything/blocksuite/master/assets/logo.svg', - }, - ], - ], - markdown: { - config(md) { - md.use(container, 'code-sandbox', { - render(tokens, idx) { - return renderSandbox(tokens, idx, 'code-sandbox'); - }, - }); - }, - }, -}); diff --git a/packages/docs/main/package.json b/packages/docs/package.json similarity index 82% rename from packages/docs/main/package.json rename to packages/docs/package.json index 818b7048d71d..150aa36c3575 100644 --- a/packages/docs/main/package.json +++ b/packages/docs/package.json @@ -1,7 +1,7 @@ { - "name": "@blocksuite/docs-main", + "name": "@blocksuite/docs", "version": "0.11.0", - "description": "BlockSuite main site documentation", + "description": "BlockSuite documentation", "private": true, "keywords": [], "author": "toeverything", @@ -16,7 +16,7 @@ "vue": "^3.4.15" }, "scripts": { - "typedoc": "pnpm -C ../../.. build:packages && typedoc --options ../../../typedoc.json", + "typedoc": "pnpm -C ../.. build:packages && typedoc --options ../../typedoc.json", "dev": "pnpm run typedoc && vitepress dev --port 5200", "dev:nobuild": "vitepress dev --port 5200", "build": "pnpm run typedoc && vitepress build", diff --git a/packages/docs/main/presets/doc-editor.md b/packages/docs/presets/doc-editor.md similarity index 100% rename from packages/docs/main/presets/doc-editor.md rename to packages/docs/presets/doc-editor.md diff --git a/packages/docs/main/presets/edgeless-editor.md b/packages/docs/presets/edgeless-editor.md similarity index 100% rename from packages/docs/main/presets/edgeless-editor.md rename to packages/docs/presets/edgeless-editor.md diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5fca642f0b28..f1ce43967f55 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -295,17 +295,17 @@ importers: specifier: ^1.15.7 version: 1.15.7 - packages/docs/main: + packages/docs: dependencies: '@blocksuite/blocks': specifier: workspace:* - version: link:../../blocks + version: link:../blocks '@blocksuite/presets': specifier: workspace:* - version: link:../../presets + version: link:../presets '@blocksuite/store': specifier: workspace:* - version: link:../../store + version: link:../store markdown-it-container: specifier: ^4.0.0 version: 4.0.0 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 6369db61dcf2..735eac04a846 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,7 +1,7 @@ packages: - 'packages/block-std' - 'packages/blocks' - - 'packages/docs/main' + - 'packages/docs' - 'packages/global' - 'packages/inline' - 'packages/lit' diff --git a/typedoc.json b/typedoc.json index dc0e9de4e04d..d8a9aa46c745 100644 --- a/typedoc.json +++ b/typedoc.json @@ -8,7 +8,7 @@ "packages/inline" ], "plugin": ["typedoc-plugin-markdown"], - "out": "packages/docs/main/api", + "out": "packages/docs/api", "entryPointStrategy": "packages", "includeVersion": false, "logLevel": "Error",