docs: make clear that type selectors are just examples

[ooker777]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)
• If applicable, I’ve added docs and tests

Description of changes

See https://github.com/orgs/syntax-tree/discussions/131

[ChristianMurphy]

Thanks @ooker777! 👋

There are some broader question that should probably be discussed before updating the docs.

1. How familiar are you with CSS? Are more links to general CSS docs needed?
2. How familiar are you with the different unified syntax trees? (https://unifiedjs.com/learn/) This project works across all of them, not just one.

There is probably room to improve the documentation, it would be good in a way that is general enough to represent a variety of use cases, not one very specific use case.

A few thoughts on the example here.

1. This package implements CSS selectors, CSS is an entire language, it feels off trying to explain what selectors are here.
2. unist-util-select works on any unist compatible tree, including mdast, hast, nlcst dotast, xast, ntast, and more. It feels off referencing only one.

[ooker777]

1. Just for my background, I have made 2 small scale webapp with Deno Fresh. In CSS I have experience in Tailwind and have implement an UI component lib. But I don't have much experience working on vanilla CSS
2. I am new with the syntax trees, and while I have read the docs and get some basic concepts, I don't think I have had a good mental model on how the whole project works

More are provided in the comment below

[wooorm]

I don’t think this is needed. This project defers to CSS. If you want to use CSS, you can use this.
This is a table of which CSS things work here too.
It contains examples, and then the names.
The latter name is enough to know that the former is an example

The change, to focus soleley on mdast, is also not good; we do not only support mdast here.

[ooker777]

Thanks. I am new to this project, and didn't expect that my PR get the attention of two members. I think I had wasted your time, so sorry about that. You can choose to close this. I just think that someone may need an extra explanation that you can use any node type on that. Because I think it's not actual CSS, so there is a chance that individual type has to be supported. So if it's not in the list it's likely to not be supported yet

[wooorm]

Don’t worry about getting attention from us! ;)

I don’t really see it. The next lines talk about combinators. Showing blockquote paragraph, blockquote > paragraph, code + paragraph, code ~ paragraph. It doesn’t make sense that paragraph is the only value that could work? Where could those new words suddenly come from otherwise? The only sensical thing is that code or blockquote both work, too.

And, the words type selector. This is a word from CSS selectors: https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors/Type_Class_and_ID_Selectors. Like the other terms here. Combinators. Pseudo-classes. All of this is from CSS.

The list here is not to be taken literally. And also not just all possible examples. It’s pseudo-code in-between. Which I believe is right. A correct mix between knowledge levels.

There will always be people who don’t understand a sentence, for one reason or another. We can’t explain every term. Or: we could, but then the resources get too verbose for folks that have more knowledge.

Thank you, for sharing what’s complex for you. Even if this doesn’t land now, it helps us understand what people struggle with!