ギャツビーのMDXの紹介
あなたのほとんどはおそらくあなたのGatsby.jsサイトでMarkdownファイルを使用したことがあります、そしてあなたはそれがコンテンツを書くための素晴らしい方法であることをすでに知っています。 ただし、プレーンなMarkdownはテキストベースのコンテンツを対象としているため、そのユースケースの外に出たい場合は制限される可能性があります。 それはすべてMDXで変わります。これは、JSXをMarkdownファイルに直接埋め込むことができるMarkdownのスーパーセットです。 素晴らしいですね。 この記事では、ギャツビーを使用したMDXの基本について説明します。これには、すぐに使用を開始するのに役立ついくつかの入門テクニックが含まれます。
飛び込む前に、Gatsbyプロジェクトがセットアップされ、編集できるようになっている必要があります。 その点に到達するためのサポートが必要な場合は、 Gatsby v2 の最初のステップの手順に従って、後でここに戻ってください。
インストール
Gatsbyの信じられないほどのプラグインライブラリのおかげで、インストールプロセスは簡単です! GatsbyでMDXを使用するには、MDXピアの依存関係に加えて、単一のプラグインgatsby-plugin-mdxのみが必要です。
次のように、今すぐインストールしましょう。
$ yarn add gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react
また、 gatsby-source-filesystem をインストールして、frontmatterを利用し、ローカルファイルからGatsbyノードを生成し、MDXファイルでインポート/エクスポート機能を使用できるようにします。
$ yarn add gatsby-source-filesystem
技術的には必須ではありませんが、この手順は強く推奨されます。これは、ギャツビーでMDXコンテンツの可能性を最大限に引き出すためです。
構成
すべてのGatsbyプラグインと同様に、gatsby-config.js
のplugins
セクションに構成の詳細を追加する必要があります。
gatsby-plugin-mdx
とgatsby-source-filesystem
の両方を次のように構成しましょう。
gatsby-config.js
module.exports = { //...siteMetadata, etc plugins: [ { resolve: `gatsby-source-filesystem`, options: { name: `pages`, path: `${__dirname}/src/pages/`, }, }, { resolve: `gatsby-plugin-mdx`, options: { defaultLayouts: { default: require.resolve(`./src/components/layout.js`), }, }, // ... other plugins ], }
defaultLayouts
オプションでdefault
キーを設定していることに注意してください。 これにより、すべてのMDXファイルがサイトのデフォルトのlayout.js
コンポーネントで自動的にラップされます。
gatsby-config.jsファイルは編集されているので、先に進む前に開発環境を再起動することを忘れないでください!
構成オプション
gatsby-plugin-mdx
で使用できる構成オプションはいくつかあります。
- 拡張子:(文字列の配列)MDXとして処理されるファイル拡張子を設定します。 通常、これを
['.mdx', '.md']
に設定して、通常のMarkdownファイルもMDXとして処理します。 - defaultLayouts:(オブジェクト)これは、ブログ投稿や製品レビューなど、複数のタイプの生成されたコンテンツがある場合に頻繁に使用されます。 (上記のように、
default
キーを設定して、すべてのMDXファイルを自動ラップすることもできます。) - gatsbyRemarkPlugins:(プラグインオブジェクトの配列)これにより、MDX処理とともにさまざまなGatsby固有のコメントプラグインを使用できます。
gatsby-remark-images
プラグインはここでよく使用されます。 - remarkPlugins:(プラグインオブジェクトの配列)上記のオプションと同様ですが、Gatsbyに依存しないremarkプラグイン用です。
- rehypePlugins:(プラグインオブジェクトの配列)上記と同様ですが、rehypeプラグイン用です。
- mediaTypes:(文字列の配列)どのメディアタイプを処理するかを設定します。 (おそらく、これを頻繁に使用する必要はありません。)
これらのオプションの使用法の詳細については、プラグインのドキュメントを参照してください。 これらのドキュメントは優れているので、この記事を読んだ後でそれらを確認することを強くお勧めします。 🔍
基本的な使用法
これまでの構成では、サイト内のすべての.mdx
ファイルをすでに処理できます。 また、Gatsbyの組み込み動作のおかげで、src/pages/
ディレクトリに追加すると、自動的にページになります。
src/pages/mdx-intro/index.mdx
に簡単なMDXファイルを作成して、これを実行しましょう。 典型的なMarkdownブログページのように、いくつかのフロントマターと基本的なMarkdownテキストから始めます。
/src/pages/mdx-intro/index.mdx
--- title: MDX is Magical! path: /mdx-intro date: 2019-08-25 --- # Hooray For MDX! This will be like turbo-charged Markdown!
この新しいページを表示するには、ブラウザでhttp://localhost:8000/mdx-intro
にアクセスしてください。
Gatsby v2 の最初のステップを読んだ場合、このページ作成パターンに気付くでしょう。唯一の違いは、MarkdownではなくMDXファイルです。 これは今のところ特別でも新しいことでもありません。 それを変えましょう!
MDXでのコンポーネントの使用
MDXの主な機能の1つは、Markdownコンテンツ内でJSXコンポーネントをインポートして使用できることです。
これを示すために、/src/components/TitleBar.js
に、カスタマイズされたタイトルバーを表示できる簡単なコンポーネントを作成してみましょう。
/src/components/TitleBar.js
import React from 'react'; const TitleBar = ({ text, size, bkgdColor }) => ( <div style={{ margin: '2rem 0', padding: '2rem', backgroundColor: bkgdColor || '#fff', }} > <h2 style={{ fontSize: size || '18px', margin: 0, }} > {text} </h2> </div> ); export default TitleBar;
次に、MDXファイルを次のように更新しましょう。
/src/pages/mdx-intro/index.mdx
--- title: MDX is Magical! path: /mdx-intro date: 2019-08-25 --- import TitleBar from "../../components/TitleBar.js"; <TitleBar size={"32px"} bkgdColor={"#4aae9b"} text={props.pageContext.frontmatter.title} /> This will be like turbo-charged Markdown!
ここで注意すべきことが2つあります。
- まず、Markdown内に直接Reactコンポーネントをインポートして使用しました! これは非常に強力なの概念であるため、少しの間沈んでみましょう。 (アニメーションチャートや動的にロードされたデータ、複雑な双方向性などを備えたブログ投稿を想像してみてください。)
- 次に、
props.pageContext.frontmatter
からフロントマター値にアクセスできることに気付いたかもしれません。 これも非常に便利です。
重要:MDXファイルにfrontmatterが含まれている場合は、常にimportステートメントを afterfrontmatterブロックに配置してください。
先に進み、ブラウザで更新されたページを表示し、size
およびbkgdColor
プロップを編集して更新を確認してください。 これは非常に単純な例ですが、ここでも、Markdown内でReactコンポーネントを使用しています。 かなり甘いですよね?
レイアウトの割り当て
構成のセクションで説明したように、MDXはカスタムレイアウトを設定する簡単な方法を提供します。 これらのレイアウトは、MDXファイルの周りに追加のスタイルやコンテンツをラップするのに便利です。
デフォルトのレイアウトの構成
特定の場所であっても、gatsby-config.js
でMDXファイルのデフォルトのレイアウトを設定できます。 この例を見てください:
gatsby-config.js
module.exports = { plugins: [ { resolve: `gatsby-source-filesystem`, options: { name: `pages`, path: `${__dirname}/src/pages/`, }, }, { resolve: `gatsby-source-filesystem`, options: { name: `posts`, path: `${__dirname}/src/blog/`, }, }, { resolve: `gatsby-plugin-mdx`, options: { defaultLayouts: { posts: require.resolve("./src/components/blog-layout.js"), default: require.resolve("./src/components/layout.js"), }, }, }, ], }
この例では、/src/blog
ディレクトリから供給されたすべてのMDXファイルがblog-layout.js
をレイアウト/ラッパーとして使用するようにサイトを構成しました。 ここでもdefault
構成を設定します。
注:この動作は、現在、pages
ディレクトリから供給されたMDXファイルでは期待どおりに機能していないようです。 (ただし、現在行っているように、default
レイアウト設定でラップすることはできます。)
レイアウトを手動で割り当てまたは削除する
特定のMDXファイルを一意のレイアウトでラップする必要がある場合や、レイアウトをまったく使用しない場合があります。 これは、MDXファイル内でJavaScriptのexport default
構文を使用することで簡単に実行できます。これは、defaultLayout
設定をオーバーライドします。 これについては次のセクションで説明します。
他のMDXファイルのインポート
JSXコンポーネントのインポート/使用に加えて、他のMDXファイルをコンポーネントであるかのようにインポートして使用することもできます。 (ヒント:実際にはそうです!)
コンポーネントディレクトリの/src/components/postSignature.mdx
に新しいMDXファイルを作成しましょう。 MDXページの下部にあるこれを作成者の署名として使用します。
/src/components/postSignature.mdx
##### Thanks for Reading! *🐊 Al E. Gator | alligator.io | [email protected]* export default ({ children }) => ( <> {children} </> )
ファイルの下部にあるexport default
ステートメントに注意してください。 前のセクションで説明したように、これはdefaultLayout
構成設定をオーバーライドする方法です。 この場合、代わりに、署名の周りに空の<>
ラッパーをエクスポートしています。
次に、このMDX署名をメインのMDXファイルに/src/pages/mdx-intro/index.mdx
でインポートしてみましょう。
/src/pages/mdx-intro/index.mdx
--- title: MDX is Magical! path: /mdx-intro date: 2019-08-25 --- import TitleBar from "../../components/TitleBar.js"; import PostSignature from "../../components/postSignature.mdx"; <TitleBar size={"32px"} bkgdColor={"#4aae9b"} text={props.pageContext.frontmatter.title} /> This is like turbo-charged Markdown! <PostSignature />
これで、mdx-intro
ページの下部にこの署名が表示されます。 素晴らしい!! 😎
GraphQLクエリ
gatsby-plugin-mdx
とgatsby-source-filesystem
のプラグインコンボのおかげで、私たちのMDXページもGraphQLクエリを介してすぐに利用できます。
この機能は、同じ方法でプレーンなMarkdownファイルをクエリするのとほぼ同じであるため、これにはあまり時間をかけません。 (唯一の違いは、MDXノードがallMarkdownRemark
とmarkdownRemark
ではなくallMdx
とmdx
にあることです。)
利用可能なすべてのMDXファイルのフロントマターをフェッチするクエリの例を次に示します。
query { allMdx { edges { node { frontmatter { title path date(formatString: "MMMM DD, YYYY") } } } } }
その他のデータの提供
JavaScriptのexport
構文を使用してMDXファイルから追加データを提供することもできます(上記のexport default
と混同しないでください)。エクスポートされた変数はすべてGraphQLスキーマに自動的に追加されます。 GraphQLクエリで必要な場合やレンダリング中に使用できること。
MDXページに追加できる「FoodTruckReview」データの例を次に示します。
export const myReviews = [ { name: "Tim's Tacos", overall: 9, variety: 7, price: 8, taste: 9 }, { name: "Noodleville", overall: 7, variety: 5, price: 6, taste: 8 }, { name: "Waffle Shack", overall: 6, variety: 5, price: 4, taste: 6 }, ];
これをファイルの任意の場所に追加した後、次のようにallMdx.nodes.exports
にアクセスして、GraphQLのデータをクエリできます。
query MdxExports { allMdx { nodes { exports { myReviews { name overall variety price taste } } } } }
これは単なる本当にの基本的なデモですが、この機能は信じられないほどクリエイティブでダイナミックな方法で使用できます。
実用例
最後に、楽しく実用的な例をページに追加してみましょう。 上で設定したmyReviews
データを使用して、アニメーションの棒グラフを表示します。
まず、Rechartsライブラリをサイトに追加しましょう。 これは、クライアントプロジェクトで頻繁に使用する強力で軽量なチャートライブラリです。
$ yarn add recharts
次に、Rechartsを使用して、再利用可能な棒グラフコンポーネントを作成します。 これはRechartsに関する記事ではないため、/src/components/BarChart.js
で新しいファイルを作成し、次のコードを貼り付けてください。
/src/components/BarChart.js
import React, { PureComponent } from 'react'; import { BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ResponsiveContainer, } from 'recharts'; const colorsList = ['#008f68', '#6db65b', '#4aae9b', '#dfa612']; class ExampleChart extends PureComponent { render() { return ( <div style={{ width: '100%', height: 350 }}> <ResponsiveContainer> <BarChart data={this.props.data}> <CartesianGrid strokeDasharray="2 2" /> <XAxis dataKey="name" /> <YAxis type="number" domain={[0, 10]} /> <Tooltip /> <Legend /> {this.props.bars.map((bar, i) => ( <Bar dataKey={bar} fill={colorsList[i]} key={`bar_${i}`} /> ))} </BarChart> </ResponsiveContainer> </div> ); } } export default ExampleChart;
これで、優れた棒グラフコンポーネントが設定されたので、インポートしてMDXページで使用する必要があります。 これが最終バージョンです。
/src/pages/mdx-intro/index.mdx
--- title: MDX is Magical! path: /mdx-intro date: 2019-08-25 --- import TitleBar from '../../components/TitleBar'; import PostSignature from '../../components/postSignature.mdx'; import BarChart from "../../components/BarChart"; export const myReviews = [ { name: "Tim's Tacos", overall: 9, variety: 7, price: 8, taste: 9 }, { name: "Noodleville", overall: 7, variety: 5, price: 6, taste: 8 }, { name: "Waffle Shack", overall: 6, variety: 5, price: 4, taste: 6 }, ]; <TitleBar text={props.pageContext.frontmatter.title} size={'32px'} bkgdColor={'#4aae9b'} /> This page is built with turbo-charged Markdown! #### My Food Reviews: <BarChart data={myReviews} bars={["overall", "variety", "price", "taste"]} /> <PostSignature />
これで、見栄えのするマルチカラーの棒グラフが表示され、アニメーション化されて表示され、ロールオーバー時にアニメーション化されたツールチップも表示されます。 📊👈
そして、もう一度言います。これはすべてMarkdown(MDX)ページ内にあります!すぐに作成できるすべての興味深いブログ投稿とページを考えてみてください…
結論
このMDXのイントロでは、ギャツビーと一緒にたくさんのことを取り上げました。 それほど圧倒的ではなかったといいのですが、このコンボは、迅速なWebサイト開発のための完全なゲームチェンジャーであることがわかります。
ただし、可能なことのほんの一部にすぎません。 ここから、MDXのGatsbyドキュメントセクションを掘り下げることをお勧めします。 冒険する価値のあるうさぎの穴だと約束します! 🕳🐇