The instructions known as “Basic”, at https://prosemirror.net/examples/basic/, seem to assume that the viewer already has quite a bit of knowledge but without giving too much information on what that knowledge is.
I’ve just started experimenting a bit with bundling of JavaScript, but the different types of scripts involved, different ways to bundle and such, seems to be a bit of a jungle. If the viewer is only interested in learning it in order to use ProseMirror (as in my case), then it seems difficult to figure out exactly what knowledge must be acquired in order to successfully set up a working example of ProseMirror.
In general, I’ve found it easiest to get to know new technologies by following tutorials on whatever I’m trying to set up. But I can’t seem to find a tutorial on ProseMirror that leads the user from start to finish.
Is such a tutorial in existence? If not, then is anyone interested in making one? Even if it were rather crude, I think it might drastically ease the process for new users to immerse themselves in whatever scripts, processes and technologies involved.
I don’t think such a tutorial exists. The thing about ProseMirror is that the library, out of the box, is too minimal to really use without building something on top of it—it’s more of a skeleton for various kinds of editors than an actual editor. So one of the reasons our docs don’t try to target people without much experience is that such people are likely to have a bad time with the library anyway—the task of integrating it will require quite a lot of additional programming.
I’ve been hoping that people would build more approachable editor components on top of ProseMirror, but so far only tiptap really does that, and that uses Vue.js so I’m not sure it’d be what you’re looking for.
And I completely agree with the project owner’s remark that this is not an _editing widget, but rather a platform for developing such a widget. It’s such a well structured project that a lot can be learned from studying it.
I have no problem with acquiring new knowledge or experience. My problem is that I can’t figure out what experience I need to acquire. The only instruction I can find is that I should use a “bundler”, but the moment I delve into that, I run into a bit of a jungle, and I’m fine with finding my way through a jungle, provided that I know where I’m trying to get in the first place. That element seems missing. I don’t know how to tie together the general information from various bundling introductions on the one hand, and ProseMirror on the other. I normally don’t have this problem when learning how to use a new library, technology or programming language, which is why I believe there’s a “missing link” in the documentation that gets a developer going, regardless of whether they’re interested in an editor for a website, or in making a full-blown editor with ProseMirror.
I would suggest that the lack of some sort of tutorial, that shows how the library can be used to create an editor, is the reason. Libraries typically come with some sort of tutorial to show how they’re used and that’s what seems to be missing.
But also to add a bit of preponderence, I’m not quite sure why this distinction between a platform to create editors and a fully working editor needs to be maintained. It’s just a matter of showing how it works. I can’t imagine any scenario where less information on how something works is likely to stear either the development process or widespread adoption in a better direction than providing more information.
Perhaps I’m misunderstanding something here, in which case I apologize in advance. I’m a bit confused over this, to be honest.
Hot tip on bundling, @teekin , learn webpack! It’s a beast, but singly the most powerful and comprehensive web front-end tool you’ll come across. And if you haven’t dabbled in reactive JS, learn Vue.js (in my opinion, Vue.js is the saviour of web development, it also works best with webpack and the team that wrote it have a nice webpack setup out of the box!) So that’s half the jungle neatly macheted for you unfortunately I think @marijn is on point about tutorials… it’d end up being a book to try and cover all the different ways in which you could implement a build (if someone feels like writing ProseMirror in Action with me though…!)
Speaking of Vue.js, a couple of us Prose Mirror nerds (to my knowledge) are building Vue.js based projects from the ground up (@marijn mentioned tiptap: that’s a very pain-free open-source way to setup prose mirror if/when you learn Vue. TipTap is a superb project).
the route into ECMA6+ webdev is kind of daunting, but it’ll pay you back in the long run!
one suggestion @marijn (appreciating that it’s a big ask though I’m sure a number of us would be happy to help out) with respect to accessibility: Prose Mirror’s ref docs could - IMO - stand to have some stubs demonstrating things in a bit more detail. I find reading formative method definitions a bit hard to get my head round sometimes; I’ve resorted to looking at stubs on the discussion forum but I suspect a lot of questions that get asked on here might be mitigated with some more examples.
But there is a “hidden” de facto example that can be copied: namely the prosemirror site itself. See its git repository. By looking at the Makefile and the scripts in the bin directory, one can figure out how to use Prosemirror.
In fact this is a fairly complete example since it has embedded prosemirror examples.
If you just want to be able to play around with the editor you can clone prosemirror and edit/run the demo.
This is useful to do anyways, or at least it really helped me understand how everything was connected, and later as I started needing to write custom commands, plugins, etc, having the code cloned locally really helped.
Although I do second what @jaysaurus said. I think the written docs are great, but the reference docs are hard to understand. I get why, lots of the concepts are hard to explain, but more code examples would help a lot. I initially found myself constantly searching this forum to understand things.
I’m in the same boat. I use PureScript for developing my apps and haven’t written an app with plain JS since 2013, so the whole JS module ecosystem is completely uninteresting to me and has completely passed me by.
In 2021, you can’t write a JS program without a build system, and there are various tools required to understand. And the tutorials are usually out of date. I’m attempting to manage this complexity with a Dockerfile, but gave up.
Everything in the ProseMirror APIs is low-level in a good way and is exactly what I want. But this build system stuff is depressing.
With CodeMirror, I was able to just add codemirror.js to my web page and then consult the API reference.
In the end, my solution is to download the examples/ version of prosemirror.js file from the examples and check it into my project, because those examples use a simple global object. Unfortunately, this is unversioned. However, the ProseMirror API seems to be pretty stable, so I’ll take my chances and just check it in with a date.
I’ll take a look.
unfortunately I think 