为 WordPress 驱动的网站构建 Gatsby 主题

Gatsby 是一个建立在 React 之上的开源框架。 使用 Gatsby，您可以从（几乎）任何地方提取数据并使用它来生成静态或动态网站。 数据可以从 CMS 中提取，这无疑将 WordPress 带到了桌面上。 在继续通过 WordPress 仪表板管理内容的同时，您可以获得静态网站的优势（速度、安全性、静态托管）。

Gatsby 框架的特点之一是它提出了主题作为定制工具。 作为拥有 WordPress 深厚背景的人，我发现 Gatsby 主题的概念特别吸引人。 我曾经设计和开发 WordPress 主题。 然而，随着对 Jamstack 解决方案的兴趣日益浓厚，我逐渐转向使用 WordPress 作为无头 CMS。 在本文中，我想分享一些我从这次过渡中学到的概念。

注意：在我们继续之前，让我们关注我们将要使用的工具。 Gatsby 提供了一个官方的 gatsby-source-wordpress 插件。 为了使它工作，我们需要准备我们的 WordPress 端。 更准确地说，我们需要通过 GraphQL API 公开 Gatsby 风格的 WordPress 数据。 实际上，这意味着安装两个 WordPress 插件 WPGraphQL 和 WPGatsby。 两者都可以通过官方 WordPress 插件存储库获得，不需要任何配置。

什么是盖茨比主题？

Gatsby 主题是一组在 Node.js 包中抽象出来的共享功能。 因此，主题注定要发布（到像 npm 这样的注册表）并作为可安装的依赖项重用。

既然我们在这里谈论 Gatsby 和WordPress ，我将立即澄清它 - 与 WordPress 主题有相似之处，但我们不应该将 WordPress 主题的概念等同于 Gatsby 主题。 对于有 WordPress 背景的人（比如我自己）来说，这种分离可能在一开始就具有挑战性。

WordPress 主题是一个强制性的模板系统，它定义了我们在前端看到的内容。 一个好的WordPress 主题的责任到此结束。 它不应该引入任何功能，因为功能是插件的领域。 因此，WordPress 生态系统中的主题和插件之间存在严格的分离。 主题应该负责表示层，插件负责功能方面。

按照盖茨比的定义，主题负责功能。 那我们不应该称它们为插件吗？ 实际上，Gatsby 和 WordPress 一样，既有插件又有主题。 插件，就像主题一样，是实现 Gatsby API 的可安装 Node.js 包。 事实上，一个 Gatsby 主题就是一个 Gatsby 插件。 如果插件拥有网站上的一个部分、一个页面或页面的一部分——我们称之为主题。

此外，与 WordPress 不同，Gatsby 不需要使用主题来构建网站。 相反，您可能会通过设置如下结构的项目来开始创建站点：

这没关系，除非您有多个站点需要维护。 在这种情况下，您可能希望抽象流程的公共部分并分别管理（版本和更新）它们。

感谢 Gatsby 主题系统，您可以将共享部分捆绑到一个包（或多个包）中，发布包并最终将它们安装到众多应用程序中。 请注意，我使用了复数形式的包——您可以在一个项目中组合多个主题。

儿童主题和阴影

在使用 Gatsby 和 WordPress 时，您将确定所有项目共有的一些核心功能。 我的意思是：获取数据并动态构建页面。 拥有一个处理数据源逻辑和页面创建的主题似乎是值得的。 另一方面，您决定显示页面的方式可能会因项目而异。 无论您在核心级别设置什么，您都可能需要在某些时候覆盖。

一种可能的方法是拥有一个核心（父）主题并在核心主题之上构建子主题。

盖茨比儿童主题是什么意思？

让我们继续比较 WordPress 子主题。 WordPress 子主题允许我们添加功能和覆盖模板。 它们提供了一种增强和修改现有主题的安全方法。

Gatsby 子主题使用父主题作为其插件。 然后我们可以使用阴影的概念，使子主题能够覆盖父主题文件； 这类似于在子主题中覆盖 WordPress 模板。 影子意味着我们可以覆盖 webpack 包中包含的src目录中的文件。 值得强调的是，在项目级别（我们将主题作为包使用）是可能的。 我们将在本文后面看到它的实际应用。

使用 WordPress，我们仅限于一个父主题，一个子主题，并且无法进行进一步的链接。 凭借 Gatsby 主题的灵活性，我们可以走得更远。 可以构建不同配置的子父链。

现在让我们看看 Gatsby 主题的实际应用。 在我们的示例中，我们将构建两个主题， gatsby-theme-wp-parent及其子主题gatsby-theme-wp-child 。 为了简单起见，我选择了这个设置。 在现实世界的场景中，您可能希望将您的功能分解为更多主题，每个主题都有一些特定的职责。

我们将发布我们的主题，将它们安装在项目中，并通过项目级阴影添加进一步的自定义。

开发设置

最后一张图描绘了最终用户的项目（站点）的结构，其中主题被使用。 它们作为项目的依赖项安装。 此设置假定主题可通过某个 npm 存储库获得，这意味着我们已经发布了它们。 我们还没有。 我们需要先构建父子主题。 但是开发设置是什么样的？ 我们的主题是两个独立的包，但我们需要在开发过程中在单个项目中并行处理它们。 此外，我们想在同一个项目中设置一个直接实现主题的演示。

可能的解决方案之一是纱线工作区。 使用 yarn 工作空间，我们在一个单一的单一存储库中工作，在项目根级别使用一个锁定文件。 此外，依赖关系可以链接在一起，这意味着工作空间相互依赖，我们在开发过程中使用本地版本。

如何设置纱线工作区？ 首先，确保全局安装了 yarn。 接下来，在 monorepo 的根目录中，添加指定工作空间的package.json文件：

 { "private": true, "workspaces": [ "packages/*", "demo" ] }

现在，每个主题都是packages中的一个子文件夹，具有自己的package.json文件和一个空的主条目index.js 。 我添加的每个主题都是这样进行的：

 mkdir packages/gatsby-theme-wp-parent touch packages/gatsby-theme-wp-parent/package.json packages/gatsby-theme-wp-parent/index.js

使用package.json如下：

 { "name": "@pehaa/gatsby-theme-wp-parent", "version": "1.0.0", "license": "MIT", "main": "index.js" }

我们将进一步讨论主题发布。 但是，目前，让我们注意我们将发布我们的主题作为范围包； 我在这里使用我的昵称@pehaa作为范围。 请记住，如果您决定将作用域包发布到公共 npm 注册表 https://registry.npmjs.org，则必须明确声明公共访问权限并将以下内容添加到其package.json文件中：

 "publishConfig": { "access": "public" }

除了主题之外，我们还需要一个demo工作区，我们将从中试用我们的代码。 该演示必须是一个"private"包，因为它不应该被发布。

 // demo/package.json { "private": true, "name": "demo", "version": "1.0.0", "scripts": { "build": "gatsby build", "develop": "gatsby develop", "clean": "gatsby clean" } }

通过设置工作区，我们可以通过指定脚本和工作区，从我们的 monorepo 中的任何位置运行开发或构建脚本，如下所示：

 yarn workspace demo develop

顺便说一句，您不仅限于单个demo 。 例如，我们的GatsbyWPThemes monorepo 包含多个我们添加到examples目录的演示。 在这种情况下，根级package.json文件定义工作空间如下：

 "workspaces": [ "packages/*", "examples/*" ]

构建盖茨比主题

首先，我们需要安装react 、 react-dom和gatsby 。 我们需要将这三个安装为每个主题中的对等依赖项 ( -P ) 和我们的演示中的依赖项。 我们还将父主题安装为子主题的依赖项，将子主题安装为演示的依赖项。

 yarn workspace @pehaa/gatsby-theme-wp-parent add -P react react-dom gatsby yarn workspace @pehaa/gatsby-theme-wp-child add -P react react-dom gatsby yarn workspace @pehaa/gatsby-theme-wp-child add "@pehaa/gatsby-theme-wp-parent@*" yarn workspace demo add react react-dom gatsby "@pehaa/gatsby-theme-wp-child@*"

注意：您不能在没有版本号的情况下添加@pehaa/gatsby-theme-wp-parent或@pehaa/gatsby-theme-wp-child 。 您必须将其指定为@*或@1.0.0 。 没有它，npm 将尝试从存储库中获取包，而不是使用本地包。 稍后，当我们使用 Lerna 发布我们的包时，所有*将自动更新到当前主题版本并保持同步。

家长主题

现在让我们关注父主题及其依赖项：

 yarn workspace @pehaa/gatsby-theme-wp-parent add gatsby-source-wordpress gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp gatsby-awesome-pagination

我们父主题的职责是加载处理和显示图像所需的源插件和三个插件。 我们将它们全部加载到gatsby-config.js文件中。

 // gatsby-config.js module.exports = (options) => { return { plugins: [ 'gatsby-plugin-sharp', // must have for gatsby 'gatsby-transformer-sharp', // must have for gatsby images 'gatsby-plugin-image', { resolve: 'gatsby-source-wordpress', options: { url: `${options.wordPressUrl}/graphql`, }, }, ], } }

除了采购内容外，我们还需要为我们的 WordPress 内容动态构建路由。 我们需要为 WordPress 静态页面、单个帖子、博客存档、类别存档和标签存档创建路由。 Gatsby 提供createPages API 作为 Gatsby Node API 的一部分。 让我们看一下负责创建单个帖子的代码。

 exports.createPages = async ({ graphql, actions }) => { const { createPage } = actions const postsQuery = await graphql(` query GET_POSTS { allWpPost(sort: {order: DESC, fields: date}) { edges { node { uri id } } } } `) const posts = postsQuery.data.allWpPost.edges posts.forEach(({ node }) => { createPage({ path: node.uri, component: path.resolve('../src/templates/post-query.js'), context: { // Data passed to context is available in page queries as GraphQL variables // we need to add the post id here // so our blog post template knows which blog post it should display id: node.id }, }) }) }

您可以在此 GitHub 存储库中找到完整的代码。 您可能会注意到它因页面类型而异。 文章、页面或存档是不同的，尤其是为后者实现的分页。 尽管如此，它仍然遵循相同的模式：

• 运行异步graphql “获取项目”查询；
• 循环生成的项目并为每个项目运行createPage辅助函数，传递：
  • 路径，
  • component ——模板文件； 盖茨比必须知道每一页应该显示什么，
  • context — 模板（在component字段中提供）可能需要的任何数据。

由于我们不想担心父主题中的 UI 部分——我们将其委托给我们将在子主题中隐藏的组件。

 // src/templates/post-query.js import { graphql } from "gatsby" import Post from "../components/Post" export default Post export const pageQuery = graphql` query ($id: String!) { wpPost(id: { eq: $id }) { # query all usefull data } } `

Post组件可以访问模板文件中定义的graphql页面查询中的数据。 我们的组件通过 props 作为props.data接收查询结果。 我们的组件文件与模板分离，但可以访问其数据。 使用此设置，我们可以隐藏Post组件，而无需重写查询。

 // src/components/Post.js import React from 'react' const Post = (props) => { return <pre>{JSON.stringify(props.data, null, 2)}</pre> } export default Post

儿童主题

现在，让我们转到子主题并添加它的依赖项。

注意：我选择使用 Chakra UI 作为组件库，它基于情感并带有自己的 Gatsby 插件。 我们还需要从@wordpress/block-library安装特定于 WordPress 内容的样式。

 yarn workspace @pehaa/gatsby-theme-wp-child add @chakra-ui/gatsby-plugin @chakra-ui/react @emotion/react @emotion/styled @wordpress/block-library framer-motion gatsby-plugin-webfonts html-react-parser

子主题的职责是 UI 部分，我们需要覆盖父主题生成的裸骨输出。 为了使阴影起作用，我们需要遵循父主题的文件结构。 例如，要覆盖gatsby-theme-wp-parent/src/components/Post.js中的Post组件，我们需要在gatsby-theme-wp-child/src/@pehaa/gatsby-theme-wp-parent/components中创建一个Post.js文件gatsby-theme-wp-child/src/@pehaa/gatsby-theme-wp-parent/components 。 @pehaa中间文件夹对应于gatsby-theme-wp-parent包的范围。

将选项传递给主题

我们在gatsby-config.js文件中加载和配置 gatsby 插件。 我们将在设置中包含三个配置文件，每个级别一个，父主题、子主题和演示。

 ├── demo │ └── gatsby-config.js ├── packages │ ├── gatsby-theme-wp-child │ │ └── gatsby-config.js │ └── gatsby-theme-wp-parent │ └── gatsby-config.js └── ...

在演示级别，配置加载子主题，如下所示：

 // demo/gatsby-config.js module.exports = { plugins: [ { resolve: '@pehaa/gatsby-theme-wp-child', options: { wordPressUrl: process.env.GATSBY_WP_URL, /* other options */ }, }, ], }

正如您在上面看到的，我们将选项传递给子主题。 这些将在子主题级别的配置文件中可用。 这是可能的，因为 Gatsby 插件已将配置导出为函数。 因此，当我们加载提供一些选项的插件时，插件会将它们作为其配置函数的参数接收。 特别是，我们传递给主题的选项可以像这样“转发”到它的父级主题：

 // gatsby-theme-wp-child/gatsby-config.js const defaultFonts = ... module.exports = (options) => { // destructure option to extract fonts const {fonts, ...rest} = options return { plugins: [ { resolve: `@pehaa/gatsby-theme-wp-parent`, options: { // "forward" the options gatsby-theme-wp-child options to its parent theme ...rest } }, '@chakra-ui/gatsby-plugin', { resolve: `gatsby-plugin-webfonts`, options: { fonts: fonts || defaultFonts }, }, ], } }

让我们再看看上面的代码。 请注意，我们在子主题级别定义字体，但我们保留通过主题选项修改它们的可能性。

 // demo/gatsby-config.js module.exports = { plugins: [ { resolve: `@pehaa/gatsby-theme-wp-child`, options: { wordPressUrl: process.env.GATSBY_WP_URL, fonts: { google: [{family: "Rubik"}], }, }, }, ], }

在配置我们的主题时，我们应该记住主题只是一个包，最终用户不会直接访问它的代码。 因此，提前考虑并公开适当的设置是一个好主意。 如果我们的主题加载需要配置的插件，我们可能应该从项目（演示）级别一直向下传递插件选项。

让我们看一个例子。 我们的父主题使用gatsby-source-wordpress插件从 WordPress 中获取数据。 这个插件带有一堆选项，其中一些可能对构建过程至关重要，例如schema.requestConcurrency或schema.timeout 。 但是，同样，父主题只是一个包，最终用户无法编辑其gatsby-config文件。 这似乎很明显，但我们在 Gatsby WP Themes 的初始版本中不知何故错过了它。 但是，通过快速修复，用户可以从项目的配置中传递gatsby-plugin-source-wordpress选项...

 // user's project gatsby-config.js module.exports = { plugins: [ { resolve: `@pehaa/gatsby-theme-wp-child`, options: { wordPressUrl: process.env.GATSBY_WP_URL, gatsbySourceWordPressOptions: {}, // ... }, }, ], }

…通过子主题和父主题到目标插件：

 // packages/gatsby-theme-wp-parent/gatsby-config.js module.exports = (options) => { return { plugins: [ // ... { resolve: `gatsby-plugin-source-wordpress`, options: { url: `${options.wordPressUrl}/graphql`, ...options.gatsbySourceWordPressOptions }, }, ], } }

CSS 主题

支持主题的 CSS-in-JS 解决方案似乎非常适合 Gatsby 主题。 我们的 Gatsby 子主题将使用 Chakra UI 框架，我们将稍微定制它的 CSS 主题。 是的，Chakra UI 也使用了“主题”的概念。 在此上下文中，主题是存储设计系统样式值、比例和/或设计标记的 JavaScript 对象。 为避免混淆，我将其称为“CSS 主题”。 我们已经安装了所需的@chakra-ui包和 Gatsby 插件@chakra-ui/gatsby-plugin 。 让我们探索插件的代码以了解它是如何工作的。 它实际上将我们的 Gatsby 应用程序包装到ChakraProvider并公开src/theme.js文件以进行阴影处理，这样我们就可以像这样进行：

 /* packages/gatsby-theme-wp-child/src/@chakra-ui/gatsby-plugin/theme.js */ import { extendTheme } from "@chakra-ui/react" const theme = { fonts: { body: "Karma, sans-serif", heading: "Poppins, sans-serif", }, styles: { global: { body: { color: "gray.700", fontSize: "xl", }, }, }, components: { Button: { baseStyle: { borderRadius: "3xl", }, defaultProps: { colorScheme: "red", }, }, }, } export default extendTheme(theme)

我们再次使用了阴影的概念。 这里的关键方面是我们创建theme.js文件的位置。

稍后，我们将看到如何在用户的项目级别上隐藏 CSS 主题。

使用 Lerna 发布主题

主题准备就绪后，您需要发布它们。 如果您想公开分享您的代码，您很可能会将其发布到公共 npm 注册表。 如果您以前从未发布过包，您可以通过在本地计算机上使用 Verdaccio 来熟悉该过程。

在 Gatsby WP Themes，我们使用 Cloudsmith 的优质服务。 Cloudsmith 支持 npm 包的全功能注册表，为私有注册表提供高级选项，为公共注册表提供免费解决方案。 我将继续使用免费的 Cloudsmith 解决方案。 创建帐户后，创建一个新的存储库； 我的是pehaa/gatsby-wp-theming 。

为了通过命令行更改 Cloudsmith 注册表，您需要提供此注册表的登录凭据。 只需输入：

 npm login --registry=https://npm.cloudsmith.io/organistion/repository_name/

您将被要求提供您的用户名、密码（即您的 API KEY）和电子邮件。

对于多包 git 存储库，您可能希望使用 Lerna 来促进发布。 Lerna 与纱线工作区非常匹配。 您可以使用npm install --global lerna全局安装 Lerna CLI。 要在我们的项目中启动它，我们将运行以下命令：

 lerna init --independent

上面的命令将在 monorepo 的根目录中创建一个lerna.json文件。 您需要手动添加"useWorkspaces" : true和"npmClient": "yarn" ； 如果它不是默认的公共 npm 之一，您可能还需要指定command.publish.registry 。

 { "npmClient": "yarn", "useWorkspaces": true, "version": "independent", "command": { "publish": { "registry": "https://cloudsmith.io/organisation/repository_name" } } }

然后， lerna publish命令发布自上次发布以来已更改的包。 默认情况下，Lerna 会提示正在更新的每个包的版本更改。 您可以通过运行跳过提示：

 lerna publish [major|minor|patch|premajor|preminor|prepatch|prerelease] --yes

您还可以将 Lerna 配置为使用 Conventional Commits Specification 来确定版本提升并生成 CHANGELOG.md 文件。 有了所有可用的选项，您应该能够使您使用 Lerna 的方式适应您的工作流程。

在项目中使用主题

现在，让我们停止开发服务器并从用户的角度来看。 我们将创建一个新项目gatsby-wp-site ，它将gatsby-theme-wp-child实现为从 npm 存储库安装的包。 在我们的项目文件夹中，我们将安装我们的四个依赖项： gatsby 、 react 、 react-dom和主题本身。 由于我们使用 Cloudsmith 发布@pehaa -scoped 包，我们必须添加一个.npmrc文件，其中我们指定@pehaa -scoped 存储库，如下所示：

 mkdir gatsby-wp-site cd gatsby-wp-site echo "@pehaa:registry=https://npm.cloudsmith.io/pehaa/gatsby-wp-theming/" >> .npmrc yarn init -yp yarn add react react-dom gatsby @pehaa/gatsby-theme-wp-child

我们的网站几乎准备就绪。 我们只需要创建一个gatsby-config.file来加载主题并提供 WordPress URL。 完成后，我们就可以运行gatsby build了。

 // gatsby-config.js module.exports = { plugins: [ { resolve: "@pehaa/gatsby-theme-wp-child", options: { wordPressUrl: "https://yourwordpress.website" } } ] }

我们的网站已准备就绪。

定制呢？ 我们仍然可以利用阴影。 此外，项目级别始终优先考虑阴影。 让我们通过重写 Footer 组件来看看它的实际效果。 现在，我们的页脚在@pehaa/gatsby-theme-wp-child/src/components/Footer.js中定义。 我们需要创建src文件夹并重新创建以下文件结构：

 gatsby-wp-site ├── src │ └── @pehaa │ └── gatsby-theme-wp-child │ └── components │ └── Footer.js

有了上面的文件结构，我们准备提供一个新版本的站点页脚。 例如：

 import React from "react" import { useStaticQuery, graphql } from "gatsby" import { Box } from "@chakra-ui/react" const Footer = () => { const data = useStaticQuery(graphql` query { wp { generalSettings { title } } } `) return ( <Box as="footer" p="6" fontSize="sm" bg="gray.700" color="white" mt="auto" textAlign="center" > <b>{data.wp.generalSettings.title}</b> - Built with WordPress and GatsbyJS </Box> ) } export default Footer

最后，让我们看看如何使用 CSS 主题。 使用以下代码，正确位于src/@chakra-ui/gatsby-plugin/theme.js中，您可以在项目中扩展默认主题。

 // src/@chakra-ui/gatsby-plugin/theme.js import { extendTheme } from "@chakra-ui/react" const theme = { /* ... */ } export default extendTheme(theme)

在大多数情况下，这并不是您所需要的。 新的 CSS 主题忽略了来自gatsby-theme-wp-child ，而您希望扩展 Gatsby 子主题中设置的 CSS 主题。 后者是可能的，因为extendTheme函数允许您传递多个对象。 要使其工作，您必须从gatsby-theme-wp-child导入 CSS 主题，并将其作为第二个参数传递给extendTheme函数：

 // src/@chakra-ui/gatsby-plugin/theme.js import theme from "@pehaa/gatsby-theme-wp-child/src/@chakra-ui/gatsby-plugin/theme" import { extendTheme } from "@chakra-ui/react" const extendedTheme = { fonts: { body: "Rubik, sans-serif", heading: "Rubik, sans-serif", }, /* ... */ } export default extendTheme(extendedTheme, theme)

你可以在这里看到该站点，它是从这个 GitHub 存储库的主分支部署的。

包起来

您刚刚看到了 Gatsby 主题化的实际应用。 使用主题方法，您可以快速设置多个 Gatsby 站点，其中大部分代码都保存在主题包中。 我们还看到了如何将项目的各个部分分成包以及如何利用阴影。

在我们的示例中，我们遵循了两个主题设置，主题之间存在父子关系。 这可能并不总是一个理想的选择。

有时，您可能希望在 UI 自定义方面走得更远。 在这种情况下，您可能会考虑直接加载和隐藏父主题，而不是使用子主题。 在实际场景中，您可能会选择一些子级主题来负责 UI 的不同、可重用部分（例如评论、表单或搜索）。

Smashing 杂志的进一步阅读

• 使用 Gatsby 函数构建 API
• Gatsby 无服务器功能和国际空间站
• 使用 Gatsby 函数和 Stripe 将开源软件货币化
• 与 Marcy Sutton 一起粉碎播客第 20 集：什么是盖茨比？