docs: add caution about scripts processing when using head config#1729
docs: add caution about scripts processing when using head config#1729delucis merged 2 commits intowithastro:mainfrom
Conversation
|
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
delucis
left a comment
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
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