search

cssinjs / jss

JSS is an authoring tool for CSS which uses JavaScript as a host language.
https://cssinjs.org
MIT License
7.08k stars 399 forks source link

Lack of documentation #1472

Closed JonasRosenqvist closed 3 years ago

JonasRosenqvist commented 3 years ago

I can't seem to find any actual documentation of the features of JSS. In particular, I don't know where the syntax is defined. Has it been copied from a pre-existing framework that I'm unfamiliar with? If so, it would be great if this could be clearly stated somewhere. I know it's claimed that the documentation can be found at https://cssinjs.org/, but I only find examples, showcases, installation guides etc. Examples of questions I have include: what does the "&" sign mean and how can it be used? When is the feature know as jss-expand applicable? When it comes to keys with white-spaces, why are some converted to camleCase while others are but in quotation marks? What's the difference? Where is the API documentation that answers these questions?

kof commented 3 years ago

The problem is that & syntax is implemented in a jss-plugin-nested syntax, core syntax is https://cssinjs.org/jss-syntax?v=v10.6.0

If you have an idea how to make this problem with docs go away, please propose

kof commented 3 years ago

When it comes to keys with white-spaces, why are some converted to camleCase while others are but in quotation marks?

That is just javascript restrictions, space can't be a key without quotes

kof commented 3 years ago

Created a separate issue for learning the syntax in one place https://github.com/cssinjs/jss/issues/1473

kof commented 3 years ago

Let me know if this issue doesn't cover everything you asked. We don't really want to cover javascript basics though.

JonasRosenqvist commented 3 years ago

Thanks @kof ! I think that covers it. I had actually missed your first link (https://cssinjs.org/jss-syntax?v=v10.6.0) entirely. I obviously could have looked more carefully and found it, but I think it might be better to break out Packages > JSS Core > API and Styles Syntax and make it much more visible, possibly under Introduction. Here one might also mention that much more features are available as plugins, give a few examples, and link down to Packages. It might also be worth keeping in mind that a lot of users don't actively chose jss. For example, I'm using the material-ui framework in a React project, which in turn is using jss with various plugins. I only found this this site after going looking for API documentation of what I originally thought was an internal material-ui feature. My point here is that some users (like me) don't even know what packages are being used because their intermediate framework isn't transparent about it.

kof commented 3 years ago

If you like to contribute to solving that documentation problem, lets discuss the details in that issue referenced above, closing this one