-
-
Notifications
You must be signed in to change notification settings - Fork 604
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(use-content-head): add helper for <head> binding (#1295)
- Loading branch information
Showing
11 changed files
with
220 additions
and
114 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| --- | ||
| title: 'useContentHead()' | ||
| description: 'Configuring your <head> tag from your content has never been easier!' | ||
| --- | ||
|
|
||
| `useContentHead()`{lang="ts"} is a composable providing a binding between your content data and [`useHead`](https://v3.nuxtjs.org/guide/features/head-management). | ||
|
|
||
| It is already implemented for you in both [`<ContentDoc />`](/api/components/content-doc) component and the default [`documentDriven`](https://content.nuxtjs.org/guide/writing/document-driven) page. | ||
|
|
||
| ## Parameters | ||
|
|
||
| These parameters can be used from the [Front-Matter](/guide/writing/markdown#front-matter) section of your pages. | ||
|
|
||
| | Key | Type | Default | Description | | ||
| | ------------------ | ------------------ | -------------------- | ----------------------------------------------------------------------------------- | | ||
| | `head` | `Object` | | A [useHead](https://v3.nuxtjs.org/guide/features/head-management) compatible object | | ||
| | `title` | `String` | | Will be used as the default value for `head.title` | | ||
| | `head.title` | `String` | Parsed `title` | Sets the `<title>` tag | | ||
| | `description` | `String` | | Will be used as the default value for `head.description` | | ||
| | `head.description` | `String` | Parsed `description` | Sets the `<meta name="description">` tag | | ||
| | `image` | `String \| Object` | | Will be used as the default value for `head.image` | | ||
| | `image.src` | `String` | | The source of the image | | ||
| | `image.alt` | `String` | | The alt description of the image | | ||
| | `image.xxx` | `String` | | Any [`og:image:xxx` compatible](https://ogp.me/#structured) attribute | | ||
| | `head.image` | `String \| Object` | | Overrides the `<meta property="og:image">` | | ||
|
|
||
| At the exception of `title`, `description` and `image`, the `head` object behaves exactly the same in [Front-Matter](/guide/writing/markdown#front-matter) as it would in [`useHead({ ... })`](https://v3.nuxtjs.org/guide/features/head-management) composable. | ||
|
|
||
| You can specify any value that is writeable in `yaml` format. | ||
|
|
||
| ```md [example-usage.md] | ||
| --- | ||
| title: 'My Page Title' | ||
| description: 'What a lovely page.' | ||
| image: | ||
| src: '/assets/image.jpg' | ||
| alt: 'An image showcasing My Page.' | ||
| width: 400 | ||
| height: 300 | ||
| head: | ||
| meta: | ||
| - name: 'keywords' | ||
| content: 'nuxt, vue, content' | ||
| - name: 'robots' | ||
| content: 'index, follow' | ||
| - name: 'author' | ||
| content: 'NuxtLabs' | ||
| - name: 'copyright' | ||
| content: '© 2022 NuxtLabs' | ||
| --- | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| `useContentHead()`{lang="ts"} is available everywhere in your app where `useHead` would be. | ||
|
|
||
| It takes two arguments: | ||
|
|
||
| - `document`: A document data (of any type) | ||
|
|
||
| - `to`: A route path | ||
| - Default: `useRoute()`{lang=ts} | ||
|
|
||
| ::code-group | ||
|
|
||
| ```vue [with documentDriven] | ||
| <script setup lang="ts"> | ||
| const { page } = useContent() | ||
| useContentHead(page) | ||
| </script> | ||
| ``` | ||
|
|
||
| ```vue [with queryContent] | ||
| <script setup lang="ts"> | ||
| const { data: page } = await useAsyncData('my-page', queryContent('/').findOne) | ||
| useContentHead(page) | ||
| </script> | ||
| ``` | ||
|
|
||
| :: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,9 @@ | ||
| --- | ||
| head.titleTemplate: '%s | TEST' | ||
| title: Hello World | ||
| description: Hello, here is a description | ||
| --- | ||
|
|
||
| # Home | ||
|
|
||
| Hello World! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| import { RouteLocationNormalized, RouteLocationNormalizedLoaded } from 'vue-router' | ||
| import type { HeadObjectPlain } from '@vueuse/head' | ||
| import type { Ref } from 'vue' | ||
| import { ParsedContent } from '../types' | ||
| import { useRoute, nextTick, useHead, unref, nextTick, watch } from '#imports' | ||
|
|
||
| export const useContentHead = ( | ||
| _content: ParsedContent | Ref<ParsedContent>, | ||
| to: RouteLocationNormalized | RouteLocationNormalizedLoaded = useRoute() | ||
| ) => { | ||
| const content = unref(_content) | ||
|
|
||
| const refreshHead = (data: ParsedContent = content) => { | ||
| // Don't call this function if no route is yet available | ||
| if (!to.path || !data) { return } | ||
|
|
||
| // Default head to `data?.head` | ||
| const head: HeadObjectPlain = Object.assign({}, data?.head || {}) | ||
|
|
||
| // Great basic informations from the data | ||
| head.title = head.title || data?.title | ||
| head.meta = head.meta || [] | ||
|
|
||
| // Grab description from `head.description` or fallback to `data.description` | ||
| // @ts-ignore - We expect `head.description` from Nuxt configurations... | ||
| const description = head?.description || data?.description | ||
|
|
||
| // Shortcut for head.description | ||
| if (description && head.meta.filter(m => m.name === 'description').length === 0) { | ||
| head.meta.push({ | ||
| name: 'description', | ||
| content: description | ||
| }) | ||
| } | ||
|
|
||
| // Grab description from `head` or fallback to `data.description` | ||
| // @ts-ignore - We expect `head.image` from Nuxt configurations... | ||
| const image = head?.image || data?.image | ||
|
|
||
| // Shortcut for head.image to og:image in meta | ||
| if (image && head.meta.filter(m => m.property === 'og:image').length === 0) { | ||
| // Handles `image: '/image/src.jpg'` | ||
| if (typeof image === 'string') { | ||
| head.meta.push({ | ||
| property: 'og:image', | ||
| // @ts-ignore - We expect `head.image` from Nuxt configurations... | ||
| content: head.image | ||
| }) | ||
| } | ||
|
|
||
| // Handles: `image.src: '/image/src.jpg'` & `image.alt: 200`... | ||
| if (typeof image === 'object') { | ||
| // https://ogp.me/#structured | ||
| const imageKeys = [ | ||
| 'src', | ||
| 'secure_url', | ||
| 'type', | ||
| 'width', | ||
| 'height', | ||
| 'alt' | ||
| ] | ||
|
|
||
| // Look on available keys | ||
| for (const key of imageKeys) { | ||
| // `src` is a shorthand for the URL. | ||
| if (key === 'src' && image.src) { | ||
| head.meta.push({ | ||
| property: 'og:image', | ||
| content: image[key] | ||
| }) | ||
| } else if (image[key]) { | ||
| head.meta.push({ | ||
| property: `og:${key}`, | ||
| content: image[key] | ||
| }) | ||
| } | ||
| } | ||
| } | ||
| } | ||
|
|
||
| // @ts-ignore | ||
| if (process.client) { nextTick(() => useHead(head)) } else { useHead(head) } | ||
| } | ||
|
|
||
| watch(() => unref(_content), refreshHead, { immediate: true }) | ||
| } |
Oops, something went wrong.