MarkdownとMDX

Markdownは、ブログ投稿やドキュメントのようなテキストを多用するコンテンツのオーサリングによく使います。Astroは標準的なMarkdownファイルをビルトインでサポートしており、タイトルや説明文、タグなどのカスタムメタデータを定義するためのフロントマターYAMLも使用できます。

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

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

MarkdownページとMDXページ

コンテンツコレクション

Astroでは、MarkdownやMDXのファイルを専用のsrc/content/フォルダで管理できます。コンテンツコレクションは、コンテンツの整理、フロントマターの検証、コンテンツを扱う際のTypeScriptの自動型安全性確保に役立ちます。

ディレクトリsrc/content/
- ディレクトリnewsletter/
  - week-1.md
  - week-2.md
- ディレクトリauthors/
  - grace-hopper.md
  - alan-turing.md

詳しい使い方はAstroのコンテンツコレクションをご覧ください。

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

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

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

---
title: Hello, World
---

# こんにちは！

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

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

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

Markdownの機能

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

フロントマター `layout`

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

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

特定のプロパティは、Astro.propsを通してレイアウトコンポーネントで利用できます。たとえば、Astro.props.frontmatterを通して、フロントマターのプロパティにアクセスできます。

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

また、レイアウトコンポーネントでMarkdownをスタイリングすることもできます。

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

見出しID

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

---
title: コンテンツページ
---
## イントロダクション

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

## 結論

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

特殊文字のエスケープ

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

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

MDXのみで使える機能

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

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

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

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

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

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

export const title = 'はじめてのMDXの投稿'

# {title}

MDXでフロントマター変数を使用

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

---
layout: '../../layouts/BlogPostLayout.astro'
title: 'はじめてのMDXの投稿'
---

# {frontmatter.title}

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

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

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

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

---
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要素に割り当てる

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

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

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

> この引用文はカスタムBlockquoteになります。

---
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のインポート

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

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

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

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

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

---
title: '史上最高の投稿'
author: 'Ben'
---

**素晴らしい**投稿！

---
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ファイルでは、フロントマターとexport文の両方からプロパティにアクセスできます。

---
title: '史上最高の投稿'
author: 'Ben'
---
export const description = '快適に過ごそう! これは素晴らしい読み物になりそうです。'

**素晴らしい**投稿！

---
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変数の型を指定できます。

---
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>

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

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

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

`Content` コンポーネント

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

---
import {Content as PromoBanner} from '../components/promoBanner.md';
---

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

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

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

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

---
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のみ）

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

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

export const title = 'はじめてのMDXの投稿'

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

---
const posts = await Astro.glob('./*.mdx');
---

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

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

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

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

MarkdownとMDXの設定

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

AstroはデフォルトでGitHub-flavored Markdownプラグインを適用しています。これにより、テキストからクリック可能なリンクが生成されるなど、いくつかの利点があります。

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

Markdownプラグイン

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

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

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

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

export default {
  markdown: {
    // .md と .mdx ファイルに適用
    remarkPlugins: [remarkToc],
    rehypePlugins: [rehypeAccessibleEmojis],
  },
}

なお、デフォルトでは、remarkTocは目次を表示するために、ページ上に「ToC」または「Table of Contents」の見出し（大文字小文字を区別しない）を必要とします。

見出しのIDとプラグイン

Astroは、MarkdownやMDXファイルのすべての見出し要素（<h1>～<h6>）にid属性を注入し、MarkdownでエクスポートしたプロパティでこれらのIDを取得するためのgetHeadings()ユーティリティを提供しています。

id属性（rehype-slugなど）を注入するrehypeプラグインを追加することで、これらの見出しIDをカスタマイズできます。Astroのデフォルトではなく、あなたのカスタムIDがHTML出力とgetHeadings()が返すアイテムに反映されます。

デフォルトでは、Astroはrehypeプラグインが実行された後にid属性を注入します。もし、カスタムrehypeプラグインの1つがAstroによって注入されたIDにアクセスする必要がある場合、AstroのrehypeHeadingIdsプラグインを直接インポートして使用できます。rehypeHeadingIdsに依存するプラグインの前に必ずrehypeHeadingIdsを追加してください。

import { defineConfig } from 'astro/config';
import { rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      rehypeHeadingIds,
      otherPluginThatReliesOnHeadingIDs,
    ],
  },
});

プラグインの設定

プラグインを設定するためには、ネストされた配列の中で、プラグインの後にオプションオブジェクトを指定します。

以下の例では、remarkTocプラグインにheadingオプションを追加して目次の配置を変更し、rehype-autolink-headingsプラグインにbehaviorオプションを追加して、見出しテキストの後にアンカータグを追加しています。

import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';

export default {
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: "contents"} ] ],
    rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
  },
}

プログラムによるフロントマターの変更

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

プラグインのfile引数のdata.astro.frontmatterプロパティにcustomPropertyを追加してください。
example-remark-plugin.mjs
```
export function exampleRemarkPlugin() {
  // すべての remark および rehype プラグインは、別の関数を返します。
  return function (tree, file) {
    file.data.astro.frontmatter.customProperty = '生成されたプロパティ';
  }
}
```
追加： astro@2.0.0
data.astro.frontmatterは、与えられたMarkdownまたはMDXドキュメントからのすべてのプロパティを含んでいます。これにより、既存のフロントマタープロパティを修正したり、この既存のフロントマターから新しいプロパティを計算したりできます。

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

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

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

または

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

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

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

関連レシピ： Add reading time (EN)

MDXからMarkdown設定を継承

AstroのMDX統合は、デフォルトでプロジェクトの既存のMarkdown設定を継承します。個々のオプションを上書きするには、MDXの構成で同等のものを指定します。

次の例では、GitHub-Flavored Markdownを無効にし、MDXファイルに対して異なるremarkプラグインのセットを適用しています。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // Markdownから継承した`syntaxHighlight`

      // Markdownの`remarkPlugins`は無視され、
      // `remarkPlugin2`のみが適用される
      remarkPlugins: [remarkPlugin2],
      // `gfm`は`false`に上書きされる
      gfm: false,
    })
  ]
});

MDXからMarkdownの設定を継承しないようにするには、extendMarkdownConfigオプション (EN))（デフォルトで有効）をfalseに設定します。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkPlugin],
  },
  integrations: [
    mdx({
      // Markdownの設定は無視される
      extendMarkdownConfig: false,
      // `remarkPlugins`は適用されない
    })
  ]
});

シンタックスハイライト

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

MarkdownまたはMDXファイルで使用されているすべてのコードフェンス(```)。
組み込みの<Code />コンポーネント (EN)内のコンテンツ (Shikiを使用）。
<Prism />コンポーネント (EN)内のコンテンツ (Prismを使用）。

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

Shikiの設定

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

import { defineConfig } from 'astro/config';

export default defineConfig({
  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,
    },
  },
});

独自テーマの追加

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

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

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

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

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

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

import { defineConfig } from 'astro/config';

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

Prismの設定

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

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

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

リモートにあるMarkdownの取得

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

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

---
// 例: 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} />

貢献する

コミュニティ

MarkdownとMDX

MarkdownページとMDXページ

コンテンツコレクション

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

Markdownの機能

フロントマター `layout`

見出しID

特殊文字のエスケープ

MDXのみで使える機能

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

MDXでフロントマター変数を使用

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

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

Markdownのインポート

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

`Content` コンポーネント

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

エクスポート（MDXのみ）

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

MarkdownとMDXの設定

Markdownプラグイン

見出しのIDとプラグイン

プラグインの設定

プログラムによるフロントマターの変更

MDXからMarkdown設定を継承

シンタックスハイライト

Shikiの設定

独自テーマの追加

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

Prismの設定

リモートにあるMarkdownの取得

どんなことを？

GitHub Issueを作成

フィードバックを送信

フィードバックを送信

MarkdownとMDX

MarkdownページとMDXページ

コンテンツコレクション

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

Markdownの機能

フロントマター layout

見出しID

特殊文字のエスケープ

MDXのみで使える機能

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

MDXでフロントマター変数を使用

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

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

Markdownのインポート

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

Content コンポーネント

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

エクスポート（MDXのみ）

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

MarkdownとMDXの設定

Markdownプラグイン

見出しのIDとプラグイン

プラグインの設定

プログラムによるフロントマターの変更

MDXからMarkdown設定を継承

シンタックスハイライト

Shikiの設定

独自テーマの追加

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

Prismの設定

リモートにあるMarkdownの取得

フロントマター `layout`

`Content` コンポーネント