Section Headings and Tables of Contents

[fantasyui-com]

I am looking at http://staging.sass-lang.com/documentation/functions/color and it is hard to find things.

Here is what I think maybe more helpful (page is not about sass, but you get the idea).

I looked at #245 but I didn't understand where the changes were made, I hope I am not interrupting anyone.

The tiny TOC, I mention would list all the function names in context of http://staging.sass-lang.com/documentation/functions/color (adjust-color, adjust-hue, etc...) It would be extremely helpful for newcomers.

As a side note, (I don't want to open another issue for this) conditional statements are stored under at-rules, that's hard to find. If I may, I think we need to present sass as a language first, so the language reference sections would be more like: Comments, Variables, Interpolation, Strings, Numbers, Lists/Maps, Conditional Statements, Loops, Mixins, Functions, etc.

And we need supported/unsupported indicator for https://github.com/sass/sass or just add "Dart Sass/Js Sass" in the existing section.

I know that what you have created thus far is done with experience and wisdom, and foresight, and proper context. I just wanted you to know that opening http://staging.sass-lang.com/documentation/functions/color feels like looking at a single blob of text, and it frightens me, and probably others too.

Thank You.

[nex3]

@jina What do you think about having page-specific tables of contents for the function docs?

@fantasyui-com Are the subsections in the sass:math documentation the sort of thing you're looking for?

As a side note, (I don't want to open another issue for this) conditional statements are stored under at-rules, that's hard to find. If I may, I think we need to present sass as a language first, so the language reference sections would be more like: Comments, Variables, Interpolation, Strings, Numbers, Lists/Maps, Conditional Statements, Loops, Mixins, Functions, etc.

That would add a lot of vertical space to the top-level table of contents, and I think it could also be confusing if things that are clearly at-rules weren't categorized as such.

And we need supported/unsupported indicator for https://github.com/sass/sass or just add "Dart Sass/Js Sass" in the existing section.

I'm not sure what you mean by this.

[fantasyui-com]

Yup, page-specific tables of contents for the function docs would do it.

Yes, with a TOC up top, it would be nice to have the subsections as in the sass:math documentation. Just to see where things start and end.

As to at rules, your wisdom should rule. But as a user I couldn't find "If Statements" I had to google SASS cheatsheet to learn about your language. There is no time to take tutorials, in the documentation. There is only time to look in a menu and scan for "Condictional" or "Logic" or something like that. It is good to underline the fact that those are at rules. but tucking away Conditional statements under something that does not sound like conditial statements (If, Logic, etc) is what got me.

As to "supported/unsupported indicator" I am sorry I was unclear, and I maybe mistaken about this, I mean this (doodled in red):

I am a https://github.com/sass/sass user, which is described as "the pure JavaScript implementation of Sass" in the README.md and that's not featured in the "supported/unsupported indicator" row/section. When I look on github dart and js are separate repositories:

And I just found "Both major Sass implementations support the same JavaScript API. Dart Sass is distributed as the pure-Javascript sass package, and LibSass is distributed as a native extension in the node-sass package. on the https://sass-lang.com/documentation/js-api page. This is burried under https://sass-lang.com/documentation/js-api

Also "Ruby Sass has reached end of life and is now totally unmaintained. Please switch to Dart Sass or LibSass at your earliest convenience." is burried on https://sass-lang.com/documentation/cli/ruby-sass

WARNING: I AM STILL MISUNDERSTANDING THINGS HERE
So to fix the problem you have to either call (I am referring to the "supported/unsupported indicator") "Dart Sass" as sass, or split "Dart Sass" into "sass" and "Dart Sass"

Unified Version

Split Version

And it would be amazing if you linked to the code repositories.

The problem that started this, is me not being able to use @use and color.adjust with node-sass. I maybe mistaken here, maybe node-sass does support @use and color.adjust statement and I was just doing something wrong. I switched to sass (as opposed to node-sass) and @use/color.adjust statement worked.

I understand that the c++ libsass is packaged as node-sass, and that sass is dart transpired into js, and that Dart Sass is also a command line program, Ruby is out, nope...

END OF WARNING: I AM STILL UNSURE BUT I GOT IT

see, I dind't understand.

I do now, sass is dart-sass(dart)
node-sass is libsass(c++)

If you, in your wisdom find a way to express this in that "supported/unsupported indicator" your new users will not be confused about what is what.

So, here is what the bar should look like (if I understood correctly)

(you can eliminate the parentheses by just linking to repositories.)

So, you see, I still got it wrong, but I think I got it right in the end.

RTFM is the the right advice for me, but you have the power to turn the language reference into something that will click with speed learner/readers and awesome noobs (comme moi ).

Nobody would ever learn PHP is they were sent to the docs first.

I learned sass from here: https://devhints.io/sass that is just not fair to you and your hard work.

Thank You.