search

markdown-it / markdown-it-container

Fenced container plugin for markdown-it markdown parser
MIT License
496 stars 74 forks source link

Improve instructions for browser users. #34

Closed GarrettAlbright closed 4 years ago

GarrettAlbright commented 4 years ago

If I may soapbox for a minute…

I've been doing research into in-browser Markdown editors and parsers over the last couple weeks for a client project, and all of the ones who have substantial activity in the last couple years all seem very Node-centric, most critically in terms of documentation. Far be it for me to tell other OSS devs how to run their projects, but it really makes me, who only writes JS for browser use and has no interest in doing otherwise, feel like a second-class citizen. Now I know all the cool kids are rewriting the entire world in Node nowadays, but I'm really hoping that today's modern JS library maintainers can remember that there's still a bunch of us old neckbeards trying to figure out how to use their stuff in a browser, where documentation becomes instantly useless the moment it tells us to use require().

With the help of #2, I got markdown-it-container working great for my client's project now, so through this pull request, I'm moving the OSS JavaScript library world a little closer to the world I'd like to see. The format of the changes vaguely match those on the main markdown-it README.

puzrin commented 4 years ago

IMO no need to fill readme with basic js programming things. That's not specific to this project.

GarrettAlbright commented 4 years ago

Hmm.

Again, if I may, your perspective is tinted from being in the Node.js world. Please imagine that you've never used Node.js, and you've never used Bower, but you want to use this project on the client side. Re-read the README.md with that mindset. How would someone without that knowledge know how to use this library? How would they get the main Markdown-it library and this one to communicate with each other? I've been building web sites since 1995, and professionally since 2007, and it took me about half an hour to figure it out.

For Pete's sake, if you do nothing else, please at least correct the "bower/browser" typo.

puzrin commented 4 years ago

I agree, someone can have principle position to not learn nodejs, bundlers and so on. But this should not become problem of this [and any other] repo.