docs: add caution about scripts processing when using head config #1729
Conversation
|
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
There was a problem hiding this comment.
Thank you for the PR @jorenbroekema! Super helpful to have suggestions like this and know which parts of our docs tripped people up. Left one suggestion.
| :::caution | ||
| Scripts are placed into head using the `set:html` directive which is similar to using `is:inline` in that it [precludes these scripts from being processed by Astro](https://docs.astro.build/en/guides/client-side-scripts/#opting-out-of-processing). | ||
| This means that if you want to include a local script and you need this to be processed, you'll probably need to [override or extend the Head component](/guides/overriding-components/#reuse-a-built-in-component). | ||
| ::: |
There was a problem hiding this comment.
Instead of a caution, I think we can add a clear description of how this does work (rather than specifying how it doesn’t):
| :::caution | |
| Scripts are placed into head using the `set:html` directive which is similar to using `is:inline` in that it [precludes these scripts from being processed by Astro](https://docs.astro.build/en/guides/client-side-scripts/#opting-out-of-processing). | |
| This means that if you want to include a local script and you need this to be processed, you'll probably need to [override or extend the Head component](/guides/overriding-components/#reuse-a-built-in-component). | |
| ::: | |
| Entries in `head` are converted directly to HTML elements and do not pass through Astro’s script or style processing. | |
| If you need to import local assets like scripts, styles, or images, [override the Head component](/guides/overriding-components/#reuse-a-built-in-component). |
This also helps us make this a bit simpler because we don’t need to explain too much all these other things which head isn’t, instead focusing on the simpler case of what it is.
There was a problem hiding this comment.
Done, I did embed a link to the Astro style and script docs in case users reading this will want to learn what this style and script processing is all about
jorenbroekema
force-pushed
the
scripts-doc
branch
from
89ea00d
to
072e5ce
Compare
Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com> Co-authored-by: pioupia <49518790+pioupia@users.noreply.github.com>
* main: (32 commits) i18n(pt-br): Update `getting-started.mdx` (withastro#1776) i18n(es): update `configuration` (withastro#1766) [ci] format Add TrueCharts to showcases (withastro#1773) i18n(zh-cn): Update `sidebar.mdx` (withastro#1761) i18n(ko-KR): update `sidebar.mdx` (withastro#1760) i18n(fr): update `guides/sidebar` (withastro#1758) test: fix Windows path separator test issues (withastro#1759) i18n(fr): Update `reference/configuration.mdx` from withastro#1729 (withastro#1757) docs: rewrite `guides/sidebar` examples to be more generic (withastro#1751) i18n(ja): Update community-content.mdx (withastro#1756) i18n(ja): Update configuration.mdx (withastro#1755) i18n(zh-cn): Update `configuration.mdx` (withastro#1753) i18n(ko-KR): update `configuration.mdx` (withastro#1752) docs: add caution about scripts processing when using head config (withastro#1729) i18n(es): update `community-content` (withastro#1740) i18n(pt-br): Update `resources/community-content.mdx` (withastro#1747) format: quick fix [ci] format [ci] format ...
Description
headconfig option, and what to do if you need scripts to be processed by Astro