Document custom blocks

[airtonix]

Keystatic should aim to support at its core the ability to add our own field (and collection types if that can be done)

Coming from TheOtherPopularPlatform™️ , people would probably expect it to be able to:

• [ ] define the field storage data type
• [ ] define serialiser and deserialiser behaviour
• [ ] define how the UI of the field functions

additionally, (and seperately)

• [ ] define a plugin type for the wysiwyg/markdown editor

Something that didn't make sense to me from TheOtherPopularPlatform™️ was

• [ ] define how the renderable preview result would look while in the cms? Why cant we just support Customising how an item in a collection is rendered as a preview?

[JedWatson]

Hey @airtonix thanks for all the feedback, both here and in other issues. We'll get through them individually in the near future and reply to all of it.

On this specific one, the gap is just docs 🙂

(it's probably worth leaving this issue open until those docs are ready though)

In terms of custom field types; all the built-in field functions are just first party implementations of things you can do in user land. Each field type defines how the data is serialised and deserialised, the storage type, and the UI. So all of them can be replaced (or entirely new ones created) in a project without needing any changes in Keystatic.

And in terms of plugins for the WYSIWYG editor, that's also in place, although we are planning some things to make it easier to build your own (including high level components for things like floating toolbars, etc)

The editor is a modified version of the one we built for KeystoneJS, you can see a demo with proper documentation here: https://keystonejs.com/docs/guides/document-field-demo

Basically, you can define as many component types as you like with fields (conceptually very similar to writing a react component and specifying prop types), and either go with the default or provide your own custom component to render the preview, even disabling the default UI in favour of your own (we call this "chromeless" mode)

I'll update here when we have better examples + docs online of how to use all of this, in the meantime please keep the suggestions coming!

Thanks

[JPrisk]

Hey @airtonix, although not perfect - here is an example implementation of a custom colour picker https://github.com/Thinkmill/keystatic-starter-portfolio/pull/1/files