Add usage docs

[johno]

We should provide basic installation and usage instructions.

[100ideas]

Regarding architecture, could you explain a little about your chose of slate-react vs others? Did you consider prosemirror or remirror (react interface on top of prosemirror)?

[johno]

That's a great question @100ideas!

In terms of architecture, we needed something that allowed us to introduce underlying editor functionality and have the ability to customize rendering. This is important because the Blocks editor is essentially emulating an MDX document and has some special needs as a result.

Originally I looked into using content editable directly, but unsurprisingly, got to learn about all those quirks. This was when the library search began.

I built out a small prototype with Draft.js originally but found it to be too restrictive. This made me realize that something built around plugins, custom nodes, and custom rendering was something that'd be important for making this all work due to the needs of MDX emulation.

When weighing libraries Prosemirror was definitely in the picture but I gravitated towards Slate because I appreciated the focus on plugins and the plugin pipeline that allows you to layer in functionality as needed that could essentially control all aspects of the editor. Not to mention serialization in Slate has a bunch of existing libraries to draw inspiration from to handle transformation between MDX and Slate schema.

It also helped knowing that GitBook uses Slate and they're a popular product in the WYSIWYG space. Granted, they're now running their own fork for their own performance needs, but for me that's not a concern at this early of a stage in development.

Hopefully this helps answer your question 🤷‍♂

[100ideas]

Yes, that's a great answer. I feel torn b/w slate & prosemirror (the latter b/c NYtimes & guardian use it), but until a robost react layer like remirror matures, I too would start prototyping w/ slate.

[100ideas]

Have you given any thought to state management of multiple blocks?

1. how could the data context of multiple blocks be composed into a reactive dependancy graph?

2. how could said graph be serialized in parallel to blocks?

[johno]

I haven't given any thought to state management amongst multiple Blocks. For now that's outside the scope since I want to build a unicycle or scooter before the Ferrari 😆.

However, since the serialization format is MDX, which in turn means JSX/React. So custom components passed to the editor itself can handle their own state management which is exactly what they'd be doing when built for production. We essentially get it all for free. Similarly to how MDXProvider context is used to render the components in the editor (which is sooooo rad) consumed Blocks that are rendered can pull in shared context and handle it accordingly.

<SomeCustomProvider>
  <Editor
    value={someMDX}
    blocks={{ SomeGraph, SomeSlabStat }}
  />
</SomeCustomProvider>

Above, SomeGraph and SomeSlabStat tie into SomeCustomProvider and handle any reactivity/state handling that's relevant to them. Then any actions that might update the global state/context can be handled at the React rendering layer for Nodes in the Slate editor.

This is essentially what we intend to do for more robust and complex Blocks down the road.