Documentation

[nicolopadovan]

There is no documentation available regarding this package.

[christianhg]

I hear you! We definitely need to add some docs for this package.

[nicolopadovan]

I hear you! We definitely need to add some docs for this package.

Great!
Would it be possible to receive some WIP documentation in the meantime?
I would love to add a Portable Text Editor within my website for my admins.

@christianhg

[christianhg]

Absolutely. I'll see what I can do next week. Although I have some plans for shaping up the package a bit to make it easier to use outside the Sanity Studio. So I might introduce a few breaking changes soon.

Would you mind sharing a bit more about your use case and plans with the PTE?

[nicolopadovan]

Absolutely. I'll see what I can do next week. Although I have some plans for shaping up the package a bit to make it easier to use outside the Sanity Studio. So I might introduce a few breaking changes soon.

Would you mind sharing a bit more about your use case and plans with the PTE?

Thanks!
Regarding my use case: I always try to create custom and ad-hoc administration portals for my clients, since they sometimes are not too educated regarding technology.
Hence, I usually create portals that are outside of the Sanity Studio, in order to provide them with just the essential and with a highly usable interface, customized precisely for their requirements.

[christianhg]

Interesting! Thanks for elaborating. Do you plan to store the data yourself or does that still go to the Sanity Content Lake?

[nicolopadovan]

Interesting! Thanks for elaborating. Do you plan to store the data yourself or does that still go to the Sanity Content Lake?

It still goes to Sanity Content Lake! And I use Sanity Studio myself when I get asked to manage their data.

[nicolopadovan]

@christianhg Let me know whether or not the documentation could be published any time soon; otherwise I will try to find a workaround using React Quill and then converting it to Portable Text, and then switch some time in the future when the package's documentation will be published.
Thanks again!

[christianhg]

Hi @nicolopadovan. Sorry about the delay.

I know it's not perfect, but perhaps it gets you started to take a look at the playground I'm building?

It already showcases a few concepts, like you how you configure the schema for the editor, listen for mutations, build a basic toolbar and control the rendering of different elements: https://github.com/portabletext/editor/blob/main/apps/playground/src/editor.tsx#L84

It should be said, though, that we are not yet close to being able to offer an out-of-the-box experience that matches Quill. For now, you'd need to hand-roll more functionality yourself if you use @portabletext/editor, but our plan is to eventually offer core plugins so you can hit the ground running.

[nicolopadovan]

I'll try to work with it and see what I can do. Thanks!

[javayhu]

@christianhg hello christianhg, thanks for your efforts of making this editor.

I'm not that familiar with frontend tech stack, and take a little time to clone this repository and run it on local. Is there any simple example for me to integrate this editor into a Nextjs project? should I add these 2 dependencies into my package.json file? or should I copy the packages folder of this project into my Nextjs project?

"@portabletext/editor": "^1.0.18",
"@portabletext/patches": "^1.1.0",

Thanks.

[nicolopadovan]

@christianhg

Regarding this issue and more broadly the repo itself: it would be great to have some more precise documentation both for having users test the package already, and because of the fact that React Quill (which is the main alternative, with the help of Sanity Block Tools) has basically been discontinued and must be currently used from unofficial forks.
This could also have a great impact on the package potential popularity, finally bringing PortableText to a more mainstream audience.

[javayhu]

@nicolopadovan hi, I also noticed Sanity Block Tools, and tried very hard to find a React Rich Text Editor to work with it, but didn't find any example of how a React Rich Text Editor with Sanity Block Tools can produce Portable Text and then save to Sanity dataset. At last, I find portable-text/editor, it seems like the right solution, but still I do not know how to use it.

Anyway, do you have any example of how React Quill with Sanity Block Tools can output Portable Text? and what do you mean the fact that React Quill (which is the main alternative, with the help of Sanity Block Tools) has basically been discontinued and must be currently used from unofficial forks.? Is there any repo for me to give it a try?

[nicolopadovan]

@javayhu
React Quill New is the fork I have found that is currently working, since the official project seems to have been abandoned.

Sources:
zenoamaro/react-quill#997
zenoamaro/react-quill#991
https://www.npmjs.com/package/react-quill-new

To use the Sanity block tools, you need a tool that produces rich text as HTML content (in this case, React Quill).
Then you input the HTML content into the block tools, and it outputs portable text.

import { htmlToBlocks } from '@sanity/block-tools' // this is the function you need

Although this is not a discussion directly related on that, but on Portable Text Editor, I can see it as related as a temporary workaround.

Another workaround is provided by @javayhu, but uses another approach (uses Markdown instead of HTML and adds the related plugin to Sanity. Myself, I prefer to avoid adding complexity to Sanity).

Edit: rewrote the comment with specifics and code

[javayhu]

@nicolopadovan @christianhg currently I use sanity-plugin-markdown in studio and react-simplemde-editor in frontend, to implement my project as a workaround. hopefully someday I can switch them all to portable text editor, thanks.

[azzlack]

@christianhg Will there be any support for using this without using Sanity? I see Sanity is a dependency today. Looking for an alternative to Plate, and i really like the Portabletext format.

[nicolopadovan]

@christianhg Will there be any support for using this without using Sanity? I see Sanity is a dependency today. Looking for an alternative to Plate, and i really like the Portabletext format.

Given the power of PortableText, I’m guessing in the future it could be more standard across multiple platforms and service.
Am as well interested in knowing this

[christianhg]

Hi there! It's true that there are some @sanity/* dependencies in here and while I'll gradually work on removing those (because it would be a bit cleaner), they are not a showstopper for using @portabletext/editor as a standalone editor. I'm planning to write some initial docs very, very soon.

[Ali-Hussein-dev]

Is there any simple example that we can use to learn how to use the package? The playground folder contains examples that cover advanced features and it uses xState to manage the editor state, which makes it hard to get started. @christianhg Can you help with a simple example?

[christianhg]

Hi again. I've now made a basic example app using the editor and also added some initial docs to the README based on this example.

There are more docs and new APIs coming, but hopefully the above is helpful to some of you who wish to get started.

Please let me know if you have any feedback. I will keep expanding the docs based on the areas you find are unclear.

[Ali-Hussein-dev]

thanks @christianhg the basic example is much easier to follow and understand how things is working.

one question, some modules show me they are not exported from @portabletext/editor like useEditor, defineSchem, PortableTextBlock and PortableTextChild. The example works fine and updated to the latest version 1.5.4, What am I missing something here?

[christianhg]

@Ali-Hussein-dev , could you try to upgrade the package and see if the problem persists? Is it a dependency issue? Were the peer dependencies correctly installed?

[Ali-Hussein-dev]

@Ali-Hussein-dev , could you try to upgrade the package and see if the problem persists? Is it a dependency issue? Where the peer dependencies correctly installed?

After upgrading, type errors are gone!

[christianhg]

Just want to let you all know, we have an all-new docs site for the editor: https://www.portabletext.org/

I'll take the liberty and close this issue now, but please do not hesitate to open new issues if there are specific things in the docs you find confusing. PRs for the docs are also welcome.

[nicolopadovan]

@christianhg
That's great! Thank you so much for the effort and the response to the community!
I will let you know if I find something to fix :)