如何在Gatsby中从Markdown生成页面

作为 Write for DOnations 计划的一部分，作者选择了 Internet Archive 来接收捐赠。

介绍

流行的静态站点生成器 Gatsby 的关键特性之一是它在使用内容源方面的灵活性。 Gatsby 可以从几乎任何数据源生成静态页面，例如 内容管理系统 (CMS)、API、 数据库，甚至是本地文件系统。

Markdown 文件是与 Gatsby 一起使用的流行的基于文件的源。 Markdown 是一种 标记语言 ，它轻量级且专为可读性而设计，非常适合文档项目、博客文章或任何文本繁重的网站。

在本教程中，您将创建一个由本地 Markdown 源文件构建的 Gatsby 支持的静态站点，使用 gatsby-source-filesystem 插件收集文件并使用 gatsby-transformer-remark 插件将它们转换为 HTML。

先决条件

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

• Node.js 的本地安装，用于运行 Gatsby 并构建您的站点。 安装过程因操作系统而异，但 DigitalOcean 有 Ubuntu 20.04 和 macOS 的指南，您始终可以在 官方 Node.js 下载页面找到最新版本[ X213X]。
• 对 JavaScript 有一定的了解，以便在 Gatsby 中工作。 JavaScript 语言是一个广泛的话题，但一个很好的起点是我们的 如何在 JavaScript 中编码 系列。
• 如果您想自定义帖子的用户界面 (UI) 超出本教程的范围，则对 React 和 JSX 以及 HTML 元素 有一定的了解。
• 一个名为 markdown-tutorial 的新 Gatsby 项目，由 gatsby-starter-default 搭建而成。 要从头开始构建一个新的 Gatsby 项目，您可以参考 如何设置您的第一个 Gatsby 网站 教程的 Step 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 作为一种标记语言的灵活性，用 Markdown 编写的文档可以呈现出各种形式和复杂程度。 Gatsby 不要求您以相同的方式格式化所有 Markdown 文件，但为了使您的站点和 URL 更易于组织，您将首先标准化您在此项目中编写和存储 Markdown 文件的方式。

在本教程中，您将向您的站点添加博客文章，每篇文章都有标题、自定义 URL、发布日期和文章正文。 您将从一篇文章开始，Learning About Gatsby，在这里您可以与全世界分享您了解 Gatsby 的经验。

为了准备存储这篇文章和未来的文章，在 src 下创建一个新目录，命名为 blog。 如果您更喜欢从命令行执行此操作，您可以使用项目根目录中的 mkdir 执行此操作：

mkdir src/blog

接下来，在该新目录中创建一个空的 Markdown 文件。 出于本教程的目的，文件名不控制发布的 URL 或 SEO，因此此处的命名约定只是为了使事情井井有条。 将您的新帖子命名为 learning-about-gatsby.md。

您可以在 IDE 中执行此操作，也可以将终端与 touch 一起使用：

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

最后，填写帖子的实际内容。 在您选择的编辑器中打开文件并添加以下内容：

降价教程/src/blog/learning-about-gatsby.md

---
title: "Learning about Gatsby"
slug: "/blog/learning-about-gatsby"
date: "2021-08-01"
---

## What I'm Working On

Right now, I'm working through a [DigitalOcean tutorial](https://www.digitalocean.com/community/tutorials) on using [Gatsby](https://www.gatsbyjs.com/) with Markdown.

由 --- 包围的顶部称为 frontmatter，由键值对组成。 它是用 YAML 编写的，它是 Markdown 之外的一种配置语言。 属性键在左边，你的值在右边。 在你的 frontmatter 块中，你已经为你的文章标题、发布日期和 slug 定义了值。 slug 是帖子 URL 的自定义部分，位于您的域名之后（也称为 路径 ）。

frontmatter 下方的任何文本都将成为帖子正文。 在该区域内，您的标题为 What I'm Working On，行首有两个井号 (##)。 在 Markdown 中，这表示 2 级标题，Gatsby 将在 HTML 中将其转换为 <h2></h2>。 在该标题下方的文本中，您有一些使用 Markdown 语法编写的链接：[link_text](link_destination)。

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

您刚刚使用 Markdown 创建了第一篇文章并将其保存在项目的源代码中。 您还对格式进行了标准化，包括博客文章前文中的特定属性值。 这可以使您的源代码井井有条，并且对于以后的步骤很重要。 现在，下一步是安装和配置 Gatsby 处理这个新的 Markdown 帖子所需的插件。

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

准备好 Markdown 文件后，是时候告诉 Gatsby 在哪里找到并处理它们了。 在此步骤中，您将安装实现此目的所需的插件并更新 Gatsby 配置以加载它们。

在 Gatsby 中处理 Markdown 需要两个插件：gatsby-transformer-remark 和 gatsby-source-filesystem。 gatsby-transformer-remark 将解析您的 Markdown 并将您的 frontmatter 转换为 Gatsby 可以查询的字段，并且 gatsby-source-filesystem 将允许您将数据从本地文件系统带入您的应用程序。

通过在 Gatsby 项目目录中运行以下命令同时安装两者：

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

安装这两个插件后，打开位于项目文件夹根目录中的 Gatsby 主配置文件：gatsby-config.js。 通过编辑这个文件，你告诉 Gatsby 如何使用新安装的插件来读取你的 Markdown 文件并开始处理它们。 将以下代码添加到您的配置文件中：

降价教程/gatsby-config.js

module.exports = {
...
  plugins: [
    `gatsby-plugin-react-helmet`,
    `gatsby-plugin-image`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images`,
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `blog`,
        path: `${__dirname}/src/blog`,
      },
    },
    `gatsby-transformer-remark`,
    `gatsby-transformer-sharp`,
...

第一个块加载 gatsby-source-filesystem 插件并传递给它一个 options object 告诉它扫描 src/blog 目录中的文件并使用 [ X155X] 名称作为集合的标签。 最后一行加载带有所有默认选项的 gatsby-transformer-remark 插件，因为您不需要为本教程自定义它们。

您现在已经配置 Gatsby 以加载扫描和解析 Markdown 文件所需的两个插件。 在下一步中，您将为 Gatsby 创建一个页面模板文件，以与您的 Markdown 内容结合并呈现为网页。

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

Gatsby 现在将扫描您的 Markdown 文件并使用 gatsby-transformer-remark 处理它们，但它仍然需要有关如何在浏览器中显示它们的说明。 此步骤涵盖如何通过添加页面模板文件（也称为 页面模板组件 ）来为其提供这些说明。

首先，在 src/pages 中创建一个空文件，文件名为 {MarkdownRemark.frontmatter__slug}.js。 文件名需要与此完全匹配，因为它使用称为 文件系统路由 API 的 Gatsby API，其中文件名指示在您的站点上创建的路由（URL）。

注意： 文件系统路由 API 是 Gatsby 中的一个较新功能，您可能仍然会在 gatsby-node.js 中看到其他涉及 createPages API 的 Markdown 页面教程。 尽管它没有被弃用，但对于本教程涵盖的用例来说，该 API 不再是必需的。 但是，如果您的项目涉及创建不镜像文件系统或以其他方式超出文件系统路由 API 功能的任意页面，您可能仍需要使用 createPages 方法 .

要创建您的组件，请将以下代码添加到文件中：

markdown-tutorial/src/pages/{MarkdownRemark.frontmatter__slug}.js

import { graphql } from "gatsby";
import * as React from "react";
import Layout from "../components/layout";
import Seo from "../components/seo";

export default function BlogPostTemplate({ data: { markdownRemark } }) {
  const { frontmatter, html } = markdownRemark;
  return (
    <Layout>
      <Seo title={frontmatter.title} />
      <h1>{frontmatter.title}</h1>
      <h2>{frontmatter.date}</h2>
      <div className="post-body" dangerouslySetInnerHTML={{ __html: html }} />
    </Layout>
  );
}

export const pageQuery = graphql`
  query ($id: String!) {
    markdownRemark(id: { eq: $id }) {
      html
      frontmatter {
        date(formatString: "MMMM DD, YYYY")
        title
      }
    }
  }
`;

这段代码有两个主要部分。 文件末尾的一个是 pageQuery，它使用 Gatsby GraphQL 标签 来评估 紧随其后的 GraphQL 查询 。 该查询的结果将传递给 BlogPostTemplate 函数，并允许您访问通过 GraphQL 获取的帖子的属性。

BlogPostTemplate 函数是一个 React 组件，它返回 JSX。 在 BlogPostTemplate 中，您可以在标题元素中显示每个帖子的标准化前端字段、标题和日期的值。 您已将帖子的实际正文放入具有 post-body 类的 <div> 中，使用 React 的 dangerouslySetInnerHTML 属性将 HTML 直接回显到渲染结果中。

最后，在你的代码中声明 BlogPostTemplate 函数之前使用 export default 是必要的，因为 Gatsby 会期望每个页面模板文件的默认导出是负责生成最终渲染页面的 React 组件。

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

在完成此步骤时，您向 Gatsby 项目添加了一个全新的页面模板文件。 使用使用文件系统路由 API 的文件名，它会根据 GraphQL 结果和您的 Markdown 源文件动态创建路由和页面。 这是让 Gatsby 从 Markdown 生成页面的最后一步。 在下一步中，您将看到这些页面正在运行，以及添加新页面。

第 4 步 — 预览您的内容并添加更多帖子

现在所有代码都可以将您的 Markdown 博客文章转换为网页，您现在可以预览您的工作并向您的网站添加更多 Markdown 内容。

要预览您的新博客文章和迄今为止所做的所有工作，请在您的项目目录中运行以下命令：

npm run develop

Gatsby 准备就绪后，它会提示您在 Web 浏览器中打开您的项目，您可以通过导航到 localhost:8000 来完成此操作。 但是，这首先只会显示 Gatsby 应用程序的主页，而不是博客文章。 要查看您的新 Markdown 博客文章，请导航至 localhost:8000/blog/learning-about-gatsby/。 你会发现你的 Markdown 文件呈现为 HTML：

从现在开始，您可以通过在 src/blog 目录中创建 Markdown 文件来继续添加新的博客文章。 每次创建新帖子时，请记住遵循您为 frontmatter 设置的约定。 这意味着确保以 /blog/ 开始 slug 值，后跟所需的自定义路径，并为帖子提供标题和日期。

要对此进行测试，请将您的 learning-about-gatsby.md Markdown 文件复制为名为 continuing-learning.md 的新帖子的基础：

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

接下来，打开新文件并对内容进行以下突出显示的更改：

降价教程/src/blog/continuing-learning.md

--- 
title: "Continuing to Learn"
slug: "/blog/continuing-learning"
date: "2021-08-01" 
--- 
 
## Update
 
I'm continuing to learn Gatsby to build some fast static sites!

在此文件中，您保持格式不变，但更改了 frontmatter 的 title 和 slug 以及博客文章的内容。 保存文件然后退出。

一旦您的服务器重建了 Gatsby 站点，请在浏览器中导航到 http://localhost:8000/blog/continuing-learning。 您将在此 URL 上找到呈现的新帖子：

注意： 如果你想在 blog 之外添加 Markdown 页面，你可以通过将 slug 修改为你想要的任何路径来实现。 如果这样做，请确保使用文件夹来保持文件井井有条。

您现在已经在 Gatsby 中从 Markdown 生成了新页面并预览了结果。

结论

按照本教程中的步骤，您将 Markdown 内容添加到 Gatsby 项目，配置 Gatsby 以查找文件并处理它们，并创建模板代码以将每个帖子呈现为新页面。 尽管使用 一个特定于 Markdown 的 Gatsby 入门模板 可以省略其中一些步骤，但手动完成该过程允许您完全按照您的需要自定义您的 Markdown 驱动的 Gatsby 站点。

虽然您可以使用 Gatsby Link 组件 链接到任何新帖子或页面，但如果您的网站有大量快速变化的 Markdown 文件，您可能需要探索添加动态列表作为下一步，因此，您网站的访问者可以快速找到您最近发布的所有帖子并导航到每个帖子。 为此，您可以使用 Gatsby GraphQL 标签来查询要列出的 Markdown 帖子，然后遍历它们并将它们显示为链接。 您可以在此 添加 Markdown 博客文章列表教程 中阅读有关此内容的更多信息。

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