MarkdownとMDX

Markdownは、ブログ投稿やドキュメントのようなテキストを多用するコンテンツのオーサリングによく使います。Astroは標準的なMarkdownファイルをビルトインでサポートしています。

@astrojs/mdxインテグレーション (EN)をインストールすると、MDX（.mdx）ファイルにも対応し、MarkdownコンテンツでのJavaScript式やコンポーネントのサポートなどの追加機能を提供します。

Markdownコンテンツを書くには、どちらか一方、または両方のタイプのファイルを使用します。

MarkdownページとMDXページ

Section titled MarkdownページとMDXページ

ファイルベースルーティング

Section titled ファイルベースルーティング

Astroは、/src/pages/ディレクトリ内の.md（または対応する別の拡張子）または.mdxファイルをページとして扱います。

このディレクトリ、またはサブディレクトリにファイルを置くと、ファイルのパス名を使って自動的にページルートを構築します。

src/pages/page-1.md
---
title: Hello, World
---

# こんにちは！

このMarkdownファイルは `your-domain.com/page-1/`にページを作成します。

スタイリングとしてはおそらく不十分ですが、Markdownは以下をサポートしています。
- **太字** と _イタリック_
- リスト
- [リンク](https://astro.build)
- などなど

📚 Astroのファイルベースルーティングや、動的ルーティングを作成するオプションについてもっと読む。

下書きページ

Section titled 下書きページ

draft: trueはオプションのfront-matterの値で、個々のMarkdownまたはMDXページや投稿を「非公開」としてマークできます。デフォルトでは、マークされたページは次の動作になります。

  • サイトのビルド対象から外す（ページはビルドされない）
  • Astro.glob() (EN)によって返される (投稿の一覧で表示されます)
src/pages/post/blog-post.md
---
layout: ../../layouts/BaseLayout.astro
title: ブログ記事
draft: true
---

これは、作成中のブログ記事です。

この記事のためにページは作成されません。

この記事をビルドして公開するには

- front-matterを`draft: false`に更新する。
- または、`draft`プロパティ全体を削除してください。

しかし、このページは `Astro.glob()` にマッチするすべてのリクエストで返されます。

下書きの投稿を、投稿アーカイブや最新投稿のリストに含めないようにするには、Astro.glob()が返す結果をフィルタリングしてください。

const posts = await Astro.glob('../pages/post/*.md');
const nonDraftPosts = posts.filter((post) => !post.frontmatter.draft);

下書きページのビルドを有効にする

Section titled 下書きページのビルドを有効にする

デフォルトで下書きページもビルドするには、markdownまたはmdxインテグレーションにdrafts: trueを追加してastro.config.mjsを更新します。

astro.config.mjs
export default defineConfig({
  markdown: {
    drafts: true,
  },
  integrations: [mdx({
    drafts: true,
  })],
});

Markdownの機能

Section titled Markdownの機能

Astroは、MarkdownとMDXファイルを使用する際に利用できる、追加のビルトインMarkdown機能を提供します。

Front-matter layout

Section titled Front-matter layout

Astroは、MarkdownおよびMDXページに、Astroレイアウトコンポーネントへの相対パス（またはエイリアス）を指定できる特別なfront-matter用のlayoutプロパティを提供します。

src/pages/posts/post-1.md
---
layout: ../../layouts/BlogPostLayout.astro
title: Astroの概要
author: Himanshu
description: Astroの凄さを知ってください！
---
これはMarkdownで書かれた記事です。

front-matterプロパティは、Astro.propsを使ってレイアウトで利用できます。

src/layouts/BlogPostLayout.astro
---
const {frontmatter} = Astro.props;
---
<html>
  <!-- ... -->
  <h1>{frontmatter.title}</h1>
  <h2>投稿者: {frontmatter.author}</h2>
  <p>{frontmatter.description}<p>
  <slot /> <!-- Markdownコンテンツはここに挿入されます -->
   <!-- ... -->
</html>

📚 Markdownのレイアウトの詳細を見る。

見出しID

Section titled 見出しID

MarkdownとMDXで見出しを使用すると、自動的にアンカーリンクが作成され、ページ内の特定のセクションに直接リンクできます。

src/pages/page-1.md
---
title: コンテンツページ
---
## イントロダクション

Markdownで書くと、同じページの[結論](#結論)に内部リンクできます。

## 結論

URL`https://my-domain.com/page-1/#イントロダクション`を使って、ページ上のイントロダクションに直接移動できます。

特殊文字のエスケープ

Section titled 特殊文字のエスケープ

特定の文字は、MarkdownおよびMDXにおいて、特別な意味を持っています。それらを表示したい場合、異なる構文を使用する必要があるかもしれません。表示するには、これらの文字の代わりにHTMLエンティティを使用します。

たとえば、< がHTML要素の先頭と解釈されないようにするには、&lt;と記述します。また、MDXで{がJavaScriptの式の先頭と解釈されないようにするには、&lcub;と記述します。

MDXのみで使える機能

Section titled MDXのみで使える機能

AstroのMDXインテグレーション (EN)を追加すると、JSX変数、式、コンポーネントによってMarkdownオーサリングを強化できます。

また、MDXにおけるMarkdownスタイルのfront-matterのサポートなど、標準的なMDXにさらに機能を追加しています。これにより、front-matter layoutプロパティや下書きページの設定など、Astroの組み込みMarkdown機能のほとんどを使用できます。

.mdxファイルは、AstroのHTMLライクな構文ではなく、MDX構文で記述する必要があります。

MDXでエクスポートされた変数を使用する

Section titled MDXでエクスポートされた変数を使用する

MDXは、export文を使用してMDXコンテンツに変数を追加することをサポートします。これらの変数は、テンプレート自体でも、ファイルをどこかにインポートするときに名前付きプロパティとしてでもアクセスできます。

たとえば、MDXページやコンポーネントからtitleフィールドをエクスポートして、{JSX expressions}で見出しとして使用できます。

/src/pages/posts/post-1.mdx
export const title = 'はじめてのMDXの投稿'

# {title}

MDXでfront-matter変数を使用する

Section titled MDXでfront-matter変数を使用する

Astro MDXインテグレーションには、MDXでfront-matterを使用するためのサポートがデフォルトで含まれています。Markdownファイルと同じようにfrontmatterプロパティを追加すると、これらの変数はテンプレートやlayoutコンポーネント内において、あるいはどこかにファイルをインポートするときに名前付きプロパティとして使用する際にアクセスできます。

/src/pages/posts/post-1.mdx
---
layout: '../../layouts/BlogPostLayout.astro'
title: 'はじめてのMDXの投稿'
---

# {frontmatter.title}

MDXでコンポーネントを使用する

Section titled MDXでコンポーネントを使用する

MDXインテグレーションをインストールすると、AstroコンポーネントとUIフレームワークコンポーネントの両方をMDX（.mdx）ファイルにインポートして、他のAstroコンポーネントと同じように使用できるようになります。

必要であれば、UIフレームワークのコンポーネントにclient:directiveをつけ忘れないよう注意してください。

MDX docsでimportとexport文の他の使用例を確認してください。

src/pages/about.mdx
---
layout: ../layouts/BaseLayout.astro
title: About me
---
import Button from '../components/Button.astro';
import ReactCounter from '../components/ReactCounter.jsx';

私は**火星**に住んでいますが、気軽に<Button title="お問い合わせ" />までご連絡ください。

以下は、MDXで動作するカウンターコンポーネントです。

<ReactCounter client:load />

カスタムコンポーネントをHTML要素に割り当てる

Section titled カスタムコンポーネントをHTML要素に割り当てる

MDXを使用すると、標準のHTML要素の代わりに、Markdown構文をカスタムコンポーネントにマッピングできます。これにより、標準的なMarkdown構文で記述しながら、選択された要素に特別なコンポーネントスタイルを適用できます。

カスタムコンポーネントを.mdxファイルにインポートし、標準のHTML要素をカスタムコンポーネントにマップするcomponentsオブジェクトをエクスポートします。

src/pages/about.mdx
import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> この引用文はカスタムBlockquoteになります。
src/components/Blockquote.astro
---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- 子コンテンツのために `<slot/>` を必ず追加してください！ -->
</blockquote>

カスタムコンポーネントとして上書き可能なHTML要素の全リストは、MDXのウェブサイトをご覧ください。

Markdownのインポート

Section titled Markdownのインポート

MarkdownファイルやMDXファイルをAstroファイルに直接インポートできます。これにより、そのMarkdownコンテンツや、AstroのJSXライクな式で使用できるfront-matterの値などのプロパティにアクセスできます。

import文で特定の1ページを、Astro.glob()で複数のページをインポートできます。

src/pages/index.astro
---
// 1つのファイルのインポート
import * as myPost from '../pages/post/my-post.md';

// Astro.globによる複数ファイルのインポート
const posts = await Astro.glob('../pages/post/*.md');
---

AstroコンポーネントでMarkdownやMDXファイルをインポートすると、そのエクスポートされたプロパティを含むオブジェクトが取得されます。

/src/pages/posts/great-post.md
---
title: '今まで書いた中で最高の投稿'
author: 'Ben'
---

**素晴らしい**投稿をご紹介します。
src/pages/my-posts.astro
---
import * as greatPost from '../pages/post/great-post.md';

const posts = await Astro.glob('../pages/post/*.md');
---

<p>{greatPost.frontmatter.title}</p>
<p>執筆者: {greatPost.frontmatter.author}</p>

<p>投稿アーカイブ:</p>
<ul>
  {posts.map(post => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}
</ul>

MDXファイルでは、front-matterとexport文の両方からプロパティにアクセスできます。

/src/pages/posts/mdx-post.mdx
---
title: '今まで書いた中で最高の投稿'
author: 'Ben'
---
export const description = '快適に過ごそう! これは素晴らしい読み物になりそうです。'

私の**素晴らしい**投稿をご紹介します。
src/pages/my-posts.astro
---
import * as greatPost from '../pages/post/mdx-post.mdx';
---

<p>{greatPost.frontmatter.title}</p>
<p>執筆者: {greatPost.frontmatter.author}</p>
<p>{greatPost.description}</p>

オプションとして、TypeScriptのジェネリックを使用してfrontmatter変数の型を指定できます。

src/pages/index.astro
---
interface Frontmatter {
  title: string;
  description?: string;
}
const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
  <!-- post.frontmatter.title は `string`! -->
</ul>

エクスポートしたプロパティ

Section titled エクスポートしたプロパティ

.astroコンポーネントでimport文またはAstro.glob()を使用した場合、以下のプロパティが使用できます。

  • file - ファイルの絶対パス（例：/home/user/projects/.../file.md）。
  • url - もしページなら、そのページのURL (例:/en/guides/markdown-content)。
  • frontmatter - ファイルのYAML front-matterで指定された全データを含みます。
  • getHeadings - ファイル内のすべての見出し（すなわちh1 -> h6要素）の配列を返す非同期関数です。各見出しのslugは、与えられた見出しに対して生成されたIDに対応し、アンカーリンクに使用できます。このリストは次の型に従います。{ depth: number; slug: string; text: string }[]。
  • Content - ファイルのレンダリングされた完全なコンテンツを返すコンポーネントです。
  • (Markdownのみ) rawContent() - 生のMarkdownドキュメントを文字列として返す関数です。
  • (Markdownのみ) compiledContent() - HTML文字列にコンパイルされたMarkdownドキュメントを返す関数です。これはfront-matterで設定されたレイアウトを含まないことに注意してください。Markdownドキュメント自身のみがHTMLとして返されます。
  • (MDXのみ) - MDXファイルは、export文を使用してデータをエクスポートすることもできます。

Content コンポーネント

Section titled Content コンポーネント

Contentをインポートすると、MarkdownまたはMDXファイルを完全にレンダリングしたコンテンツを返すコンポーネントを使用できます。

src/pages/content.astro
---
import {Content as PromoBanner} from '../components/promoBanner.md';
---

<h2>本日のプロモーション</h2>
<PromoBanner />

例：動的ページルーティング

Section titled 例：動的ページルーティング

Markdown/MDXファイルをsrc/pages/ディレクトリに置いてページルートを作成する代わりに、ページを動的に生成できます。

Markdownコンテンツにアクセスするには、Astroページのpropsに<Content/>コンポーネントを渡します。そして、Astro.propsからコンポーネントを取得し、ページテンプレートにレンダリングできます。

src/pages/[slug].astro
---
export async function getStaticPaths() {
  const posts = await Astro.glob('../posts/**/*.md')

  return posts.map(post => ({
    params: { 
      slug: post.frontmatter.slug 
    },
    props: {
      post
    },
  }))
}

const { Content } = Astro.props.post
---
<article>
  <Content/>
</article>

エクスポート（MDXのみ）

Section titled エクスポート（MDXのみ）

MDXファイルでは、export文を使用してデータをエクスポートできます。

たとえば、MDXページやコンポーネントからtitleフィールドをエクスポートできます。

/src/pages/posts/post-1.mdx
export const title = 'はじめてのMDXの投稿'

このtitleはimportやAstro.glob() (EN)文からアクセスできます。

src/pages/index.astro
---
const posts = await Astro.glob('./*.mdx');
---

{posts.map(post => <p>{post.title}</p>)}

インポートしたMDXを使ったカスタムコンポーネント

Section titled インポートしたMDXを使ったカスタムコンポーネント

インポートしたMDXコンテンツをレンダリングする際、componentsプロパティでカスタムコンポーネントを渡せます。

src/pages/page.astro
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- # 記法のためのカスタムの <h1> を作成し、`content.mdx`で定義されたカスタムコンポーネントを適用します。 -->
<Content components={{...components, h1: Heading }} />

MarkdownとMDXの設定

Section titled MarkdownとMDXの設定

AstroのMarkdownサポートは、活発なエコシステムを持つ強力なパースおよび処理ツールであるremarkによって提供されています。Pandocやmarkdown-itなどの他のMarkdownパーサーは、現在サポートされていません。

Astroは、GitHub-flavored Markdownと Smartypantsプラグインをデフォルトで適用します。これにより、テキストからクリッカブルリンクを生成したり、読みやすさのために引用をフォーマットしたりといった、いくつかの便利な機能が提供されます。

remarkがMarkdownをどのように解析するかは、astro.config.mjsでカスタマイズできます。Markdownの設定オプションの全リストをご覧ください。

Markdownプラグイン

Section titled Markdownプラグイン

Astroは、MarkdownおよびMDXのためのサードパーティのremarkおよびrehypeプラグインの追加をサポートしています。これらのプラグインにより、目次の自動生成、アクセス可能な絵文字ラベルの適用など、新しい機能でMarkdownを拡張できます。

人気のあるプラグインはawesome-remarkとawesome-rehypeを参照するのがおすすめです。具体的なインストール方法については、各プラグインのREADMEをご覧ください。

この例では、Astroのデフォルトプラグインを維持したまま、MarkdownとMDXにremark-tocを適用し、MDXのみにrehype-accessible-emojisを適用しています。

astro.config.mjs
import { defineConfig } from 'astro/config';
import remarkToc from 'remark-toc';
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';

export default {
  markdown: {
    // .md と .mdx ファイルに適用
    remarkPlugins: [remarkToc],
    // remark-gfm と remark-smartypants を保持
    extendDefaultPlugins: true,
  },
  integrations: [mdx({
    // .mdx ファイルのみに適用
    rehypePlugins: [rehypeAccessibleEmojis],
  })],
}

例：front-matterの挿入

Section titled 例：front-matterの挿入

remarkやrehypeのプラグインを使用することで、すべてのMarkdownファイルやMDXファイルにfrontmatterプロパティを追加できます。

  1. プラグインのfile引数のdata.astro.frontmatterプロパティにcustomPropertyを追加してください。

    example-remark-plugin.mjs
    export function exampleRemarkPlugin() {
  // すべての remark および rehype プラグインは、別の関数を返します。
  return function (tree, file) {
    file.data.astro.frontmatter.customProperty = '生成されたプロパティ';
  }
}

  2. このプラグインをmarkdownまたはmdxのインテグレーション設定に適用します。

    astro.config.mjs
    import { exampleRemarkPlugin } from './example-remark-plugin.mjs';

export default {
  markdown: {
    remarkPlugins: [exampleRemarkPlugin],
    extendDefaultPlugins: true,
  },
};

    または

    astro.config.mjs
    import { exampleRemarkPlugin } from './example-remark-plugin.mjs';

export default {
  integrations: [
    mdx({
      remarkPlugins: [exampleRemarkPlugin],
    }),
  ],
}

これで、すべてのMarkdownまたはMDXファイルは、front-matterにcustomPropertyを持ち、Markdownのインポート時やレイアウトのAstro.props.frontmatterプロパティから利用できるようになります。

例：読書時間の計算

Section titled 例：読書時間の計算

remark pluginプラグインを使用すると、frontmatterに読了時刻を追加できます。次の2つのヘルパーがおすすめです。

npm install reading-time mdast-util-to-string

これらのパッケージをremarkプラグインに適用すると、以下のようになります。

remark-reading-time.mjs
import getReadingTime from 'reading-time';
import { toString } from 'mdast-util-to-string';

export function remarkReadingTime() {
  return function (tree, { data }) {
    const textOnPage = toString(tree);
    const readingTime = getReadingTime(textOnPage);
    // readingTime.textは、読書時間（分）をフレンドリーな文字列として出力します。
    // たとえば、"3 min read"
    data.astro.frontmatter.minutesRead = readingTime.text;
  };
}

このプラグインを設定ファイルに適用します。

astro.config.mjs
import { remarkReadingTime } from './remark-reading-time.mjs';

export default {
  markdown: {
    remarkPlugins: [remarkReadingTime],
    extendDefaultPlugins: true,
  },
};

これにより、すべてのMarkdownドキュメントは計算されたminutesReadを持つようになります。これを使用して、たとえばMarkdownレイアウトに読書時間を表示するバナーを含めることができます。

src/layouts/BlogLayout.astro
---
const { minutesRead } = Astro.props.frontmatter;
---

<html>
  <head>...</head>
  <body>
    <p>{minutesRead}</p>
    <slot />
  </body>
</html>

シンタックスハイライト

Section titled シンタックスハイライト

Astroは、ShikiとPrismをビルトインでサポートしています。これは、次のようなシンタックスハイライトを提供します。

Shikiはデフォルトで有効になっており、github-darkテーマであらかじめ設定されています。コンパイルされた出力は、余計なCSSクラス、スタイルシート、クライアントサイドJSのないインラインstyleに限定されます。

Shikiの設定

Section titled Shikiの設定

Shikiはデフォルトのシンタックスハイライトです。すべてのオプションはshikiConfigオブジェクト経由で以下のように設定できます。

astro.config.mjs
export default {
  markdown: {
    shikiConfig: {
      // Shikiの組み込みテーマから選択（または独自のテーマを追加）
      // https://github.com/shikijs/shiki/blob/main/docs/themes.md
      theme: 'dracula',
      // カスタム言語の追加
      // 注：Shikiには.astroを含む無数の言語が内蔵されています。
      // https://github.com/shikijs/shiki/blob/main/docs/languages.md
      langs: [],
      // 水平スクロールを防ぐために文字の折り返しを有効にする
      wrap: true,
    },
  },
};

独自テーマの追加

Section titled 独自テーマの追加

Shikiの定義済みテーマを使用する代わりに、ローカルファイルからカスタムテーマをインポートできます。

astro.config.mjs
import { defineConfig } from 'astro/config';
import customTheme from './my-shiki-theme.json';

export default defineConfig({
  markdown: {
    shikiConfig: { theme: customTheme },
  },
});

また、テーマ、ライトモードとダークモードの切り替え、CSS変数によるスタイリングについて詳しく調べるには、Shiki公式のテーマドキュメントを読むことをおすすめします。

デフォルトのシンタックスハイライトモードを変更する

Section titled デフォルトのシンタックスハイライトモードを変更する

デフォルトを'prism'に切り替えたい場合、またはシンタックスハイライトを完全に無効にしたい場合は、markdown.syntaxHighlighting設定オブジェクトを使用できます。

astro.config.mjs
export default {
  markdown: {
    // 'shiki'（デフォルト）、'prism'、またはハイライトを無効にする場合は false を指定します
    syntaxHighlight: 'prism',
  },
};

Prismの設定

Section titled Prismの設定

Prismの使用を選択した場合、AstroはPrismのCSSクラスを代わりに適用します。なお、シンタックスハイライトを表示させるには、独自のCSSスタイルシートを用意する必要があります。

  1. 利用可能なPrismテーマから、あらかじめ用意されたスタイルシートを選択します。
  2. このスタイルシートをプロジェクトのpublic/ディレクトリに追加します。
  3. これをレイアウトコンポーネントの<head>に<link>タグで読み込みます。（Prismの基本的な使い方を参照してください）

また、オプションや使い方については、Prismの対応言語一覧をご覧ください。

リモートにあるMarkdownの取得

Section titled リモートにあるMarkdownの取得

Astroは主にプロジェクトディレクトリ内に保存されるローカルのMarkdownファイル用に設計されています。しかし、リモートソースからMarkdownを取得する必要がある特定のケースもあるかもしれません。たとえば、ウェブサイトを構築するとき（またはSSRを使用している場合、ユーザーがウェブサイトにリクエストを行うとき）、リモートAPIからMarkdownを取得してレンダリングする必要があるかもしれません。

Astroは、標準でリモートのMarkdownをサポートしていません！ リモートのMarkdownを取得し、それをHTMLにレンダリングするには、npmから独自のMarkdownパーサーをインストールし、設定する必要があります。これは、カスタマイズしたAstroのビルトインMarkdownとMDXの設定をいずれからも継承しません。プロジェクトでこれを実装する前に、これらの制限を理解しておいてください。

src/pages/remote-example.astro
---
// 例: Markdown をリモートAPIから取得し、
// それを実行時にHTMLにレンダリングする。
// "marked" (https://github.com/markedjs/marked) を利用
import { marked } from 'marked';
const response = await fetch('https://raw.githubusercontent.com/wiki/adam-p/markdown-here/Markdown-Cheatsheet.md');
const markdown = await response.text();
const content = marked.parse(markdown);
---
<article set:html={content} />