docs(solid-meta): add useHead reference #1387
Conversation
|
|
✅ Deploy Preview for solid-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
LadyBluenotes
left a comment
LadyBluenotes
left a comment
There was a problem hiding this comment.
Thank you for putting in the work for this! I have some changes to keep it consistent with the other pages :)
|
|
||
| ## When to use useHead | ||
|
|
||
| - Insert tags without built-in components, such as `script` and `noscript`. | ||
| - Control SSR output with `setting.close` and `setting.escape`. | ||
| - Inject per-page structured data like JSON-LD. | ||
| - Reuse an existing element via `ref`. | ||
|
|
||
| ## Prefer components when possible | ||
|
|
||
| Use the dedicated components when they fit your use case: | ||
|
|
||
| - [`<Title />`](/solid-meta/reference/meta/title) for page titles. | ||
| - [`<Meta />`](/solid-meta/reference/meta/meta) for metadata. | ||
| - [`<Link />`](/solid-meta/reference/meta/link) for external resources. | ||
| - [`<Style />`](/solid-meta/reference/meta/style) for inline styles. | ||
| - [`<Base />`](/solid-meta/reference/meta/base) for base URLs. | ||
|
|
||
| They provide clearer intent and sensible defaults. |
There was a problem hiding this comment.
We generally try to avoid explanations in the reference section, since its goal is to document the API surface as clearly and directly as possible. We generally try to avoid explanations in the reference section, since its goal is to document the API surface as clearly and directly as possible. Keeping references concise makes them easier to scan and helps readers quickly understand what exists and how it’s shaped, without additional narrative getting in the way.
With that in mind, do you mind removing these sections?
There was a problem hiding this comment.
Thanks for the feedback! Sure, I can remove those sections.
| ## Notes | ||
|
|
||
| ### SSR and hydration | ||
|
|
||
| On the server, tags are collected and rendered into `<head>`. | ||
| During hydration, tags with matching `id` values are reused. | ||
| On client-only renders, existing server tags are removed and replaced. | ||
|
|
||
| ### Dedupe and idempotency | ||
|
|
||
| For `title` and `meta`, only the most recent tag with the same key is kept. | ||
| The key is derived from the tag name and selected attributes. | ||
| For `meta`, the key uses `name` (or `property`), `http-equiv`, `content`, `charset`, and `media`. | ||
| For `title`, the key does not include any attributes. | ||
| Other tag types are not deduped. | ||
| The `id` does not control deduping. | ||
| It ensures hydration can reuse the same element instead of inserting a duplicate. | ||
|
|
||
| ### Reactive updates and cleanup | ||
|
|
||
| `useHead` runs inside a render effect. | ||
| If your tag description reads reactive values, the tag updates when those values change. | ||
| When the component unmounts, the tag is removed and any previous cascading tag is restored. | ||
|
|
||
| ### Security and escaping | ||
|
|
||
| Use `setting.escape: true` when inserting untrusted content. | ||
| Setting `escape: false` renders raw HTML and can create XSS risks. | ||
| Only use `escape: false` with trusted, pre-serialized strings such as JSON-LD. | ||
|
|
||
| ### Best practices | ||
|
|
||
| Use stable, unique `id` values to avoid duplicates. | ||
| Prefer the dedicated head components when they meet your needs. | ||
| Avoid inserting multiple tags that represent the same metadata unless you intend to override. |
There was a problem hiding this comment.
Similar to the comment above, we want to avoid adding any of these explanation points to the page.
There was a problem hiding this comment.
Thank you so much for your help and the detailed feedback on the PR, it was extremely helpful. I believe I’ve incorporated all the feedback into the code. When you have a chance, could you please review the latest changes?
Co-authored-by: Sarah <hello@sarahgerrard.me>
Co-authored-by: Sarah <hello@sarahgerrard.me>
Co-authored-by: Sarah <hello@sarahgerrard.me>
Co-authored-by: Sarah <hello@sarahgerrard.me>
Co-authored-by: Sarah <hello@sarahgerrard.me>
Co-authored-by: Sarah <hello@sarahgerrard.me>
Co-authored-by: Sarah <hello@sarahgerrard.me>
Co-authored-by: Sarah <hello@sarahgerrard.me>
Co-authored-by: Sarah <hello@sarahgerrard.me>
LadyBluenotes
left a comment
LadyBluenotes
left a comment
There was a problem hiding this comment.
Fantastic work, thank you!
2 participants
Description
Adds a
useHeadreference page for @solidjs/meta covering signature, parameters, SSR/hydration behavior, escaping, and examples (including JSON-LD).The new page is available at
/solid-meta/reference/meta/use-head.Wires the page into the solid-meta reference navigation and links it from the setup guide.
Related issues & labels
How to test locally:
pnpm sync
pnpm check:types
pnpm check:lint