Add a warning about dynamic tags and reword another in Template Directives

[ArmandPhilippot]

📚 Subject area/topic

Templates directives

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/reference/directives-reference/

📋 Description of content that is out-of-date or incorrect

I noted two improvements more or less related that can be made on the "Template Directives" page. I could open a pull request but:

1. I'm not sure what is the best approach to improve the documentation in relation to your style guide,
2. I'm not enough familiar with the internal mechanism of Astro to be accurate.

define:vars section

The issue

Using define:vars on a <style /> tag in a component which depends on dynamic tags does not work. An issue was reported on the Astro repository but has been closed. It seems a fix is not planned. So I think it would be worth mentioning it in the documentation.

My concerns

There is already a warning about <script /> tags:

So I'm not sure what is the best approach to differentiate the two warnings:

• two warning blocks with an explicit title for each (I never saw this pattern on your documentation),
• a warning block for <script /> and a note block for <style /> (I saw an example of two different blocks next to each other in the documentation),
• a single generic "Caution" block with the two warnings next to each other (it can be confusing if the two warnings are not related since the current warning is already multi-lines... I don't know if there is any relation between the the two behaviors),
• to consider the <style /> tag case as less important and to put it in a new paragraph between the code block and the warning block (there is a similar mention on the "Client directives" section: "Hydration directives are not supported when using dynamic tags".

Proposal

Regardless of the chosen format, we could add the following sentences:

The `define:vars` directive is not supported when using [dynamic tags](https://docs.astro.build/en/core-concepts/astro-syntax/#dynamic-tags). If you cannot wrap the children with an extra element like a `div`, the best approach is to manually add a ``style={`--myVar:${value}`}`` to your `Element`.

is:inline section

Issue

There is a warning block about the directive being applied automatically for any attribute other than src for both <script /> and <style /> tags:

But in the next section (define:vars), the warning only mentions the <script /> tag:

Using `define:vars` on a `<script>` tag implies the [`is:inline` directive](https://docs.astro.build/en/reference/directives-reference/#isinline)

There was a previous issue (#3165) about is:inline behavior with define:vars. It seems the statement in is:inline section is wrong: using define:vars on <style /> tag does not automatically apply the is:inline directive.

So I think the warning block in is:inline section should be reworded to reflect the current behavior.

Proposal

Most of the attributes used on a `<script>` or `<style>` tag will imply the `is:inline` directive. The few exceptions are the `src` attribute and, only on the `<style>` tag, the [`define:vars` directive](https://docs.astro.build/en/reference/directives-reference/#definevars).

Perhaps I'm wrong but the lang attribute (ie. <style lang="scss">) does not apply the is:inline directive. Maybe it should be added to the list to prevent confusion.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

About the define:vars bug, here is the StackBlitz from the original issue (not mine): https://stackblitz.com/edit/astro-minimal-example-custom-tags?file=README.md