seo

@vuepress/plugin-seo

通过向 <head> 注入标签，让你的站点支持开放内容协议 OGP与 JSON-LD 1.1。

使用

npm i -D @vuepress/plugin-seo@next
.vuepress/config.ts
import { seoPlugin } from '@vuepress/plugin-seo'

export default {
  plugins: [
    seoPlugin({
      hostname: 'https://example.com',
    }),
  ],
}

插件开箱即用，会读取站点配置与页面 Frontmatter，尽可能生成所需的标签。默认情况下，除首页外所有由 Markdown 文件生成的页面都被视为文章。

默认的 OGP 生成逻辑

以下 <meta> 标签会被注入 <head>：

属性名称值
og:urlhostname + base + page.path
og:site_name该语言的标题，回退到站点标题
og:titlepage.title
og:descriptionpage.frontmatter.description，未设置时由 autoDescription 根据页面内容生成
og:type"article" 或 "website"，参考页面类型
og:imagepage.frontmatter.banner || page.frontmatter.cover || 页面中的第一张图片 || fallBackImage
og:updated_time来自 @vuepress/plugin-git
og:localepage.lang
og:locale:alternate页面的其他语言，来自站点配置
og:restrictions:agerestrictions
twitter:card仅当找到封面时为 "summary_large_image"
twitter:image:src页面的封面图片
twitter:image:altpage.title
twitter:creatortwitterID
article:authorpage.frontmatter.author || author，参考作者
article:tagpage.frontmatter.tags || page.frontmatter.tag
article:published_timepage.frontmatter.date，回退到 Git 创建时间
article:modified_time来自 @vuepress/plugin-git

只有取值存在的标签才会被注入，因此 og:updated_time、article:tag 以及来自 restrictions 和 twitterID 的标签在不可用时会被省略。

默认的 JSON-LD 生成逻辑

属性名值
@context"https://schema.org"
@type文章为 "Article" 并含有 headline，其余为 "WebPage" 并含有 name
image页面中的所有图片，回退到 fallBackImage
datePublishedpage.frontmatter.date，回退到 Git 创建时间
dateModified来自 @vuepress/plugin-git
authorpage.frontmatter.author || author，标记为 Person

页面类型

og:type 标签与 JSON-LD 的 @type 均取决于页面是否为文章，你可以使用 isArticle 选项提供自己的判断逻辑。

如果某个页面属于其他类型，例如图书、音乐，你可以通过修改 ogp 与 jsonLd 对象来处理。

自定义生成过程

ogp 与 jsonLd 选项会收到默认对象，并返回修改后的对象。

比如你使用的第三方主题要求为每篇文章在 Frontmatter 中设置 banner，你可以这样写：

seoPlugin({
  ogp: (ogp, page) => ({
    ...ogp,
    'og:image': page.frontmatter.banner || ogp['og:image'],
  }),
})

如果相同内容可以在不同 URL 下访问，你可能需要 canonical 选项来声明首选地址。它接受一个会被添加到页面链接之前的字符串，或一个返回链接的函数。

例如你的站点部署在 example.com 的 docs 目录下，并可通过 http://example.com/docs/xxx、https://example.com/docs/xxx、http://www.example.com/docs/xxx 与首选的 https://www.example.com/docs/xxx 访问，将 canonical 设置为 https://www.example.com/docs/，搜索引擎便知道应当收录哪个地址。

head 标签

你可以通过页面的 head Frontmatter 直接添加标签：

---
head:
  - - meta
    - name: keywords
      content: SEO plugin
---

其他协议可以通过 customHead 选项支持，它会修改页面的 head 标签配置。

选项

hostname必填string

站点部署的域名。

authorSeoAuthor

默认作者。

type AuthorName = string

interface AuthorInfo {
  name: string
  url?: string
  email?: string
}

type SeoAuthor = AuthorInfo | AuthorInfo[] | AuthorName | AuthorName[]
autoDescriptionboolean
默认值true

当 Frontmatter 中未设置页面描述时，是否根据页面内容生成描述。

canonicalstring | ((page: Page) => string | null)

页面的首选链接。

参考：规范链接。

fallBackImagestring

当找不到图片时的回退图片链接，应为完整或绝对链接。

restrictionsstring

内容的年龄分级，格式为 [int]+，如 "13+"。

twitterIDstring

作者的 Twitter 用户名。

isArticle(page: Page) => boolean

用于判断页面是否为文章的函数。

参考：页面类型。

ogp(ogp: SeoContent, page: Page, app: App) => SeoContent

自定义 OGP 生成器。

参考：自定义生成过程。

jsonLd(jsonLD: ArticleSchema | BlogPostingSchema | WebPageSchema, page: Page, app: App) => ArticleSchema | BlogPostingSchema | WebPageSchema

自定义 JSON-LD 生成器。

参考：自定义生成过程。

customHead(head: HeadConfig[], page: Page, app: App) => void

自定义 head 标签生成器。

参考：head 标签。

Frontmatter

seoboolean
默认值true

是否为该页面注入 SEO 标签。