docs: Quote block investigation fixes (#1576)

* Fixed a bunch of docs annoyances

* Fixed theming

* Reverted frontmatter deletions & `ImageBlockContent` changes

* Fixed `async` types in docs

Author: matthewlipski

docs/components/ThemedImage.tsx

@@ -6,9 +6,9 @@ export function ThemedImage(
     darkImage: React.ComponentProps<typeof Image>["src"];
   } & React.ComponentProps<typeof Image>,
 ) {
-  const { theme } = useTheme();
+  const { resolvedTheme } = useTheme();
   const { darkImage, ...rest } = props;
-  if (theme === "dark") {
+  if (resolvedTheme === "dark") {
     // eslint-disable-next-line jsx-a11y/alt-text
     return <Image {...rest} src={darkImage} />;
   } else {

docs/components/example/ThemedExample.tsx

@@ -6,11 +6,11 @@ import { examples } from "./generated/exampleComponents.gen";
 export default function ThemedExample(props: { name: keyof typeof examples }) {
   const example = examples[props.name];
   const App = example.App;
-  const { theme } = useTheme();
+  const { resolvedTheme } = useTheme();
 
   return (
     <BlockNoteContext.Provider
-      value={{ colorSchemePreference: theme === "dark" ? "dark" : "light" }}>
+      value={{ colorSchemePreference: resolvedTheme === "dark" ? "dark" : "light" }}>
       <App />
     </BlockNoteContext.Provider>
   );

docs/pages/docs/advanced/grid-suggestion-menus.mdx

@@ -5,6 +5,7 @@ imageTitle: Grid Suggestion Menus
 ---
 
 import { Example } from "@/components/example";
+import { ThemedImage } from "@/components/ThemedImage";
 
 # Grid Suggestion Menus
 
@@ -18,10 +19,12 @@ The Emoji Picker is a Grid Suggestion Menu that opens with the `:` character (or
 
 It only displays once the user types 2 non-whitespace characters a query, to minimize cases where the user only wants to enter the `:` character.
 
-<img
-  style={{ maxWidth: "400px" }}
+<ThemedImage
   src="/img/screenshots/emoji_picker.png"
+  darkImage="/img/screenshots/emoji_picker_dark.png"
   alt="image"
+  width={400}
+  height={400}
 />
 
 ### Changing Emoji Picker Columns

docs/pages/docs/collaboration/real-time-collaboration.mdx

@@ -4,14 +4,19 @@ description: Let's see how you can add Multiplayer capabilities to your BlockNot
 imageTitle: Real-time Collaboration
 ---
 
+import { ThemedImage } from "@/components/ThemedImage";
+
 # Real-time Collaboration (multiplayer text editor)
 
 Let's see how you can add Multiplayer capabilities to your BlockNote setup, and allow real-time collaboration between users (similar to Google Docs):
 
-<img
-  style={{ maxWidth: "300px", border: "1px solid gray" }}
+<ThemedImage
+  style={{ border: "1px solid gray" }}
   src="/img/features/collaboration_light.gif"
+  darkImage="/img/features/collaboration_dark.gif"
   alt="text editing collaboration"
+  width={300}
+  height={300}
 />
 
 _Try the live demo on the [homepage](https://www.blocknotejs.org)_

docs/pages/docs/custom-schemas/custom-blocks.mdx

@@ -46,10 +46,12 @@ const Alert = createReactBlockSpec(
 The Block Config describes the shape of your custom blocks. Use it to specify the type, properties (props) and content your custom blocks should support:
 
 ```typescript
-type CustomBlockConfig = {
+type BlockConfig = {
   type: string;
   content: "inline" | "none";
   readonly propSchema: PropSchema;
+  isSelectable?: boolean;
+  hardBreakShortcut?: "shift+enter" | "enter" | "none";
 };
 ```
 
@@ -87,6 +89,16 @@ type PropSchema<
 
 _In the alert demo, we add a `type` prop for the type of alert that we want (warning / error / info / success). We also want basic styling options, so we add text alignment and text color from the [Default Block Properties](/docs/block-types#default-block-properties)._
 
+**`isSelectable`**
+
+Can be set to false in order to make the block non-selectable, both using the mouse and keyboard. This also helps with being able to select non-editable content within the block. Should only be set to false when `content` is `none` and defaults to true.
+
+**`hardBreakShortcut`**
+
+Defines which keyboard shortcut should be used to insert a hard break into the block's inline content. Defaults to `"shift+enter"`.
+
+##### File Block Config
+
 #### Block Implementation (`ReactCustomBlockImplementation`)
 
 The Block Implementation defines how the block should be rendered in the editor, and how it should be parsed from and converted to HTML.
@@ -146,3 +158,11 @@ const schema = BlockNoteSchema.create({
 ```
 
 You can then instantiate your editor with this custom schema, as explained on the [Custom Schemas](/docs/custom-schemas) page.
+
+### Improving the User Experience
+
+Now you know how to create a custom block and add it to your editor. However, users don't have a way of creating instances of it to their documents.
+
+To fix this, it's recommended to implement a [command to insert your custom in the Slash Menu](/docs/ui-components/suggestion-menus#changing-slash-menu-items), and [an item for it in the Block Type Select](/docs/ui-components/formatting-toolbar#changing-block-type-select-items). The demo below builds upon the earlier alert block example, adding both of these.
+
+<Example name="custom-schema/alert-block-full-ux" />

docs/pages/docs/editor-api/converting-blocks.mdx

@@ -28,10 +28,10 @@ BlockNote can import / export Blocks to and from Markdown. Note that this is als
 `blocksToMarkdownLossy` converts `Block` objects to a Markdown string:
 
 ```typescript
-blocksToMarkdownLossy(blocks?: Block[]): string;
+async blocksToMarkdownLossy(blocks?: Block[]): Promise<string>;
 
 // Usage
-const markdownFromBlocks = editor.blocksToMarkdownLossy(blocks);
+const markdownFromBlocks = await editor.blocksToMarkdownLossy(blocks);
 ```
 
 `blocks:` The blocks to convert. If not provided, the entire document (all top-level blocks) is used.
@@ -49,10 +49,10 @@ The output is simplified as Markdown does not support all features of BlockNote
 Use `tryParseMarkdownToBlocks` to try parsing a Markdown string into `Block` objects:
 
 ```typescript
-tryParseMarkdownToBlocks(markdown: string): Blocks[];
+async tryParseMarkdownToBlocks(markdown: string): Promise<Blocks[]>;
 
 // Usage
-const blocksFromMarkdown = editor.tryParseMarkdownToBlocks(markdown);
+const blocksFromMarkdown = await editor.tryParseMarkdownToBlocks(markdown);
 ```
 
 `returns:` The blocks parsed from the Markdown string.
@@ -72,10 +72,10 @@ For example, you an use this for static rendering documents that have been creat
 Make sure to include the same stylesheets when you want to render the output HTML ([see example](/examples/backend/rendering-static-documents)).
 
 ```typescript
-blocksToFullHTML(blocks?: Block[]): string;
+async blocksToFullHTML(blocks?: Block[]): Promise<string>;
 
 // Usage
-const HTMLFromBlocks = editor.blocksToFullHTML(blocks);
+const HTMLFromBlocks = await editor.blocksToFullHTML(blocks);
 ```
 
 `blocks:` The blocks to convert. If not provided, the entire document (all top-level blocks) is used.
@@ -93,10 +93,10 @@ Converting Blocks to HTML this way will lose some information such as the nestin
 Use `blocksToHTMLLossy` to export `Block` objects to an HTML string:
 
 ```typescript
-blocksToHTMLLossy(blocks?: Block[]): string;
+async blocksToHTMLLossy(blocks?: Block[]): Promise<string>;
 
 // Usage
-const HTMLFromBlocks = editor.blocksToHTMLLossy(blocks);
+const HTMLFromBlocks = await editor.blocksToHTMLLossy(blocks);
 ```
 
 `blocks:` The blocks to convert. If not provided, the entire document (all top-level blocks) is used.
@@ -114,10 +114,10 @@ To better conform to HTML standards, children of blocks which aren't list items
 Use `tryParseHTMLToBlocks` to parse an HTML string to `Block` objects:
 
 ```typescript
-tryParseHTMLToBlocks(html: string): Blocks[];
+async tryParseHTMLToBlocks(html: string): Promise<Blocks[]>;
 
 // Usage
-const blocksFromHTML = editor.tryParseHTMLToBlocks(html);
+const blocksFromHTML = await editor.tryParseHTMLToBlocks(html);
 ```
 
 `returns:` The blocks parsed from the HTML string.

docs/pages/docs/editor-basics/document-structure.mdx

@@ -3,6 +3,7 @@ description: Learn how documents (the content of the rich text editor) are struc
 ---
 
 import { Example } from "@/components/example";
+import { ThemedImage } from "@/components/ThemedImage";
 
 # Document Structure
 
@@ -13,10 +14,13 @@ Learn how documents (the content of the rich text editor) are structured to make
 Each BlockNote document is made up of a list of blocks.
 A block is a piece of content like a paragraph, heading, list item or image. Blocks can be dragged around by users in the editor. A block contains a piece of content and optionally nested (child) blocks:
 
-<img
+<ThemedImage
+  style={{ marginTop: "1em" }}
   src="/img/screenshots/block_structure.png"
+  darkImage="/img/screenshots/block_structure_dark.png"
   alt="image"
-  style={{ width: "100%", marginTop: "1em" }}
+  width={2000}
+  height={2000}
 />
 
 ### Block Objects

docs/pages/docs/ui-components/formatting-toolbar.mdx

@@ -6,15 +6,18 @@ path: /docs/formatting-toolbar
 ---
 
 import { Example } from "@/components/example";
+import { ThemedImage } from "@/components/ThemedImage";
 
 # Formatting Toolbar
 
 The Formatting Toolbar appears whenever you highlight text in the editor.
 
-<img
-  style={{ maxWidth: "600px" }}
+<ThemedImage
   src="/img/screenshots/formatting_toolbar.png"
+  darkImage="/img/screenshots/formatting_toolbar_dark.png"
   alt="image"
+  width={600}
+  height={600}
 />
 
 ## Changing the Formatting Toolbar

docs/pages/docs/ui-components/image-toolbar.mdx

@@ -6,12 +6,19 @@ path: /docs/image-toolbar
 ---
 
 import { Example } from "@/components/example";
+import { ThemedImage } from "@/components/ThemedImage";
 
 # Image Toolbar
 
 The Image Toolbar appears whenever you select an image that doesn't have a URL, or when you click the "Replace Image" button in the [Formatting Toolbar](/docs/formatting-toolbar) when an image is selected.
 
-<img style={{maxWidth: "600px"}} src="/img/screenshots/image_toolbar.png" alt="image" />
+<ThemedImage
+  src="/img/screenshots/image_toolbar.png"
+  darkImage="/img/screenshots/image_toolbar_dark.png"
+  alt="image"
+  width={600}
+  height={600}
+/>
 
 ## Image Upload
 

docs/pages/docs/ui-components/side-menu.mdx

@@ -6,23 +6,28 @@ path: /docs/side-menu
 ---
 
 import { Example } from "@/components/example";
+import { ThemedImage } from "@/components/ThemedImage";
 
 # Block Side Menu
 
 The Block Side Menu appears on the left side whenever you hover a block. By default, it consists of a `+` button and a drag handle (`⠿`):
 
-<img
-  style={{ maxWidth: "500px" }}
+<ThemedImage
   src="/img/screenshots/side_menu.png"
-  alt="Side menu"
+  darkImage="/img/screenshots/side_menu_dark.png"
+  alt="image"
+  width={500}
+  height={500}
 />
 
 Clicking the drag handle (`⠿`) in the Block Side Menu opens the Drag Handle Menu:
 
-<img
-  style={{ maxWidth: "250px" }}
+<ThemedImage
   src="/img/screenshots/drag_handle_menu.png"
+  darkImage="/img/screenshots/drag_handle_menu_dark.png"
   alt="image"
+  width={250}
+  height={250}
 />
 
 ## Changing the Block Side Menu