作者选择了 Internet Archive作为 Write for Donations计划的一部分接受捐赠。

介绍

受欢迎的静态网站生成器(Gatsby)的关键特征之一(LINK0)是其在消耗内容源的灵活性。Gatsby可以从几乎任何数据源生成静态页面,如内容管理系统(CMS)(LINK1)、API(LINK2)、数据库(LINK3)甚至是本地文件系统。

Markdown文件是一个流行的基于文件的源,可用于Gatsby。 _Markdown_是一个轻量级的标记语言(https://en.wikipedia.org/wiki/Markup_language),用于可读性,这使得它非常适合文档项目,博客帖子或任何重文本的网站。

在本教程中,您将创建一个基于Gatsby的静态网站,它从本地Markdown源文件中构建,使用gatsby-source-filesystem插件收集文件,以及gatsby-transformer-remark插件将其转换为HTML。

前提条件

在开始之前,这里有一些你需要的东西:

• 当地安装Node.js,用于运行Gatsby并建设你的站点。 安装程序因操作系统而异,但DigitalOcean有Ubuntu 20.04和macOS的指南,您总是可以在官方节点.js下载页上找到最新的发布. *一些熟悉的JavaScript,在加兹比工作. JavaScript语言是一个可扩展的话题,但好的起步点是我们[如何用JavaScript来编码 (https://www.digitalocean.com/community/tutorial_series/how-to-code-in-javascript)系列.
• 如果您想要自定义您职位的用户界面(UI),超出本教程的涵盖范围,则需要熟悉反应和JSX以及HTML元素.
• 一个新的Gatsby项目,取自`gatsby-starter-default'。 要从零开始构建新的Gatsby项目,可以参考"如何设置您的第一个Gatsby网站"(https://andsky.com/tech/tutorials/how-to-set-up-your-first-gatsby-website)的步骤1 . .

本教程已在 Node.js v14.16.1, npm v6.14.12, Gatsby v3.10.2, gatsby-source-filesystem v3.10.0 和 gatsby-transformer-remark v4.7.0 上测试。

步骤1 - 标准化您的标记内容

鉴于 Markdown 作为标记语言的灵活性,用 Markdown 编写的文档可以采用各种形式和复杂度。Gatsby 不要求您以相同的方式格式化所有 Markdown 文件,但为了使您的网站和 URL 更容易组织,您首先将标准化您在该项目中写和存储您的 Markdown 文件的方式。

对于本教程,您将添加博客帖子到您的网站,每个帖子将有一个标题,自定义的URL,发布日期和帖子体。

为了准备存储这个和未来的帖子,在src下创建一个新的目录,名为blog。如果你更喜欢从命令行中这样做,你可以从项目的根目录中用mkdir这样做:

1mkdir src/blog

接下来,在该新目录中创建一个空的 Markdown 文件,为本教程的目的,文件名不控制发布的 URL 或 SEO,所以这里的命名公约只是为了保持事情的组织。

您可以在您的 IDE 中这样做,或者使用触摸的终端:

1touch src/blog/learning-about-gatsby.md

最后,填写文章的实际内容,在您选择的编辑器中打开文件,并添加以下内容:

 1[label markdown-tutorial/src/blog/learning-about-gatsby.md]
 2---
 3title: "Learning about Gatsby"
 4slug: "/blog/learning-about-gatsby"
 5date: "2021-08-01"
 6---
 7
 8## What I'm Working On
 9
10Right now, I'm working through a [DigitalOcean tutorial](https://andsky.com/tech/tutorials) on using [Gatsby](https://www.gatsbyjs.com/) with Markdown.

由 `--- 附带的顶部部分被称为 frontmatter 并由关键值对组成。 它是用 YAML 编写的,这是 Markdown 以外的配置语言。 属性密钥在左边,你的值在右边。 在你的 frontmatter 块中,你已经为你的帖子的标题,发布日期和 slug 定义了值。

在该区域内,你有一个我正在工作的标题,有两个哈希符号(# )在行开始时。在Markdown中,这表明一个2级标题,Gatsby将在HTML中将其转换为

将更改保存到learning-about-gatsby.md,然后关闭文件。

您刚刚使用 Markdown 创建了您的第一个帖子,并将其保存到您的项目的源代码中。 您还将格式标准化,包括博客帖子的前面特定属性值。 这将保持您的源代码组织,并对后续步骤至关重要。

步骤 2 — 安装和配置所需的插件

有了你的Markdown文件,是时候告诉Gatsby在哪里找到它们并处理它们了,在这个步骤中,你将安装实现这一目标所需的插件,并更新Gatsby配置来加载它们。

需要两个插件来处理Gatsby的Markdown: gatsby-transformer-remark和 [gatsby-source-filesystem(https://www.gatsbyjs.com/plugins/gatsby-source-filesystem/))。

在您的 Gatsby 项目目录中同时运行下列命令:

1npm install gatsby-source-filesystem gatsby-transformer-remark

安裝兩個插件後,開啟主要的 Gatsby 配置檔案,它生活在您的項目文件夾的根: `gatsby-config.js. 通過編輯這個檔案,你告訴 Gatsby 如何使用新安裝的插件來閱讀您的 Markdown 檔案並開始處理它們。

 1[label markdown-tutorial/gatsby-config.js]
 2module.exports = {
 3...
 4  plugins: [
 5    `gatsby-plugin-react-helmet`,
 6    `gatsby-plugin-image`,
 7    {
 8      resolve: `gatsby-source-filesystem`,
 9      options: {
10        name: `images`,
11        path: `${__dirname}/src/images`,
12      },
13    },
14    {
15      resolve: `gatsby-source-filesystem`,
16      options: {
17        name: `blog`,
18        path: `${__dirname}/src/blog`,
19      },
20    },
21    `gatsby-transformer-remark`,
22    `gatsby-transformer-sharp`,
23...

第一个区块加载了gatsby-source-filesystem插件,并通过一个options object,告诉它扫描文件的src/blog目录,并使用blog名称作为收藏的标签。

你现在已经配置了Gatsby来加载需要扫描和解析你的Markdown文件的两个插件. 在下一步,你将创建一个页面模板文件为Gatsby与你的Markdown内容相结合,并作为网页渲染。

步骤 3 — 创建页面模板文件

Gatsby 现在将扫描您的 Markdown 文件并使用gatsby-transformer-remark处理它们,但它仍然需要在浏览器中显示它们的说明。

首先,在src/pages中创建一个空的文件,其文件名为{MarkdownRemark.frontmatter__slug}.js。该文件名必须完全匹配,因为它使用了一个Gatsby API,名为文件系统路由API(https://www.gatsbyjs.com/docs/reference/routing/file-system-route-api/),其中文件名决定了您网站上创建的路由(URL)。

<美元 > [注] ** 注:** 文件系统路由 API在Gatsby中是一个较新的功能,你可能会看到其他的Markdown页面教程,这些教程将创建PagesAPI用gatsby-node.js代替。 虽然它没有贬值,但对于本教程涵盖的用例来说,API已经没有必要了. 然而,如果有一个项目涉及创建任意页面,不反映文件系统,或以其他方式超过文件系统路由 API 的能力,你可能仍然需要使用'createPages' 方法. < $ > (美元)

若要创建您的组件,请将以下代码添加到文件中:

 1[label markdown-tutorial/src/pages/{MarkdownRemark.frontmatter__slug}.js]
 2import { graphql } from "gatsby";
 3import * as React from "react";
 4import Layout from "../components/layout";
 5import Seo from "../components/seo";
 6
 7export default function BlogPostTemplate({ data: { markdownRemark } }) {
 8  const { frontmatter, html } = markdownRemark;
 9  return (
10    <Layout>
11      <Seo title={frontmatter.title} />
12      <h1>{frontmatter.title}</h1>
13      <h2>{frontmatter.date}</h2>
14      <div className="post-body" dangerouslySetInnerHTML={{ __html: html }} />
15    </Layout>
16  );
17}
18
19export const pageQuery = graphql`
20  query ($id: String!) {
21    markdownRemark(id: { eq: $id }) {
22      html
23      frontmatter {
24        date(formatString: "MMMM DD, YYYY")
25        title
26      }
27    }
28  }
29`;

该代码有两个主要部分. 文件末尾的一个是「pageQuery」,它使用Gatsby GraphQL标签(https://www.gatsbyjs.com/docs/how-to/querying-data/page-query/)来评估接下来的GraphQL查询(https://andsky.com/tech/tutorials/understanding-queries-in-graphql)。

BlogPostTemplate函数是返回 JSX的 React 组件。在BlogPostTemplate中,您在标题元素中显示每个帖子的标准化前提字段的值,标题和日期。您将帖子的实际体置于一个div<>中,使用post-body类,使用 React 的dangerouslySetInnerHTML属性将 HTML 直接回响到渲染结果中。

最后,在声明BlogPostTemplate函数之前使用导出默认是您的代码中必要的,因为Gatsby将预计每个页面模板文件的默认导出将是负责生产最终渲染页面的React组件。

现在您已将模板代码添加到文件中,保存更改并关闭它。

完成此步骤后,您已将全新的页面模板文件添加到您的 Gatsby 项目中。使用使用 File System Route API 的文件名称,它会根据 GraphQL 结果和您的 Markdown 源文件动态地创建路线和页面。

步骤4 - 预览您的内容并添加更多帖子

有了所有代码,现在可以将你的Markdown博客帖子变成网页,你现在可以预览你的工作,并添加更多的Markdown内容到你的网站。

要预览您的新博客帖子和迄今为止所做的所有工作,请在项目目录中运行此命令:

1npm run develop

一旦Gatsby准备好了,它会提示你在Web浏览器中打开你的项目,你可以通过导航到localhost:8000。然而,这首先只会向你显示你的Gatsby应用程序的首页而不是博客帖子。 要查看你的新的Markdown博客帖子,请导航到localhost:8000/blog/learning-about-gatsby/`。 你会发现你的Markdown文件以HTML格式渲染:

从现在开始,你可以通过在src/blog目录中创建Markdown文件来继续添加新的博客帖子。每次你创建一个新帖子,请记住遵循你为前面设置的惯例。

要测试这一点,复制你的learning-about-gatsby.md标记文件成为一个名为continuing-learning.md的新文章的基础:

1cp src/blog/learning-about-gatsby.md src/blog/continuing-learning.md

接下来,打开新文件并对内容进行以下突出更改:

 1[label markdown-tutorial/src/blog/continuing-learning.md]
 2--- 
 3title: "Continuing to Learn"
 4slug: "/blog/continuing-learning"
 5date: "2021-08-01" 
 6--- 
 7
 8## Update
 9
10I'm continuing to learn Gatsby to build some fast static sites!

在此文件中,您保持相同的格式化,但更改了 frontmatter 的标题和slug以及博客帖子的内容。

一旦你的服务器重新构建了你的Gatsby网站,在你的浏览器中导航到http://localhost:8000/blog/continuing-learning。

注: 如果您想在博客之外添加标记页面,您可以通过修改slug到您想要的路径来做到这一点。

您现在有来自Gatsby的Markdown生成的新页面,并预览了结果。

结论

通过遵循本教程中的步骤,您将Markdown内容添加到您的Gatsby项目中,配置了Gatsby来查找文件并处理它们,并创建了模板代码,以使每个帖子作为一个新页面。

虽然您可以使用 [Gatsby `Link' 组件] (https://andsky.com/tech/tutorials/gatsbyjs-gatsby-link] 链接到任何新的帖子或页面,但如果您的站点有大量正在迅速变化的Markdown文件,您可能想探索作为下一步添加动态列表,因此访问您站点的访客可以快速找到您最近的所有帖子并浏览每个站点. 为此,您可以使用 Gatsby GraphQL 标记来查询您想要列出的 Markdown 帖子, 然后在它们上面斜移并显示为链接 。 您可以在此 [添加 Markdown Blog Posts 教程列表] (https://www.gatsbyjs.com/docs/adding-a-list-of-markdown-blog-posts/) 中读取更多关于此内容的内容 .

如果您想了解更多关于 Gatsby 的信息,请参阅 如何使用 Gatsby.js 系列创建静态网站的其余部分。