作者选择了 Internet Archive作为 Write for Donations计划的一部分接受捐赠。
介绍
Gatsby 1.0于2017年发布,自那时以来一直在发布新功能,同时保持其作为静态网站生成器的高定制性。添加的功能以插件,新API,实用程序和配置选项的形式出现。这些功能可以单独使用并定制或结合在一起应用特定的用例。然而,由于许多网站受益于相同的功能和设置组合,Gatsby引入了 Gatsby themes。
Gatsby 主题专门指作为配置选项、功能和/或用户界面(UI)元素的集合的插件。将共享功能分离成维护主题,使您更容易保持网站的更新,并允许您花费更少的时间来配置您的网站和开发您的内容。
在本教程中,您将安装、配置和使用一个Gatsby主题来发布博客帖子: gatsby-theme-blog. 此插件将多个功能,如 MDX支持和代码突出,组成一个方便的包。
每個步驟都會帶你經歷使用Gatsby主題的重要部分,到最後你會看到這個過程如何適用於你可能想要在未來使用的任何Gatsby主題。
前提条件
在开始之前,这里有一些你需要的东西:
安裝程序取決於操作系統,但DigitalOcean有指南 Ubuntu 20.04和 macOS,你可以總是找到最新的版本在 官方Node.js下載頁面 。 *一些熟悉的JavaScript,為工作在Gatsby。 JavaScript語言是一個廣泛的主題,但一個很好的起點是我們的 如何編碼在JavaScript系列。
- 一個新的Gatsby項目,從「gatsby-starter-default」開始。 要建立一個新的Gatsby項目從零開始,你可以參考「如何設定您的第一個Gatsby網站」教程。
本教程已在 Node.js v14.16.1, npm v6.14.12, Gatsby v3.11.1 和 'gatsby-theme-blog' v3.0.0 上测试。
步骤 1 - 查找和安装一个主题
虽然本教程将引导您使用特定的主题,‘gatsby-theme-blog’,但每个步骤在概念上也适用于一般的Gatsby主题。
Gatsby 向插件和主题作者提供有关 他们应该如何发布他们的 Gatsby 软件包的指导,这使得更容易找到一个适合您的需求的主题。 主题开发人员被指示将他们的主题软件包标记为gatsby和gatsby-theme作为关键字,然后通过包 registries(文件实际托管的地方)进行扫描,并使其可搜索。
作为开发者,你正在寻找一个主题来添加支持MDX,代码突出,等等. 虽然Gatsby有自己的插件浏览器(https://www.gatsbyjs.com/plugins/?=gatsby-theme),它实际上从npm注册表中提取其列表,所以你的第一步是直接在npm注册表搜索引擎(https://www.npmjs.com)开始搜索。 通过使用博客关键字:gatsby主题的搜索输入,你将限制你的结果仅限于那些插件有gatsby主题的关键字,如下屏幕截图所示:
在本教程中,您将使用gatsby-theme-blog,所以选择该包. 使用选定的gatsby-theme-blog(https://www.npmjs.com/package/gatsby-theme-blog)作为您要安装的主题,此步骤的下一部分是实际安装它,以及它的依赖。 导航到您现有的Gatsby项目并在目录中运行以下命令:
1npm install gatsby-theme-blog
依赖程序完成安装后,您将看到一个类似于以下的消息:
1[secondary_label Output]
2...
3+ [email protected]
4added 262 packages from 181 contributors and audited 2391 packages in 49.706s
现在你已经在你的项目中安装了主题及其依赖性,现在是时候在你的Gatsby项目中加载和配置主题了。
步骤 2 – 加载和配置主题
现在你的主题已经安装了,你可以开始在你的网站上实际使用它,并根据你的需求修改它. 在Gatsby中,主主题初始化和配置是通过编辑根配置文件, gatsby-config.js。
在您喜爱的编辑器中打开gatsby-config.js配置文件,然后添加以下内容:
1[label gatsby-config.js]
2module.exports = {
3 plugins: [
4 ...
5 `gatsby-plugin-image`,
6 {
7 resolve: 'gatsby-theme-blog',
8 options: {
9 basePath: '/posts',
10 contentPath: `md/posts`,
11 }
12 },
13 `gatsby-transformer-sharp`,
14 ...
15 ]
16}
主题使用basePath选项来设置博客的URL,而contentPath则告诉主题在哪里找到将 Markdown 文件发布为博客帖子。
添加此代码后,保存您的配置文件。
「gatsby-theme-blog」的主題提供了額外的設定, 在「gatsby-theme-blog」「README」檔案中記錄。 由於每個Gatsby主題都是不同的,這個步驟中最重要的部分是指您所選擇的主題的文檔,並遵循其中提供的準確指南。
您现在已经设置了主题,以便通过Gatsby配置文件加载和配置您喜欢的内容,下一步是探索它为您的网站添加的一些新功能,并沿途进行测试。
步骤三:测试功能
由于您的主题现在已安装、配置和加载,您现在可以将其部署到您的网站中,此步骤涵盖如何尝试与主题结合的一些新功能,并预览您的结果。
您将通过一个新的博客帖子文件测试gatsby-theme-blog的MDX、代码突出化和标记处理支持,首先,您需要创建一个目录以存储文件,这需要与您在 [步骤 #2](#步骤-2 - 加载和配置主题)中使用的md/posts的contentPath设置相匹配。您可以在您的文件浏览器中手动创建此目录,或者在您的终端中通过在您的Gatsby项目的根部运行此命令:
1mkdir -p ./md/posts
接下来,创建一个空的MDX文件,‘my-first-post.mdx’,它将包含你的新帖子内容。
1touch ./md/posts/my-first-post.mdx
现在打开空的 MDX 文件并添加以下代码:
1[label md/posts/my-first-post.mdx]
2---
3title: Learning Gatsby Themes and Trying MDX
4slug: /posts/gatsby-theme-learning
5date: 2021-08-16
6excerpt: A post about learning Gatsby themes and trying out some MDX.
7---
8
9## Welcome!
10
11This is a post where I plan to share my journey learning Gatsby Themes, and to try out some MDX.
12
13## Resources
14
15<ul>
16{[
17 {
18 link: 'https://www.gatsbyjs.com/',
19 text: 'Gatsby Website',
20 note: 'Official Website for Gatsby'
21 },
22 {
23 link: 'https://www.gatsbyjs.com/docs/themes/',
24 text: 'Gatsby Theme Documentation',
25 note: 'Documentation for Gatsby Theme usage and development'
26 },
27 {
28 link: 'https://www.digitalocean.com/community/tutorial_series/how-to-create-static-web-sites-with-gatsby-js',
29 text: 'DigitalOcean - "How To Create Static Web Sites with Gatsby.js"',
30 note: 'A DigitalOcean tutorial series on using Gatsby JS'
31 }
32].map(item => (
33 <li key={item.link}>
34 <a href={item.link} target="_blank">{item.text}</a>
35 <ul>
36 <li>{item.note}</li>
37 </ul>
38 </li>
39))}
40</ul>
41
42## Code Sample
43
44To try out code highlighting in this theme, here is a snippet of JavaScript code. This code won't run in your browser; it is for visual use only.
在文件的顶部,由---附带的部分是一组称为 frontmatter 的密钥值对。不是每个主题都使用相同的密钥,而你在帖子中使用的密钥已从gatsby-theme-blog使用的密钥中仔细选择(https://www.npmjs.com/package/gatsby-theme-blog#blog-post-fields)。
所有后面的文本成为帖子的体,从您的 **欢迎!**部分开始。标题文本前的两个哈希符号(##)告诉 Markdown这是一个级别2的标题,这也用于 资源部分。
在 ** 资源** 部分中,您首先使用了 MDX 与常规 Markdown 不同之处:使用 React 的 JSX 语法嵌入了 React 组件,这些组件与您的 Markdown 合并并并成一个单一页面。
最后,要测试与gatsby-theme-blog结合的代码语法突出功能,在文件末尾添加一个 Markdown Fenced Code Block:
1[label md/posts/my-first-post.mdx]
2 ```js
3 function saySomething(name) {
4 console.log(`Hello ${name}!`);
5 console.log(`Isn't learning about Gatsby fun?!`);
6 }
7 saySomething('Arthur');
8 ```
这使用三重背杆来表示代码开始和停止的边界。
保存并关闭 MDX 文件,当你完成编辑新的帖子。
要看到这个帖子作为一个观众,测试你的主题插件的所有功能,运行以下命令:
1npm run develop
一旦准备好了,Gatsby CLI将提示您在您的网页浏览器中打开您的项目,您可以通过导航到localhost:8000。 要查看新博客列表页面,请访问localhost:8000/posts,并查看这个特定的新帖子,请导航到localhost:8000/posts/gatsby-theme-learning/`。
您刚刚测试了您新安装的主题提供的一些功能,并在网页浏览器中查看了您的努力的结果. 对于许多用户来说,这可能涵盖了他们的所有需求,但对于更高的自定义水平,下一步探索了一个名为阴影的盖茨比概念,允许您将主题的碎片叠加起来。
步骤 4 — 使用阴影(可选)
在本教程的这一点上,您已经安装并配置了Gatsby中的第三方主题。 配置发生在gatsby-config.js中,并且仅限于主题出版商选择的选项,以便定制。
术语 shadowing是指用你自己的修改来压缩或扩展内置主题文件的做法,对于熟悉 WordPress的人来说,这类似于一个 _child主题的概念。
通过Gatsby主题,主题的源代码中的任何文件都可以被阴影化,从影响Gatsby节点和文件生成的方法到用户界面元素和布局. 对于您的博客,您将阴影化名为 bio-content.js的React组件文件,以定制您的博客生物如何显示在每个帖子下方. 通过阴影化此一个文件,您将影响通过gatsby-theme-blog插件的每个博客帖子的外观。
阴影的第一步是创建一个文件夹在你的src目录中,与你想要阴影的主题插件相同的确切名称。
1mkdir src/gatsby-theme-blog
对于您想要阴影的主题中的任何特定文件,下一步是创建一个具有相同名称和与主题相同的目录结构的文件,因为您只会稍微修改现有的生物组件,您可以通过复制现有的文件作为起点来节省一些时间,使用cp(复制)命令:
1mkdir -p src/gatsby-theme-blog/components
2cp node_modules/gatsby-theme-blog/src/components/bio-content.js src/gatsby-theme-blog/components/bio-content.js
现在打开新复制的文件,并进行以下修改:
1[label src/gatsby-theme-blog/components/bio-content.js]
2import React, { Fragment } from "react"
3
4const BioContent = () => (
5 <Fragment>
6 <p>Content by DigitalOcean</p>
7 <p>License Info:</p>
8 <p
9 style={{
10 margin: "10px 20px",
11 padding: 8,
12 backgroundColor: "#0069ff",
13 color: "white",
14 borderRadius: 12,
15 }}
16 >
17 This work is licensed under a Creative Commons
18 Attribution-NonCommercial-ShareAlike 4.0 International License.
19 </p>
20 </Fragment>
21)
22
23export default BioContent
保存并关闭此文件,因为您现在已经完成了影子文件的编辑。
在此文件中,您已将原始 bio-content.js 文件遮蔽,用作者名称和许可证信息替换了位置保持者文本.您已通过替换由 BioContent React 组件返回的 JSX 来做到这一点。
通过在您的终端中再次运行npm run develop,您将启动Gatsby开发服务器,并可以在您的所有博客帖子中预览更改:
通过使用Gatsby shadowing,您刚刚修改了第三方Gatsby主题,超出了标准配置,混合了自己的自定义重叠和扩展。
结论
通过遵循本教程中的步骤,您现在有一个Gatsby网站,它使用了一种发布的主题来将多个组件和包装功能作为一个单一的依赖性。 由于这个包装的功能,您的网站现在更容易更新,并且可以包含更少的配置和设置代码,尽管有额外的功能。
虽然本教程涵盖了一个特定的主题,但它概述的概念和方法一般适用于盖茨比主题. 有关盖茨比主题的更多信息,请参阅 官方盖茨比文档。