Markdown
ドキュメントの書き方
はじめに
Fumadocs は、マークアップ言語である MDX に便利な拡張機能を多数提供しています。ここでは、Fumadocs におけるデフォルトの MDX 構文を簡単に紹介します。
Fumadocs がサポートしているフォーマットは MDX だけではありません。実際には、ヘッドレス CMS など任意のレンダラーを使用できます。
詳しくはカスタムコンテンツソースを参照してください。
MDX
JSX 構文を使える Markdown のスーパーセットである MDX をおすすめします。 コンポーネントをインポートしてドキュメント内で使用したり、JavaScript を記述したりすることもできます。
詳しくは以下を参照してください。
import { Component } from './component';
<Component name="Hello" />
## Heading
### Heading
#### Heading
Hello World, **Bold**, _Italic_, ~~Hidden~~
1. First
2. Second
3. Third
- Item 1
- Item 2
> Quote here
| Table | Description |
| ----- | ----------- |
| Hello | World |フロントマター
Fumadocs はデフォルトで YAML 形式のフロントマターに対応しています。Fumadocs UI では、title がページタイトル (h1) として使用されます。
---
title: This is a document
---
...そのため、ページタイトルのレンダリングに独自のロジックを用意していない限り、Markdown/MDX を書く際に h1 タイトル (# Heading) は通常使用しません。
コンテンツソースが対応していれば、フロントマターをコード内でエクスポートすることもできます。エクスポートした値は YAML のフロントマターを上書きする形でマージされ、props を参照することもできます。
---
title: Deploy
---
export const frontmatter = {
description: `Deploy your ${props.framework} site.`,
};Fumadocs MDX の場合
schema オプションを使用すると、フロントマターにプロパティを追加できます。詳しくはフロントマターのカスタマイズを参照してください。
自動リンク
内部リンクには、使用している React フレームワークの <Link /> コンポーネントが使われるため、プリフェッチが可能になり、ハードリロードも発生しません。
外部リンクには、セキュリティ対策としてデフォルトで rel="noreferrer noopener" target="_blank" 属性が付与されます。
[My Link](https://github.github.com/gfm)
This also works: https://github.github.com/gfm.Cards
リンクを追加するのに便利です。
import { HomeIcon } from 'lucide-react';
<Cards>
<Card href="/docs" title="Documentation">
Browse the full documentation.
</Card>
<Card title="href is optional">Cards can hold plain content too.</Card>
<Card icon={<HomeIcon />} href="/" title="Home">
You can include icons too.
</Card>
</Cards>「関連情報」セクション
次のように記述できます。
import { getPageTreePeers } from 'fumadocs-core/page-tree';
import { source } from '@/lib/source';
<Cards>
{getPageTreePeers(source.getPageTree(), '/docs/my-page').map((peer) => (
<Card key={peer.url} title={peer.name} href={peer.url}>
{peer.description}
</Card>
))}
</Cards>;同じフォルダー内にある他のページがカード形式で表示されます。
Callouts
ヒントや警告を追加するのに便利なコンポーネントで、デフォルトで含まれています。Callout の種類は次のように指定できます。
info(デフォルト)warn/warningerrorsuccessidea
<Callout>Hello World</Callout>
<Callout title="Title" type="warn">
Hello World
</Callout>
<Callout title="Title" type="error">
Hello World
</Callout>
<Callout title="Title" type="idea">
Hello World
</Callout>タイトル
Hello World
タイトル
Hello World
タイトル
Hello World
見出し
各見出しにはアンカーが自動的に付与され、スペースなどの無効な文字はサニタイズされます(例：Hello World は hello-world になります)。
# Hello `World`目次の設定
目次 (TOC) は見出しをもとに生成されます。見出しが目次にどう反映されるかをカスタマイズすることもできます。
# Heading [!toc]
This heading will be hidden from TOC.
# Another Heading [toc]
This heading will **only** be visible in TOC, you can use it to add additional TOC items.
Like headings rendered in a React component:
<MyComp />カスタムアンカー
見出しに [#slug] を追加すると、アンカーをカスタマイズできます。
# heading [#my-heading-id]次のように、目次の設定と組み合わせることもできます。
# heading [toc] [#my-heading-id]特定の見出しへのリンクを共有するには、ハッシュフラグメントに見出しの ID を指定します (例: /page#my-heading-id) 。
コードブロック
シンタックスハイライトは、Rehype Code によってデフォルトでサポートされています。
```js
console.log('Hello World');
```
```js title="My Title"
console.log('Hello World');
```行番号
行番号を表示します。Twoslash やその他のトランスフォーマーと組み合わせて使うこともできます。
```ts twoslash lineNumbers
const a = 'Hello World';
// ^?
console.log(a);
```行番号の開始値を設定できます。
```js lineNumbers=4
function main() {
console.log('starts from 4');
return 0;
}
```Shiki トランスフォーマー
Shiki トランスフォーマーの一部に対応しており、特定の行をハイライトしたり、スタイルを適用したりできます。
```tsx
// 行をハイライト
<div>Hello World</div> // [!code highlight]
// 単語をハイライト
// [!code word:Fumadocs]
<div>Fumadocs</div>
// 差分の表示
console.log('hewwo'); // [!code --]
console.log('hello'); // [!code ++]
// フォーカス
return new ResizeObserver(() => {}) // [!code focus]
```タブグループ
```ts tab="Tab 1"
console.log('A');
```
```ts tab="Tab 2"
console.log('B');
```console.log('A');永続化用の ID を追加するには、最初のコードブロックで tab-group を定義します。
```ts tab="Tab 1" tab-group="my-custom-group"
console.log('A');
```
```ts tab="Tab 2"
console.log('B');
```console.log('A');別のグループ：
console.log('A');タブグループ内の MDX
タブグループは remark プラグインの remarkCodeTab によって提供されており、Fumadocs MDX ではデフォルトで有効になっています。タブの値で MDX を使用するには、parseMdx オプションを有効にしてください。
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkCodeTabOptions: {
parseMdx: true,
},
},
});```ts tab="<Building /> Tab 1"
console.log('A');
```
```ts tab="<Rocket /> Tab 2"
console.log('B');
```console.log('A');インクルード
別のファイル (Markdown/MDX ドキュメントも可) を参照します。Fumadocs MDX では、Remark Include によって常に有効になっています。
<include> タグで対象ファイルのパスを指定してください (パスは MDX ファイル自体からの相対パスです) 。
<include>./another.mdx</include>インクルードのその他の使い方については、こちらを参照してください。
Props
ページの props は、MDX 内で props として利用できます。たとえば、[framework] フォルダー内のページは、パスパラメーターから framework を受け取ります。
## Deploy on {props.framework}
Deploy your {props.framework} site.式は、目次、検索インデックス、LLM向けのMarkdownでも、評価後の値に置き換えられます。Astroのページでは、上の見出しのIDはdeploy-on-astroになります。
ページにカスタムpropsを渡すこともできます。
Show
条件に応じてコンテンツをレンダリングします。Fumadocs MDX では、Remark Show によってデフォルトで有効になっています。
when は、props を参照できる JavaScript の式です。
<show when={props.framework === 'astro'}>
## Adapters
Add an adapter to your Astro config.
</show>このセクションは、framework が astro のページでのみレンダリングされます。それ以外のページでは、目次、検索インデックス、LLM 向けの Markdown からも除外されます。
ステップを <show> で囲むこともできます。
### Build [step]
<show when={props.framework === 'astro'}>
### Add an Adapter [step]
</show>
### Deploy [step]レンダリングされないステップは番号付けの対象外になります。たとえば Deploy は、Astro のページではステップ 3、それ以外のページではステップ 2 になります。
タブグループのコードブロックも同様です。タブは、対応するコードブロックがレンダリングされる場合にのみ表示されます。
NPM コマンド
各種パッケージマネージャー向けに、パッケージのインストールコマンドを生成する際に便利です。
```npm
npm i next -D
```詳細はremark-npmを参照してください。
ステップ
ガイドで手順を示すのに便利です。有効化と設定の方法については、remark-steps を参照してください。
### Installation [step]
### Write Code [step]
### Deploy [step]その他のコンポーネント
タブ、アコーディオン、Zoomable Image などの組み込みコンポーネントを設定して、MDX ドキュメント内で使用できます。
その他の機能
以下のページもあわせてご覧ください。
How is this guide?
最終更新日
General Translation
Ferry Health
assistant-ui
Inkeep