Missing stylesheets documentation?


#1

I’m trying to get a basic ProseMirror setup going, following examples shown at https://prosemirror.net/examples/basic/ and Using with React but the styling was non-existent. I initially dragged in the following two stylesheets:

import 'prosemirror-view/style/prosemirror'
import 'prosemirror-example-setup/style/style'

…but the styling was all wonky:

I then tried grepping around for the classes that seem to be missing and found this:

$ pwd
/workplace/editor-experiments/node_modules
$ find prosemirror-* -type f -name '*.css' | xargs grep ProseMirror-menubar
prosemirror-menu/style/menu.css:.ProseMirror-menubar {

Once I added import 'prosemirror-menu/style/menu', I was up and running, but I was more than a little surprised that I had to include a stylesheet from a package that I didn’t have to explicitly include in my project…and there are no docs that I could see that explicitly called this out:

$ grep prosemirror package.json
    "prosemirror-example-setup": "^1.0.1",
    "prosemirror-model": "^1.6.1",
    "prosemirror-schema-basic": "^1.0.0",
    "prosemirror-schema-list": "^1.0.1",
    "prosemirror-state": "^1.2.2",
    "prosemirror-view": "^1.5.1",

It would be really helpful if this didn’t take so much sleuthing to get stood up…I’m embarrassed to admit how much time it took me to figure out how to solve this problem. :-\


#2

Hey there, i completely understand your point, i was struggling with that as well when i started using ProseMirror. I think it’s important to consider the following lines from the ProseMirror guides:

The core library is not an easy drop-in component—we are prioritizing modularity and customizeability over simplicity, with the hope that, in the future, people will distribute drop-in editors based on ProseMirror. As such, this is more of a Lego set than a Matchbox car.

When working with ProseMirror you’ll notice that you have to read through a lot of example code as well as the various repos (for example the example setup repo). The ‘implicit’ documentation that is provided through all these repos and examples is great, but it takes some extra time to figure it all out.


#3

Thank you. I appreciate the timely response.

I can’t help but wonder if this approach isn’t self-defeating. One can still take a “building blocks” approach to a project and still have good, solid documentation that doesn’t leave the user surprised in the end. When I see examples of how to do something in code documentation, I am expecting that it’ll just work if I follow it faithfully…so when it doesn’t, it’s frustrating. This erodes my confidence in the whole project because that little voice inside me starts saying “What other surprises are lying in wait for me that are going to cause me pain in the future?”

-dan


#4

I don’t want to speak on behalf of the creator, but i think the decision to prefer modularity and customizability over simplicity was made very deliberately, and this will probably not change any time soon. I’d recommend to give the library a try, because the documentation is fantastic, there are a lot of examples, and the core maintainer is very supportive on this board.

About the surprises… yes, there will be surprises. For example, you’ll be surprised how well the api is thought out and how well the editor behaves. In my opinion it is worth it to dig deep and give it a try :slight_smile:

And about your original problem with the style sheets: yes, maybe it would make sense to drop a line somewhere at the beginning of the guide that one should import these styles. The problem is that in the examples hosted on Glitch, the sources are bundled specifically for that, and it isn’t visible to the user what styles need to be imported.


#5

By no means does modularity justify poor docs. What happens here is that the example-setup and menu modules aren’t really considered core modules (we expect most sites will want to implement something more custom tailored), so their docs aren’t really on the level of the core’s docs. Still, a note about the CSS files could be added to prosemirror-example-setup’s README.md to hopefully steer the next user in the right direction. Do you want to create a pull request?


#6

FWIW, I handled the situation in a more blunt-force (not for prod) method in this ‘starter’ repo:

For the CSS in the simple HTML page storing the document, I concatenated style/style.css from the repo prosemirror-example-setup with the contents of editor.css, a file included in the Basic Setup example on the ProseMirror site, easily copied from the browser.

HTH