GatsbyでMarkdownからページを生成する方法

著者は、 Write for DOnations プログラムの一環として、 InternetArchiveを選択して寄付を受け取りました。

序章

人気のある静的サイトジェネレーターGatsbyの重要な機能の1つは、コンテンツソースを柔軟に利用できることです。 Gatsbyは、コンテンツ管理システム（CMS）、 API 、データベース、さらにはローカルファイルシステムなど、ほぼすべてのデータソースから静的ページを生成できます。

Markdown ファイルは、Gatsbyで使用する一般的なファイルベースのソースです。 Markdown はマークアップ言語で、軽量で読みやすく設計されているため、ドキュメントプロジェクト、ブログ投稿、またはテキストを多用するWebサイトに最適です。

このチュートリアルでは、gatsby-source-filesystemプラグインを使用してファイルを収集し、gatsby-transformer-remarkプラグインを使用してファイルをHTMLに変換し、ローカルのMarkdownソースファイルから自身を構築するGatsbyを利用した静的サイトを作成します。

前提条件

始める前に、ここにあなたが必要とするいくつかのものがあります：

Gatsbyを実行してサイトを構築するためのNode.jsのローカルインストール。インストール手順はオペレーティングシステムによって異なりますが、DigitalOceanには Ubuntu20.04およびmacOSのガイドがあり、最新リリースは公式Node.jsダウンロードページ[ X213X]。
Gatsbyで作業するためのJavaScriptにある程度精通している。 JavaScript言語は広大なトピックですが、出発点としては、JavaScriptでコーディングする方法シリーズが適しています。
このチュートリアルで説明されている以上に投稿のユーザーインターフェイス（UI）をカスタマイズする場合は、ReactとJSX、およびHTML要素にある程度精通している必要があります。
gatsby-starter-defaultから足場を組んだ、markdown-tutorialという名前の新しいGatsbyプロジェクト。新しいGatsbyプロジェクトを最初から作成するには、最初のGatsbyWebサイトのセットアップ方法チュートリアルのステップ1を参照してください。

このチュートリアルは、Node.js v14.16.1、npm v6.14.12、Gatsby v3.10.2、gatsby-source-filesystem v3.10.0、およびgatsby-transformer-remarkv4.7.0でテストされました。

ステップ1—マークダウンコンテンツの標準化

マークアップ言語としてのMarkdownの柔軟性を考えると、Markdownで記述されたドキュメントは、さまざまな形式と複雑さのレベルをとることができます。 Gatsbyでは、すべてのMarkdownファイルを同じ方法でフォーマットする必要はありませんが、サイトとURLを整理しやすくするために、まず、このプロジェクト内でのMarkdownファイルの作成方法と保存方法を標準化します。

このチュートリアルでは、ブログ投稿をサイトに追加します。各投稿には、タイトル、カスタマイズされたURL、公開日、および投稿本文が含まれます。まず、ギャツビーについて学ぶという1つの投稿から始めます。ここでは、ギャツビーについて学んだ経験を世界と共有できます。

この投稿と今後の投稿を保存する準備として、srcの下にblogという名前の新しいディレクトリを作成します。コマンドラインからこれを実行する場合は、プロジェクトのルートディレクトリからmkdirを使用して実行できます。

mkdir src/blog

次に、その新しいディレクトリ内に空のMarkdownファイルを作成します。このチュートリアルでは、ファイル名は公開されたURLまたは SEO を制御しないため、ここでの命名規則は、物事を整理するためのものです。新しい投稿にlearning-about-gatsby.mdのファイル名を付けます。

IDEでこれを行うか、touchでターミナルを使用できます。

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

最後に、投稿の実際の内容を入力します。選択したエディターでファイルを開き、以下を追加します。

markdown-tutorial / 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 と呼ばれ、キーと値のペアで構成されます。これは、Markdown以外の構成言語であるYAMLで記述されています。プロパティキーは左側にあり、値は右側にあります。フロントマターブロックでは、投稿のタイトル、公開日、およびスラッグの値を定義しました。スラッグは、ドメイン名の後に続く投稿のURLのカスタマイズされた部分です（パスとも呼ばれます）。

フロントマターの下のテキストはすべて投稿本文になります。その領域内には、What I'm Working Onの見出しがあり、行の先頭に2つのハッシュ記号（##）があります。 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の2つのプラグインが必要です。 gatsby-transformer-remarkは、Markdownを解析し、フロントマターをGatsbyがクエリできるフィールドに変換します。また、gatsby-source-filesystemを使用すると、ローカルファイルシステムからアプリケーションにデータを取り込むことができます。

Gatsbyプロジェクトディレクトリで次のコマンドを実行して、両方を同時にインストールします。

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

両方のプラグインをインストールした後、プロジェクトフォルダーのルートにあるメインのGatsby構成ファイルgatsby-config.jsを開きます。このファイルを編集することで、新しくインストールされたプラグインを使用してMarkdownファイルを読み取り、それらの処理を開始する方法をGatsbyに指示します。次のコードを構成ファイルに追加します。

markdown-tutorial / 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 オブジェクトを渡して、src/blogディレクトリでファイルをスキャンして[ X155X]コレクションのラベルとしての名前。最後の行では、gatsby-transformer-remarkプラグインにすべてのデフォルトオプションがロードされます。これは、このチュートリアルでそれらをカスタマイズする必要がないためです。

これで、Markdownファイルのスキャンインと解析に必要な2つのプラグインをロードするようにGatsbyを構成しました。次のステップでは、Gatsbyのページテンプレートファイルを作成して、Markdownコンテンツと組み合わせ、Webページとしてレンダリングします。

ステップ3—ページテンプレートファイルの作成

GatsbyはMarkdownファイルをスキャンし、gatsby-transformer-remarkで処理しますが、ブラウザーでそれらを表示する方法についての指示が必要です。この手順では、ページテンプレートファイル（ページテンプレートコンポーネントとも呼ばれます）を追加して、これらの指示を与える方法について説明します。

まず、src/pagesに{MarkdownRemark.frontmatter__slug}.jsというファイル名の空のファイルを作成します。ファイル名はこれと完全に一致する必要があります。これは、ファイルシステムルートAPIと呼ばれるGatsbyAPIを使用しているためです。このAPIでは、ファイル名によってサイトで作成されるルート（URL）が決まります。

注：ファイルシステムルートAPIはGatsbyの新しい機能であり、代わりにgatsby-node.jsのcreatePagesAPIを含む他のMarkdownページのチュートリアルが表示される場合があります。非推奨ではありませんが、このチュートリアルで取り上げるユースケースでは、そのAPIは不要になりました。ただし、ファイルシステムをミラーリングしない、または他の方法でFile System Route 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
      }
    }
  }
`;

このコードには2つの主要なセクションがあります。ファイルの最後にあるのはpageQueryで、 Gatsby GraphQLタグを使用して、それに続くGraphQLクエリを評価します。そのクエリの結果はBlogPostTemplate関数に渡され、GraphQLを介してフェッチされた投稿のプロパティにアクセスできます。

BlogPostTemplate関数は、JSXを返すReactコンポーネントです。 BlogPostTemplate内で、各投稿の標準化されたフロントマターフィールドの値、タイトルと日付をヘッダー要素に表示します。 post-bodyのクラスで<div>に配置した投稿の実際の本文。ReactのdangerouslySetInnerHTMLプロパティを使用して、レンダリングされた結果にHTMLを直接エコーアウトします。

最後に、BlogPostTemplate関数を宣言する前にexport defaultを使用する必要があります。これは、Gatsbyが各ページテンプレートファイルのデフォルトのエクスポートが最終的なレンダリングページの生成を担当するReactコンポーネントであると想定するためです。

テンプレートコードをファイルに追加したので、変更を保存して閉じます。

この手順を完了すると、Gatsbyプロジェクトに新しいページテンプレートファイルが追加されました。 File System Route APIを使用するファイル名を使用して、GraphQLの結果とMarkdownソースファイルに基づいてルートとページを動的に作成します。これは、GatsbyにMarkdownからページを生成させるための最後のステップでした。次のステップでは、これらのページの動作を確認し、新しいページを追加します。

ステップ4—コンテンツのプレビューと投稿の追加

Markdownブログの投稿をWebページに変換するためのすべてのコードが用意されたので、作業をプレビューして、Markdownコンテンツをサイトに追加できます。

新しいブログ投稿とこれまでに行ったすべての作業をプレビューするには、プロジェクトディレクトリで次のコマンドを実行します。

npm run develop

Gatsbyの準備が整うと、プロジェクトをWebブラウザーで開くように求められます。これは、localhost:8000に移動することで実行できます。ただし、これにより、最初はブログ投稿ではなく、Gatsbyアプリケーションのホームページのみが表示されます。新しいMarkdownブログ投稿を表示するには、localhost:8000/blog/learning-about-gatsby/に移動します。あなたはHTMLとしてレンダリングされたMarkdownファイルを見つけるでしょう：

今後は、src/blogディレクトリにMarkdownファイルを作成することで、新しいブログ投稿を追加し続けることができます。新しい投稿を作成するたびに、フロントマターに設定した規則に従うことを忘れないでください。つまり、slugの値は、/blog/の後に必要なカスタムパスを付けて開始し、投稿にタイトルと日付を指定してください。

これをテストするには、learning-about-gatsby.md Markdownファイルをコピーして、continuing-learning.mdという名前の新しい投稿のベースにします。

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

次に、新しいファイルを開き、コンテンツに次の強調表示された変更を加えます。

markdown-tutorial / 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!

このファイルでは、フォーマットを同じに保ちましたが、フロントマターのtitleとslugおよびブログ投稿の内容を変更しました。ファイルを保存して終了します。

サーバーがGatsbyサイトを再構築したら、ブラウザでhttp://localhost:8000/blog/continuing-learningに移動します。このURLでレンダリングされた新しい投稿が見つかります：

注： blogの外にMarkdownページを追加したい場合は、slugを任意のパスに変更することで追加できます。これを行う場合は、ファイルを整理するために必ずフォルダーを使用してください。

これで、GatsbyのMarkdownから生成された新しいページが作成され、結果がプレビューされました。

結論

このチュートリアルの手順に従って、GatsbyプロジェクトにMarkdownコンテンツを追加し、ファイルを検索して処理するようにGatsbyを構成し、各投稿を新しいページとしてレンダリングするためのテンプレートコードを作成しました。 Markdown固有のGatsbyスターターテンプレートを使用すると、これらの手順の一部を省略できますが、プロセスを手動で実行すると、Markdownを利用したGatsbyサイトを希望どおりにカスタマイズできます。

Gatsby Linkコンポーネントを使用して新しい投稿やページにリンクできますが、サイトに急速に変化する大量のMarkdownファイルがある場合は、次のステップとして動的リストを追加することを検討してください。そのため、サイトへの訪問者は、最新の投稿をすべてすばやく見つけて、それぞれに移動できます。これを行うには、Gatsby GraphQLタグを使用して、リストするMarkdown投稿をクエリし、それらを繰り返し処理してリンクとして表示します。これについて詳しくは、このMarkdownブログ投稿のリストの追加チュートリアルをご覧ください。

Gatsbyの詳細については、Gatsby.jsシリーズを使用して静的Webサイトを作成する方法の残りの部分を確認してください。