diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index adaf4daa7a70..7be361c84f30 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -52,6 +52,8 @@ export default defineConfig({ return 'Скопировать код' case 'zh': return '复制代码' + case 'ja': + return 'コードをコピー' default: return 'Copy code' } @@ -130,7 +132,8 @@ export default defineConfig({ ru: { label: 'Русский', lang: 'ru-RU', dir: 'ltr' }, es: { label: 'Español', lang: 'es', dir: 'ltr' }, ko: { label: '한국어', lang: 'ko-KR', dir: 'ltr' }, - fa: { label: 'فارسی', lang: 'fa-IR', dir: 'rtl' } + fa: { label: 'فارسی', lang: 'fa-IR', dir: 'rtl' }, + ja: { label: '日本語', lang: 'ja', dir: 'ltr' } }, vite: { diff --git a/docs/ja/config.ts b/docs/ja/config.ts new file mode 100644 index 000000000000..4f6ef26db55d --- /dev/null +++ b/docs/ja/config.ts @@ -0,0 +1,225 @@ +import { createRequire } from 'module' +import { defineAdditionalConfig, type DefaultTheme } from 'vitepress' + +const require = createRequire(import.meta.url) +const pkg = require('vitepress/package.json') + +export default defineAdditionalConfig({ + description: 'Vite と Vue による静的サイトジェネレーター', + + themeConfig: { + nav: nav(), + + search: { options: searchOptions() }, + + sidebar: { + '/ja/guide/': { base: '/ja/guide/', items: sidebarGuide() }, + '/ja/reference/': { base: '/ja/reference/', items: sidebarReference() } + }, + + editLink: { + pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path', + text: 'GitHub でこのページを編集' + }, + + footer: { + message: 'MIT ライセンスの下で公開されています。', + copyright: 'Copyright © 2019-present Evan You' + } + } +}) + +function nav(): DefaultTheme.NavItem[] { + return [ + { + text: 'ガイド', + link: '/ja/guide/what-is-vitepress', + activeMatch: '/guide/' + }, + { + text: 'リファレンス', + link: '/ja/reference/site-config', + activeMatch: '/reference/' + }, + { + text: pkg.version, + items: [ + { + text: '1.6.4', + link: 'https://vuejs.github.io/vitepress/v1/' + }, + { + text: '更新履歴', + link: 'https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md' + }, + { + text: 'コントリビュート方法', + link: 'https://github.com/vuejs/vitepress/blob/main/.github/contributing.md' + } + ] + } + ] +} + +function sidebarGuide(): DefaultTheme.SidebarItem[] { + return [ + { + text: '導入', + collapsed: false, + items: [ + { text: 'VitePress とは?', link: 'what-is-vitepress' }, + { text: 'はじめに', link: 'getting-started' }, + { text: 'ルーティング', link: 'routing' }, + { text: 'デプロイ', link: 'deploy' } + ] + }, + { + text: '執筆', + collapsed: false, + items: [ + { text: 'Markdown 拡張', link: 'markdown' }, + { text: 'アセットの取り扱い', link: 'asset-handling' }, + { text: 'フロントマター', link: 'frontmatter' }, + { text: 'Markdown で Vue を使う', link: 'using-vue' }, + { text: '多言語対応', link: 'i18n' } + ] + }, + { + text: 'カスタマイズ', + collapsed: false, + items: [ + { text: 'カスタムテーマを使う', link: 'custom-theme' }, + { + text: 'デフォルトテーマの拡張', + link: 'extending-default-theme' + }, + { text: 'ビルド時のデータ読み込み', link: 'data-loading' }, + { text: 'SSR 互換性', link: 'ssr-compat' }, + { text: 'CMS との接続', link: 'cms' } + ] + }, + { + text: '実験的機能', + collapsed: false, + items: [ + { text: 'MPA モード', link: 'mpa-mode' }, + { text: 'サイトマップ生成', link: 'sitemap-generation' } + ] + }, + { + text: '設定 & API リファレンス', + base: '/ja/reference/', + link: 'site-config' + } + ] +} + +function sidebarReference(): DefaultTheme.SidebarItem[] { + return [ + { + text: 'リファレンス', + items: [ + { text: 'サイト設定', link: 'site-config' }, + { text: 'Frontmatter 設定', link: 'frontmatter-config' }, + { text: 'ランタイム API', link: 'runtime-api' }, + { text: 'CLI', link: 'cli' }, + { + text: 'デフォルトテーマ', + base: '/ja/reference/default-theme-', + items: [ + { text: '概要', link: 'config' }, + { text: 'ナビゲーション', link: 'nav' }, + { text: 'サイドバー', link: 'sidebar' }, + { text: 'ホームページ', link: 'home-page' }, + { text: 'フッター', link: 'footer' }, + { text: 'レイアウト', link: 'layout' }, + { text: 'バッジ', link: 'badge' }, + { text: 'チームページ', link: 'team-page' }, + { text: '前 / 次 リンク', link: 'prev-next-links' }, + { text: '編集リンク', link: 'edit-link' }, + { text: '最終更新日時', link: 'last-updated' }, + { text: '検索', link: 'search' }, + { text: 'Carbon 広告', link: 'carbon-ads' } + ] + } + ] + } + ] +} + +function searchOptions(): Partial { + return { + placeholder: 'ドキュメントを検索', + translations: { + button: { + buttonText: '検索', + buttonAriaLabel: '検索' + }, + modal: { + searchBox: { + clearButtonTitle: '検索をクリア', + clearButtonAriaLabel: '検索をクリア', + closeButtonText: '閉じる', + closeButtonAriaLabel: '閉じる', + placeholderText: 'ドキュメントを検索', + placeholderTextAskAi: 'AI に質問: ', + placeholderTextAskAiStreaming: '回答を作成中...', + searchInputLabel: '検索', + backToKeywordSearchButtonText: 'キーワード検索に戻る', + backToKeywordSearchButtonAriaLabel: 'キーワード検索に戻る' + }, + startScreen: { + recentSearchesTitle: '検索履歴', + noRecentSearchesText: '最近の検索はありません', + saveRecentSearchButtonTitle: '検索履歴に保存', + removeRecentSearchButtonTitle: '検索履歴から削除', + favoriteSearchesTitle: 'お気に入り', + removeFavoriteSearchButtonTitle: 'お気に入りから削除', + recentConversationsTitle: '最近の会話', + removeRecentConversationButtonTitle: '会話履歴から削除' + }, + errorScreen: { + titleText: '結果を取得できません', + helpText: 'ネットワーク接続を確認してください' + }, + noResultsScreen: { + noResultsText: '結果が見つかりません', + suggestedQueryText: '別の検索語を試してください', + reportMissingResultsText: '結果があるはずだと思いますか?', + reportMissingResultsLinkText: 'フィードバックを送る' + }, + resultsScreen: { + askAiPlaceholder: 'AI に質問: ' + }, + askAiScreen: { + disclaimerText: + 'AI が生成した回答には誤りが含まれる可能性があります。必ずご確認ください。', + relatedSourcesText: '関連ソース', + thinkingText: '考え中...', + copyButtonText: 'コピー', + copyButtonCopiedText: 'コピーしました!', + copyButtonTitle: 'コピー', + likeButtonTitle: 'いいね', + dislikeButtonTitle: 'よくない', + thanksForFeedbackText: 'フィードバックありがとうございます!', + preToolCallText: '検索中...', + duringToolCallText: '検索中 ', + afterToolCallText: '検索完了', + aggregatedToolCallText: '検索完了' + }, + footer: { + selectText: '選択', + submitQuestionText: '質問を送信', + selectKeyAriaLabel: 'Enter キー', + navigateText: '移動', + navigateUpKeyAriaLabel: '上矢印キー', + navigateDownKeyAriaLabel: '下矢印キー', + closeText: '閉じる', + backToSearchText: '検索に戻る', + closeKeyAriaLabel: 'Esc キー', + poweredByText: '提供: ' + } + } + } + } +} diff --git a/docs/ja/guide/asset-handling.md b/docs/ja/guide/asset-handling.md new file mode 100644 index 000000000000..694318c49203 --- /dev/null +++ b/docs/ja/guide/asset-handling.md @@ -0,0 +1,66 @@ +# アセットの取り扱い {#asset-handling} + +## 静的アセットの参照 {#referencing-static-assets} + +すべての Markdown ファイルは Vue コンポーネントにコンパイルされ、[Vite](https://vitejs.dev/guide/assets.html) によって処理されます。Markdown 内では、相対 URL を使ってアセットを参照することが **推奨されます**。 + +```md +![画像](./image.png) +``` + +Markdown ファイル内、テーマの `*.vue` コンポーネント内、スタイルや通常の `.css` ファイル内でも、アセットはプロジェクトルートを基準とした絶対パス、またはファイルシステムを基準とした相対パスで参照できます。後者は Vite、Vue CLI、あるいは webpack の `file-loader` を使ったことがある場合に慣れ親しんだ挙動です。 + +一般的な画像、メディア、フォントファイルタイプは自動的にアセットとして検出され、含まれます。 + +::: tip リンクされたファイルはアセットとして扱われません +Markdown ファイル内のリンクで参照された PDF やその他のドキュメントは、自動的にアセットとして扱われません。これらのリンクファイルにアクセスできるようにするには、手動でプロジェクトの [`public`](#the-public-directory) ディレクトリに配置する必要があります。 +::: + +絶対パスを含むすべての参照されたアセットは、プロダクションビルド時にハッシュ化されたファイル名で出力ディレクトリにコピーされます。参照されないアセットはコピーされません。4kb 未満の画像アセットは base64 としてインライン化されます(これは [`vite`](../reference/site-config#vite) 設定オプションで変更可能です)。 + +すべての **静的な** パス参照(絶対パスを含む)は、作業ディレクトリの構造を基準にする必要があります。 + +## Public ディレクトリ {#the-public-directory} + +Markdown やテーマコンポーネントで直接参照されない静的アセットを提供する必要がある場合や、特定のファイルをオリジナルのファイル名のまま提供したい場合があります。 +例えば `robots.txt`、favicon、PWA 用アイコンなどです。 + +これらのファイルは [ソースディレクトリ](./routing#source-directory) 配下の `public` ディレクトリに配置できます。たとえばプロジェクトルートが `./docs` で、デフォルトのソースディレクトリを使用している場合、`public` ディレクトリは `./docs/public` になります。 + +`public` に配置されたアセットは、出力ディレクトリのルートにそのままコピーされます。 + +なお、`public` 内のファイルはルート絶対パスで参照する必要があります。例えば `public/icon.png` は常に `/icon.png` として参照しなければなりません。 + +## ベース URL {#base-url} + +サイトをルート以外の URL にデプロイする場合、`.vitepress/config.js` で `base` オプションを設定する必要があります。 +例えば `https://foo.github.io/bar/` にデプロイする場合、`base` は `'/bar/'` と設定します(必ずスラッシュで開始・終了する必要があります)。 + +すべての静的アセットパスは `base` 設定値に応じて自動的に調整されます。 +例えば Markdown 内で `public` 配下のアセットを絶対参照した場合: + +```md +![画像](/image-inside-public.png) +``` + +この場合は `base` の設定値を変更しても、参照を修正する必要はありません。 + +ただし、テーマコンポーネントで動的にアセットをリンクする場合(例:テーマ設定値に基づいた画像の `src`)は注意が必要です。 + +```vue + +``` + +この場合は、VitePress が提供する [`withBase` ヘルパー](../reference/runtime-api#withbase) でパスをラップすることを推奨します。 + +```vue + + + +``` diff --git a/docs/ja/guide/cms.md b/docs/ja/guide/cms.md new file mode 100644 index 000000000000..191312df249d --- /dev/null +++ b/docs/ja/guide/cms.md @@ -0,0 +1,56 @@ +--- +outline: deep +--- + +# CMS との接続 {#connecting-to-a-cms} + +## 全体のワークフロー {#general-workflow} + +VitePress を CMS と接続する際は、主に [動的ルーティング](./routing#dynamic-routes) を中心に考えることになります。先にその仕組みを理解しておいてください。 + +CMS ごとに動作が異なるため、ここでは各自の環境に合わせて調整できる汎用的なワークフローのみを示します。 + +1. CMS が認証を必要とする場合は、API トークンを格納するための `.env` を作成し、次のように読み込みます。 + + ```js + // posts/[id].paths.js + import { loadEnv } from 'vitepress' + + const env = loadEnv('', process.cwd()) + ``` + +2. CMS から必要なデータを取得し、適切なパスデータの形式に整形します。 + + ```js + export default { + async paths() { + // 必要に応じて各 CMS のクライアントライブラリを使用 + const data = await (await fetch('https://my-cms-api', { + headers: { + // 必要ならトークン + } + })).json() + + return data.map(entry => { + return { + params: { id: entry.id, /* title, authors, date など */ }, + content: entry.content + } + }) + } + } + ``` + +3. ページ内でコンテンツをレンダリングします。 + + ```md + # {{ $params.title }} + + - {{ $params.date }} に {{ $params.author }} が作成 + + + ``` + +## 連携ガイドの募集 {#integration-guides} + +特定の CMS と VitePress の連携ガイドを書かれた方は、下部の「Edit this page」リンクからぜひ投稿してください! diff --git a/docs/ja/guide/custom-theme.md b/docs/ja/guide/custom-theme.md new file mode 100644 index 000000000000..0095ca8a1cec --- /dev/null +++ b/docs/ja/guide/custom-theme.md @@ -0,0 +1,213 @@ +# カスタムテーマを使う {#using-a-custom-theme} + +## テーマの解決 {#theme-resolving} + +カスタムテーマを有効にするには、`.vitepress/theme/index.js` または `.vitepress/theme/index.ts` ファイル(「テーマエントリファイル」)を作成します。 + +``` +. +├─ docs # プロジェクトルート +│ ├─ .vitepress +│ │ ├─ theme +│ │ │ └─ index.js # テーマエントリ +│ │ └─ config.js # 設定ファイル +│ └─ index.md +└─ package.json +``` + +VitePress はテーマエントリファイルを検出すると、常にデフォルトテーマではなくカスタムテーマを使用します。ただし、[デフォルトテーマを拡張](./extending-default-theme) してその上で高度なカスタマイズを行うことも可能です。 + +## テーマインターフェース {#theme-interface} + +VitePress のカスタムテーマは次のインターフェースを持つオブジェクトとして定義されます。 + +```ts +interface Theme { +/** + * すべてのページに適用されるルートレイアウトコンポーネント + * @required + */ +Layout: Component +/** + * Vue アプリインスタンスを拡張 + * @optional + */ +enhanceApp?: (ctx: EnhanceAppContext) => Awaitable +/** + * 別のテーマを拡張し、そのテーマの `enhanceApp` を先に実行 + * @optional + */ +extends?: Theme +} + +interface EnhanceAppContext { +app: App // Vue アプリインスタンス +router: Router // VitePress のルーターインスタンス +siteData: Ref // サイト全体のメタデータ +} +``` + +テーマエントリファイルでは、このテーマをデフォルトエクスポートとして公開します。 + +```js [.vitepress/theme/index.js] + +// テーマエントリでは Vue ファイルを直接インポートできます +// VitePress は @vitejs/plugin-vue をあらかじめ設定済みです +import Layout from './Layout.vue' + +export default { +Layout, +enhanceApp({ app, router, siteData }) { + // ... +} +} +``` + +デフォルトエクスポートはカスタムテーマにおける唯一の契約であり、必須なのは `Layout` プロパティだけです。つまり、VitePress のテーマは単一の Vue コンポーネントでも成り立ちます。 + +レイアウトコンポーネントの内部は通常の Vite + Vue 3 アプリケーションと同じように動作します。なお、テーマは [SSR 対応](./ssr-compat) である必要があります。 + +## レイアウトの構築 {#building-a-layout} + +最も基本的なレイアウトコンポーネントには [``](../reference/runtime-api#content) コンポーネントを含める必要があります。 + +```vue [.vitepress/theme/Layout.vue] + +``` + +上記のレイアウトは、すべてのページの Markdown を単純に HTML として描画します。最初の改善点として 404 エラー処理を追加できます。 + +```vue{1-4,9-12} + + + +``` + +[`useData()`](../reference/runtime-api#usedata) ヘルパーを使うと、条件によってレイアウトを切り替えるために必要なすべてのランタイムデータを取得できます。アクセスできるデータのひとつにフロントマターがあります。これを利用すると、ページごとにレイアウトを制御できます。例えば、ユーザーが特別なホームページレイアウトを使いたい場合は以下のように記述します。 + + ```md +--- +layout: home +--- + ``` + +テーマ側を次のように調整します。 + +```vue{3,12-14} + + + +``` + +もちろんレイアウトをさらにコンポーネントに分割することもできます。 + +```vue{3-5,12-15} + + + +``` + +利用可能なすべての機能は [Runtime API リファレンス](../reference/runtime-api) を参照してください。さらに [ビルド時データ読み込み](./data-loading) を活用すれば、ブログ記事一覧ページのようなデータ駆動型のレイアウトも実現できます。 + +## カスタムテーマの配布 {#distributing-a-custom-theme} + +最も簡単な配布方法は [GitHub のテンプレートリポジトリ](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository) として提供することです。 + +npm パッケージとして配布する場合は、次の手順を踏みます。 + +1. パッケージエントリでテーマオブジェクトをデフォルトエクスポートとして公開する。 +2. 必要であればテーマ設定の型定義を `ThemeConfig` として公開する。 +3. テーマが VitePress 設定の調整を必要とする場合は、パッケージのサブパス(例:`my-theme/config`)としてその設定を公開し、ユーザーが拡張できるようにする。 +4. 設定ファイルやフロントマターを通じて、テーマ設定オプションを文書化する。 +5. テーマの利用方法を明確に説明する(以下を参照)。 + +## カスタムテーマの利用 {#consuming-a-custom-theme} + + +外部テーマを利用するには、カスタムテーマエントリからインポートして再エクスポートします。 + +```js [.vitepress/theme/index.js] +import Theme from 'awesome-vitepress-theme' + +export default Theme +``` + +テーマを拡張する必要がある場合: + +```js [.vitepress/theme/index.js] +import Theme from 'awesome-vitepress-theme' + +export default { +extends: Theme, +enhanceApp(ctx) { + // ... +} +} +``` + +テーマが特別な VitePress 設定を必要とする場合は、設定ファイルも拡張する必要があります。 + +```ts [.vitepress/config.ts] +import baseConfig from 'awesome-vitepress-theme/config' + +export default { +// 必要に応じてテーマの基本設定を拡張 +extends: baseConfig +} +``` + +テーマがテーマ設定用の型を提供している場合: + +```ts [.vitepress/config.ts] +import baseConfig from 'awesome-vitepress-theme/config' +import { defineConfigWithTheme } from 'vitepress' +import type { ThemeConfig } from 'awesome-vitepress-theme' + +export default defineConfigWithTheme({ +extends: baseConfig, +themeConfig: { + // 型は `ThemeConfig` +} +}) +``` diff --git a/docs/ja/guide/data-loading.md b/docs/ja/guide/data-loading.md new file mode 100644 index 000000000000..469999d72469 --- /dev/null +++ b/docs/ja/guide/data-loading.md @@ -0,0 +1,212 @@ +# ビルド時のデータの読み込み {#build-time-data-loading} + +VitePress には **データローダー (data loaders)** という機能があり、任意のデータを読み込み、ページやコンポーネントからインポートすることができます。データの読み込みは **ビルド時のみ** 実行され、最終的な JavaScript バンドルには JSON としてシリアライズされたデータが含まれます。 + +データローダーはリモートデータの取得や、ローカルファイルに基づいたメタデータの生成に利用できます。たとえば、ローカルの API ページをすべて解析して API エントリのインデックスを自動生成するといったことが可能です。 + +## 基本的な使い方 {#basic-usage} + +データローダーファイルは `.data.js` または `.data.ts` で終わる必要があります。ファイルは `load()` メソッドを持つオブジェクトをデフォルトエクスポートします。 + +```js [example.data.js] +export default { +load() { + return { + hello: 'world' + } +} +} +``` + +ローダーモジュールは Node.js 上でのみ評価されるため、Node API や npm 依存関係を自由に利用できます。 + +その後、このファイルから `.md` ページや `.vue` コンポーネントで `data` という名前のエクスポートを使ってデータをインポートできます。 + +```vue + + +
{{ data }}
+``` + +出力: + +```json +{ + "hello": "world" +} +``` + +データローダー自体は `data` を直接エクスポートしていないことに気づくでしょう。これは VitePress が裏側で `load()` を呼び出し、その結果を暗黙的に `data` として公開しているためです。 + +ローダーが非同期でも動作します。 + +```js +export default { + async load() { + // リモートデータを取得 + return (await fetch('...')).json() + } +} +``` + +## ローカルファイルからのデータ {#data-from-local-files} + +ローカルファイルに基づいたデータを生成する必要がある場合は、データローダー内で `watch` オプションを使用し、ファイルの変更をホットリロードに反映させることが推奨されます。 + +`watch` では [glob パターン](https://github.com/mrmlnc/fast-glob#pattern-syntax) を利用して複数ファイルをマッチさせることができ、パターンはローダーファイルからの相対パスで指定できます。`load()` 関数にはマッチしたファイルの絶対パスが渡されます。 + +以下は CSV ファイルを読み込み [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/) を使って JSON に変換する例です。このコードはビルド時にのみ実行されるため、CSV パーサーがクライアントに送られることはありません。 + +```js +import fs from 'node:fs' +import { parse } from 'csv-parse/sync' + +export default { + watch: ['./data/*.csv'], + load(watchedFiles) { + return watchedFiles.map((file) => { + return parse(fs.readFileSync(file, 'utf-8'), { + columns: true, + skip_empty_lines: true + }) + }) + } +} +``` + +## `createContentLoader` + +コンテンツ中心のサイトを構築する場合、ブログ記事や API ページなどを一覧表示する「アーカイブ」や「インデックス」ページが必要になることがよくあります。これはデータローダー API を使って直接実装できますが、あまりにも一般的なケースなので VitePress では `createContentLoader` というヘルパーが用意されています。 + +```js [posts.data.js] +import { createContentLoader } from 'vitepress' + +export default createContentLoader('posts/*.md', /* options */) +``` + +このヘルパーは [ソースディレクトリ](./routing#source-directory) からの相対 glob パターンを受け取り、`{ watch, load }` を返すデータローダーオブジェクトを生成します。これをデータローダーファイルのデフォルトエクスポートにできます。開発時のパフォーマンスを向上させるために、ファイルの更新時刻に基づくキャッシュも行われます。 + +このローダーは Markdown ファイルにのみ対応し、それ以外のファイルは無視されます。 + +読み込まれるデータは `ContentData[]` 型の配列です。 + +```ts +interface ContentData { + url: string // ページのマッピング URL(例: /posts/hello.html) + frontmatter: Record // ページのフロントマター + + src: string | undefined + html: string | undefined + excerpt: string | undefined +} +``` + +デフォルトでは `url` と `frontmatter` のみが提供されます。これは読み込まれたデータがクライアントバンドルに JSON としてインライン化されるため、サイズに注意する必要があるためです。 + +以下はデータを使って最小限のブログインデックスページを構築する例です。 + +```vue + + + +``` + +### オプション {#options} + +デフォルトデータが要件に合わない場合は、オプションで変換処理を追加できます。 + +```js [posts.data.js] +import { createContentLoader } from 'vitepress' + +export default createContentLoader('posts/*.md', { + includeSrc: true, // 生の markdown ソースを含める? + render: true, // レンダリングされた HTML を含める? + excerpt: true, // 抜粋を含める? + + transform(rawData) { + return rawData + .sort((a, b) => { + return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date) + }) + .map((page) => { + page.src // 生の markdown ソース + page.html // レンダリングされた HTML + page.excerpt // 抜粋 HTML(最初の `---` までの内容) + return {/* ... */} + }) + } +}) +``` + +[Vue.js ブログ](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts) での使用例も参考になります。 + +`createContentLoader` API は [ビルドフック](../reference/site-config#build-hooks) 内でも利用可能です。 + +```js [.vitepress/config.js] +export default { + async buildEnd() { + const posts = await createContentLoader('posts/*.md').load() + // メタデータを基にファイルを生成(例: RSS フィード) + } +} +``` + +**型定義** + +```ts +interface ContentOptions { + includeSrc?: boolean + render?: boolean + excerpt?: + | boolean + | ((file: { data: { [key: string]: any }; content: string; excerpt?: string }, options?: any) => void) + | string + transform?: (data: ContentData[]) => T | Promise +} +``` + +## 型付きデータローダー {#typed-data-loaders} + + +TypeScript を使用する場合は、ローダーと `data` エクスポートを型付けできます。 + +```ts +import { defineLoader } from 'vitepress' + +export interface Data { + // データ型 +} + +declare const data: Data +export { data } + +export default defineLoader({ + watch: ['...'], + async load(): Promise { + // ... + } +}) +``` + +## 設定情報の取得 {#configuration} + + +ローダー内で設定情報を取得するには次のようにします。 + +```ts +import type { SiteConfig } from 'vitepress' + +const config: SiteConfig = (globalThis as any).VITEPRESS_CONFIG +``` diff --git a/docs/ja/guide/deploy.md b/docs/ja/guide/deploy.md new file mode 100644 index 000000000000..38029e9cebe0 --- /dev/null +++ b/docs/ja/guide/deploy.md @@ -0,0 +1,348 @@ +--- +outline: deep +--- + +# VitePress サイトをデプロイする {#deploy-your-vitepress-site} + + +以下のガイドは、次の前提に基づいています。 + +- VitePress のサイトはプロジェクトの `docs` ディレクトリ内にある。 +- デフォルトのビルド出力ディレクトリ(`.vitepress/dist`)を使用している。 +- VitePress はプロジェクトのローカル依存としてインストールされており、`package.json` に次のスクリプトが設定されている。 + +```json [package.json] + { + "scripts": { + "docs:build": "vitepress build docs", + "docs:preview": "vitepress preview docs" + } + } +``` + +## ローカルでビルドしてテストする {#build-and-test-locally} + + +1. 次のコマンドでドキュメントをビルドします。 + + ```sh + $ npm run docs:build + ``` + +2. ビルド後、次のコマンドでローカルプレビューします。 + + ```sh + $ npm run docs:preview + ``` + + `preview` コマンドはローカルの静的 Web サーバーを起動し、出力ディレクトリ `.vitepress/dist` を `http://localhost:4173` で配信します。プロダクションへプッシュする前に見た目を確認できます。 + +3. `--port` 引数でサーバーのポートを設定できます。 + + ```json + { + "scripts": { + "docs:preview": "vitepress preview docs --port 8080" + } + } + ``` + + これで `docs:preview` は `http://localhost:8080` でサーバーを起動します。 + +## 公開ベースパスの設定 {#setting-a-public-base-path} + + +デフォルトでは、サイトはドメインのルートパス(`/`)にデプロイされることを想定しています。サイトをサブパス、例:`https://mywebsite.com/blog/` で配信する場合は、VitePress の設定で [`base`](../reference/site-config#base) オプションを `'/blog/'` に設定してください。 + +**例:** GitHub(または GitLab)Pages に `user.github.io/repo/` としてデプロイするなら、`base` を `/repo/` に設定します。 + +## HTTP キャッシュヘッダー {#http-cache-headers} + + +本番サーバーの HTTP ヘッダーを制御できる場合は、`cache-control` ヘッダーを設定して、再訪時のパフォーマンスを向上させましょう。 + +本番ビルドでは静的アセット(JavaScript、CSS、`public` 以外のインポートアセット)にハッシュ付きファイル名が使用されます。ブラウザの開発者ツールのネットワークタブで本番プレビューを確認すると、`app.4f283b18.js` のようなファイルが見られます。 + +この `4f283b18` ハッシュはファイル内容から生成されます。同じハッシュの URL は同じ内容を必ず返し、内容が変われば URL も変わります。したがって、これらのファイルには最も強いキャッシュヘッダーを安全に適用できます。これらのファイルは出力ディレクトリ内の `assets/` 配下に配置されるため、次のヘッダーを設定できます。 + +``` +Cache-Control: max-age=31536000,immutable +``` + +::: details Netlify の `_headers` ファイル例 + +``` +/assets/* + cache-control: max-age=31536000 + cache-control: immutable +``` + +注:`_headers` ファイルは [public ディレクトリ](./asset-handling#the-public-directory) に配置します(この例では `docs/public/_headers`)。そうすると、ビルド出力にそのままコピーされます。 + +[Netlify のカスタムヘッダードキュメント](https://docs.netlify.com/routing/headers/) + +::: + +::: details `vercel.json` による Vercel 設定例 + +```json + { + "headers": [ + { + "source": "/assets/(.*)", + "headers": [ + { + "key": "Cache-Control", + "value": "max-age=31536000, immutable" + } + ] + } + ] + } +``` + +注:`vercel.json` は **リポジトリのルート** に配置してください。 + +[Vercel のヘッダー設定ドキュメント](https://vercel.com/docs/concepts/projects/project-configuration#headers) + +::: + +## プラットフォーム別ガイド {#platform-guides} + + +### Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render {#netlify-vercel-cloudflare-pages-aws-amplify-render} + +新しいプロジェクトを作成し、ダッシュボードで次の設定に変更します。 + +- **Build Command:** `npm run docs:build` +- **Output Directory:** `docs/.vitepress/dist` +- **Node Version:** `20`(以上) + +::: warning +HTML の _Auto Minify_ のようなオプションを有効にしないでください。Vue にとって意味のあるコメントが出力から削除され、削除されるとハイドレーションの不整合エラーが発生する可能性があります。 +::: + +### GitHub Pages {#github-pages} + +1. プロジェクトの `.github/workflows` ディレクトリに `deploy.yml` を作成し、以下の内容を記述します。 + + ```yaml [.github/workflows/deploy.yml] + # Sample workflow for building and deploying a VitePress site to GitHub Pages + # + name: Deploy VitePress site to Pages + + on: + # Runs on pushes targeting the `main` branch. Change this to `master` if you're + # using the `master` branch as the default branch. + push: + branches: [main] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + + # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages + permissions: + contents: read + pages: write + id-token: write + + # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. + # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. + concurrency: + group: pages + cancel-in-progress: false + + jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Not needed if lastUpdated is not enabled + # - uses: pnpm/action-setup@v3 # Uncomment this block if you're using pnpm + # with: + # version: 9 # Not needed if you've set "packageManager" in package.json + # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm # or pnpm / yarn + - name: Setup Pages + uses: actions/configure-pages@v4 + - name: Install dependencies + run: npm ci # or pnpm install / yarn install / bun install + - name: Build with VitePress + run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/.vitepress/dist + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + runs-on: ubuntu-latest + name: Deploy + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + ``` + + ::: warning + VitePress の `base` オプションが正しく設定されていることを確認してください。詳細は [公開ベースパスの設定](#公開ベースパスの設定) を参照してください。 + ::: + +2. リポジトリ設定の「Pages」メニューで、「Build and deployment > Source」を「GitHub Actions」に設定します。 + +3. 変更を `main` ブランチにプッシュし、GitHub Actions の完了を待ちます。設定に応じて、サイトは `https://.github.io/[repository]/` または `https:///` にデプロイされます。以後、`main` へのプッシュごとに自動デプロイされます。 + +### GitLab Pages {#gitlab-pages} + +1. VitePress の設定で `outDir` を `../public` に設定します。`https://.gitlab.io//` にデプロイする場合は `base` を `'//'` に設定します。カスタムドメイン、ユーザー/グループページ、または GitLab の「Use unique domain」を有効にしている場合は `base` は不要です。 + +2. プロジェクトのルートに `.gitlab-ci.yml` を作成して、以下を追加します。これにより、コンテンツを更新するたびにサイトがビルド・デプロイされます。 + + ```yaml [.gitlab-ci.yml] + image: node:18 + pages: + cache: + paths: + - node_modules/ + script: + # - apk add git # Uncomment this if you're using small docker images like alpine and have lastUpdated enabled + - npm install + - npm run docs:build + artifacts: + paths: + - public + only: + - main + ``` + +### Azure Static Web Apps {#azure-static-web-apps} + +1. [公式ドキュメント](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration) に従います。 + +2. 設定ファイルで次の値を指定します(`api_location` のように不要なものは削除)。 + + - **`app_location`**: `/` + - **`output_location`**: `docs/.vitepress/dist` + - **`app_build_command`**: `npm run docs:build` + +### Firebase {#firebase} + +1. プロジェクトのルートに `firebase.json` と `.firebaserc` を作成します。 + + `firebase.json`: + + ```json [firebase.json] + { + "hosting": { + "public": "docs/.vitepress/dist", + "ignore": [] + } + } + ``` + + `.firebaserc`: + + ```json [.firebaserc] + { + "projects": { + "default": "" + } + } + ``` + +2. `npm run docs:build` の後、次のコマンドでデプロイします。 + + ```sh + firebase deploy + ``` + +### Surge {#surge} + +1. `npm run docs:build` の後、次のコマンドでデプロイします。 + + ```sh + npx surge docs/.vitepress/dist + ``` + +### Heroku {#heroku} + +1. [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static) のドキュメントとガイドに従います。 + +2. プロジェクトのルートに `static.json` を作成し、以下を記述します。 + + ```json [static.json] + { + "root": "docs/.vitepress/dist" + } + ``` + +### Edgio {#edgio} + +[Creating and Deploying a VitePress App To Edgio](https://docs.edg.io/guides/vitepress) を参照してください。 + +### Kinsta Static Site Hosting {#kinsta-static-site-hosting} + +[VitePress](https://kinsta.com/static-site-hosting/) を [こちらの手順](https://kinsta.com/docs/vitepress-static-site-example/) に従ってデプロイできます。 + +### Stormkit {#stormkit} + +[VitePress プロジェクトを Stormkit にデプロイ](https://stormkit.io/blog/how-to-deploy-vitepress) する手順を参照してください。 + +### CloudRay {#cloudray} + +[CloudRay](https://cloudray.io/) でのデプロイ方法は [こちらの手順](https://cloudray.io/articles/how-to-deploy-vitepress-site) を参照してください。 + +### Nginx {#nginx} + +以下は Nginx サーバーブロックの設定例です。一般的なテキスト系アセットの gzip 圧縮、VitePress サイトの静的ファイル配信における適切なキャッシュヘッダー、そして `cleanUrls: true` のハンドリングを含みます。 + +```nginx +server { + gzip on; + gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript; + + listen 80; + server_name _; + index index.html; + + location / { + # content location + root /app; + + # exact matches -> reverse clean urls -> folders -> not found + try_files $uri $uri.html $uri/ =404; + + # non existent pages + error_page 404 /404.html; + + # a folder without index.html raises 403 in this setup + error_page 403 /404.html; + + # adjust caching headers + # files in the assets folder have hashes filenames + location ~* ^/assets/ { + expires 1y; + add_header Cache-Control "public, immutable"; + } + } +} +``` + +この設定は、ビルド済みの VitePress サイトがサーバー上の `/app` ディレクトリに配置されていることを想定しています。サイトのファイルが別の場所にある場合は、`root` ディレクティブを適宜変更してください。 + +::: warning index.html をデフォルトにしない +`try_files` の解決先を、他の Vue アプリのように index.html にフォールバックさせないでください。不正なページ状態になります。 +::: + +詳細は [公式 nginx ドキュメント](https://nginx.org/en/docs/)、Issue [#2837](https://github.com/vuejs/vitepress/discussions/2837)、[#3235](https://github.com/vuejs/vitepress/issues/3235)、および Mehdi Merah 氏の [ブログ記事](https://blog.mehdi.cc/articles/vitepress-cleanurls-on-nginx-environment#readings) を参照してください。 diff --git a/docs/ja/guide/extending-default-theme.md b/docs/ja/guide/extending-default-theme.md new file mode 100644 index 000000000000..6047ac916d3a --- /dev/null +++ b/docs/ja/guide/extending-default-theme.md @@ -0,0 +1,332 @@ +--- +outline: deep +--- + +# デフォルトテーマの拡張 {#extending-the-default-theme} + +VitePress のデフォルトテーマはドキュメント向けに最適化されており、カスタマイズ可能です。利用できるオプションの一覧は [デフォルトテーマの概要](../reference/default-theme-config) を参照してください。 + +しかし、設定だけでは不十分なケースもあります。例えば: + +1. CSS のスタイルを微調整したい +2. グローバルコンポーネントの登録など、Vue アプリインスタンスを変更したい +3. レイアウトのスロット経由でテーマに独自コンテンツを挿入したい + +これらの高度なカスタマイズには、デフォルトテーマを「拡張」するカスタムテーマを使用する必要があります。 + +::: tip +先に [カスタムテーマの使用](./custom-theme) を読み、カスタムテーマの仕組みを理解してから進めてください。 +::: + +## CSS のカスタマイズ {#customizing-css} + +デフォルトテーマの CSS は、ルートレベルの CSS 変数をオーバーライドすることでカスタマイズできます。 + +```js [.vitepress/theme/index.js] +import DefaultTheme from 'vitepress/theme' +import './custom.css' + +export default DefaultTheme +``` + +```css +/* .vitepress/theme/custom.css */ +:root { + --vp-c-brand-1: #646cff; + --vp-c-brand-2: #747bff; +} +``` + +上書き可能な [デフォルトテーマの CSS 変数](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) を参照してください。 + +## フォントを変更する {#using-different-fonts} + +VitePress はデフォルトフォントとして [Inter](https://rsms.me/inter/) を使用し、ビルド出力にフォントを含めます。プロダクションでは自動でプリロードもされます。しかし、別のメインフォントを使いたい場合には望ましくないことがあります。 + +Inter をビルド出力に含めたくない場合は、`vitepress/theme-without-fonts` からテーマをインポートします。 + +```js [.vitepress/theme/index.js] +import DefaultTheme from 'vitepress/theme-without-fonts' +import './my-fonts.css' + +export default DefaultTheme +``` + +```css +/* .vitepress/theme/my-fonts.css */ +:root { + --vp-font-family-base: /* 通常テキスト用フォント */ + --vp-font-family-mono: /* コード用フォント */ +} +``` + +::: warning +[Team Page](../reference/default-theme-team-page) などのオプションコンポーネントを使う場合も、必ず `vitepress/theme-without-fonts` からインポートしてください。 +::: + +フォントが `@font-face` で参照されるローカルファイルの場合、アセットとして処理され、ハッシュ付きファイル名で `.vitepress/dist/assets` に出力されます。このファイルをプリロードするには、[transformHead](../reference/site-config#transformhead) ビルドフックを使います。 + +```js [.vitepress/config.js] +export default { + transformHead({ assets }) { + // 使うフォントに合わせて正規表現を調整 + const myFontFile = assets.find(file => /font-name\.[\w-]+\.woff2/.test(file)) + if (myFontFile) { + return [ + [ + 'link', + { + rel: 'preload', + href: myFontFile, + as: 'font', + type: 'font/woff2', + crossorigin: '' + } + ] + ] + } + } +} +``` + +## グローバルコンポーネントの登録 {#registering-global-components} + +```js [.vitepress/theme/index.js] +import DefaultTheme from 'vitepress/theme' + +/** @type {import('vitepress').Theme} */ +export default { + extends: DefaultTheme, + enhanceApp({ app }) { + // 独自のグローバルコンポーネントを登録 + app.component('MyGlobalComponent' /* ... */) + } +} +``` + +TypeScript を使う場合: + +```ts [.vitepress/theme/index.ts] +import type { Theme } from 'vitepress' +import DefaultTheme from 'vitepress/theme' + +export default { + extends: DefaultTheme, + enhanceApp({ app }) { + // 独自のグローバルコンポーネントを登録 + app.component('MyGlobalComponent' /* ... */) + } +} satisfies Theme +``` + +Vite を使っているため、Vite の [glob import 機能](https://vitejs.dev/guide/features.html#glob-import) を利用してディレクトリ内のコンポーネントを自動登録することもできます。 + +## レイアウトスロット {#layout-slots} + +デフォルトテーマの `` コンポーネントには、ページ内の特定の位置にコンテンツを挿入するためのスロットがいくつか用意されています。以下は、アウトラインの前にコンポーネントを挿入する例です。 + +```js [.vitepress/theme/index.js] +import DefaultTheme from 'vitepress/theme' +import MyLayout from './MyLayout.vue' + +export default { + extends: DefaultTheme, + // スロットを注入するラッパーコンポーネントで Layout を上書き + Layout: MyLayout +} +``` + +```vue [.vitepress/theme/MyLayout.vue] + + + +``` + +レンダーファンクションを使う方法もあります。 + +```js [.vitepress/theme/index.js] +import { h } from 'vue' +import DefaultTheme from 'vitepress/theme' +import MyComponent from './MyComponent.vue' + +export default { + extends: DefaultTheme, + Layout() { + return h(DefaultTheme.Layout, null, { + 'aside-outline-before': () => h(MyComponent) + }) + } +} +``` + +デフォルトテーマレイアウトで利用可能なスロットの一覧: + +- フロントマターで `layout: 'doc'`(デフォルト)を有効にしているとき: + - `doc-top` + - `doc-bottom` + - `doc-footer-before` + - `doc-before` + - `doc-after` + - `sidebar-nav-before` + - `sidebar-nav-after` + - `aside-top` + - `aside-bottom` + - `aside-outline-before` + - `aside-outline-after` + - `aside-ads-before` + - `aside-ads-after` +- フロントマターで `layout: 'home'` を有効にしているとき: + - `home-hero-before` + - `home-hero-info-before` + - `home-hero-info` + - `home-hero-info-after` + - `home-hero-actions-after` + - `home-hero-image` + - `home-hero-after` + - `home-features-before` + - `home-features-after` +- フロントマターで `layout: 'page'` を有効にしているとき: + - `page-top` + - `page-bottom` +- 404(Not Found)ページ: + - `not-found` +- 常に利用可能: + - `layout-top` + - `layout-bottom` + - `nav-bar-title-before` + - `nav-bar-title-after` + - `nav-bar-content-before` + - `nav-bar-content-after` + - `nav-screen-content-before` + - `nav-screen-content-after` + +## View Transitions API の利用 + +### 外観切り替え時(ライト/ダーク) {#on-appearance-toggle} + +カラーモード切り替え時にカスタムトランジションを提供するよう、デフォルトテーマを拡張できます。例: + +```vue [.vitepress/theme/Layout.vue] + + + + + +``` + +結果(**注意!**:点滅や急な動き、明るい光を含みます): + +
+デモ + +![Appearance Toggle Transition Demo](/appearance-toggle-transition.webp) + +
+ +詳細は [Chrome Docs](https://developer.chrome.com/docs/web-platform/view-transitions/) を参照してください。 + +### ルート遷移時 {#on-route-change} + +近日公開。 + +## 内部コンポーネントの置き換え {#overriding-internal-components} + +Vite の [エイリアス](https://vitejs.dev/config/shared-options.html#resolve-alias) を使って、デフォルトテーマのコンポーネントを独自のものに置き換えられます。 + +```ts +import { fileURLToPath, URL } from 'node:url' +import { defineConfig } from 'vitepress' + +export default defineConfig({ + vite: { + resolve: { + alias: [ + { + find: /^.*\/VPNavBar\.vue$/, + replacement: fileURLToPath( + new URL('./theme/components/CustomNavBar.vue', import.meta.url) + ) + } + ] + } + } +}) +``` + +正確なコンポーネント名は [ソースコード](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default/components) を参照してください。内部コンポーネントであるため、マイナーリリース間で名称が更新される可能性があります。 diff --git a/docs/ja/guide/frontmatter.md b/docs/ja/guide/frontmatter.md new file mode 100644 index 000000000000..0c5ddcb583d4 --- /dev/null +++ b/docs/ja/guide/frontmatter.md @@ -0,0 +1,48 @@ +# フロントマター {#frontmatter} + +## 使い方 {#usage} + +VitePress はすべての Markdown ファイルで YAML フロントマターをサポートしており、[gray-matter](https://github.com/jonschlinkert/gray-matter) で解析します。フロントマターは Markdown ファイルの先頭(` + + +``` + +## RTL サポート(実験的){#rtl-support-experimental} + +RTL をサポートするには、設定で `dir: 'rtl'` を指定し、、または のような RTLCSS 系の PostCSS プラグインを使用してください。CSS の詳細度の問題を避けるため、PostCSS プラグインでは `:where([dir="ltr"])` と `:where([dir="rtl"])` を接頭辞として使うよう設定してください。 diff --git a/docs/ja/guide/markdown.md b/docs/ja/guide/markdown.md new file mode 100644 index 000000000000..966ce72c8d2c --- /dev/null +++ b/docs/ja/guide/markdown.md @@ -0,0 +1,1040 @@ +# Markdown 拡張 {#markdown-extensions} + +VitePress には組み込みの Markdown 拡張機能が用意されています。 + +## 見出しアンカー {#header-anchors} + +見出しには自動的にアンカーリンクが付与されます。アンカーのレンダリングは `markdown.anchor` オプションで設定できます。 + +### カスタムアンカー {#custom-anchors} + +自動生成ではなく任意のアンカーを指定したい場合は、見出しの末尾にサフィックスを追加します。 + + ```md + # カスタムアンカーを使う {#my-anchor} + ``` + +これにより、デフォルトの `#using-custom-anchors` ではなく `#my-anchor` でその見出しにリンクできます。 + +## リンク {#links} + +内部リンクと外部リンクは特別に処理されます。 + +### 内部リンク {#internal-links} + +内部リンクは SPA ナビゲーションのためにルーターリンクへ変換されます。また、各サブディレクトリにある `index.md` は自動的に `index.html` に変換され、URL は対応する `/` になります。 + +次のようなディレクトリ構成があるとします。 + + ``` + . + ├─ index.md + ├─ foo + │ ├─ index.md + │ ├─ one.md + │ └─ two.md + └─ bar + ├─ index.md + ├─ three.md + └─ four.md + ``` + +そして、現在編集中のファイルが `foo/one.md` の場合: + + ```md + [Home](/) + [foo](/foo/) + [foo の見出し](./#heading) + [bar - three](../bar/three) + [bar - three](../bar/three.md) + [bar - four](../bar/four.html) + ``` + +### ページサフィックス {#page-suffix} + +ページと内部リンクはデフォルトで `.html` サフィックス付きで生成されます。 + +### 外部リンク {#external-links} + +外部リンクには自動的に `target="_blank" rel="noreferrer"` が付与されます。 + +- [vuejs.org](https://vuejs.org) +- [VitePress on GitHub](https://github.com/vuejs/vitepress) + +## フロントマター {#frontmatter} + +[YAML フロントマター](https://jekyllrb.com/docs/front-matter/) をそのままサポートしています。 + + ```yaml + --- + title: ハッカーのようにブログを書く + lang: ja-JP + --- + ``` + +このデータはページ内や、カスタム/テーマコンポーネントからも利用できます。詳しくは [Frontmatter](../reference/frontmatter-config) を参照してください。 + +## GitHub 風テーブル {#github-style-tables} + +**入力** + + ```md + | テーブル | は | クール | + | -------------- | :---------: | ------: | + | 3列目は | 右寄せ | $1600 | + | 2列目は | 中央 | $12 | + | シマ模様 | neat です | $1 | + ``` + +**出力** + +| テーブル | は | クール | +| -------- | :----: | ------: | +| 3列目は | 右寄せ | \$1600 | +| 2列目は | 中央 | \$12 | +| シマ模様 | neatです | \$1 | + +## 絵文字 :tada: {#emoji} + +**入力** + + ``` + :tada: :100: + ``` + +**出力** + +:tada: :100: + +すべての絵文字の [一覧はこちら](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs)。 + +## 目次 {#table-of-contents} + +**入力** + + ``` + [[toc]] + ``` + +**出力** + +[[toc]] + +TOC のレンダリングは `markdown.toc` オプションで設定できます。 + +## カスタムコンテナ {#custom-containers} + +タイプ、タイトル、内容を指定してカスタムコンテナを定義できます。 + +### デフォルトタイトル {#default-title} + +**入力** + + ```md + ::: info + これは情報ボックスです。 + ::: + + ::: tip + これはヒントです。 + ::: + + ::: warning + これは警告です。 + ::: + + ::: danger + これは危険の警告です。 + ::: + + ::: details + これは詳細ブロックです。 + ::: + ``` + +**出力** + +::: info +これは情報ボックスです。 +::: + +::: tip +これはヒントです。 +::: + +::: warning +これは警告です。 +::: + +::: danger +これは危険の警告です。 +::: + +::: details +これは詳細ブロックです。 +::: + +### カスタムタイトル {#custom-title} + +コンテナの「タイプ」の直後に文字列を追加することで、タイトルをカスタマイズできます。 + +**入力** + + ````md + ::: danger 停止 + 危険地帯。先に進まないでください。 + ::: + + ::: details クリックしてコードを表示/非表示 + ```js + console.log('こんにちは、VitePress!') + ``` + ::: + ```` + +**出力** + +::: danger 停止 +危険地帯。先に進まないでください。 +::: + +::: details クリックしてコードを表示/非表示 + ```js + console.log('こんにちは、VitePress!') + ``` +::: + +また、英語以外で執筆する場合などは、サイト設定に以下を追加してタイトル文字列をグローバルに上書きできます。 + + ```ts + // config.ts + export default defineConfig({ + // ... + markdown: { + container: { + tipLabel: 'ヒント', + warningLabel: '警告', + dangerLabel: '危険', + infoLabel: '情報', + detailsLabel: '詳細' + } + } + // ... + }) + ``` + +### 追加属性 {#additional-attributes} + +カスタムコンテナには追加の属性を付与できます。この機能には [markdown-it-attrs](https://github.com/arve0/markdown-it-attrs) を使用しており、ほぼすべての Markdown 要素でサポートされます。たとえば `open` 属性を付けると、details ブロックをデフォルトで開いた状態にできます。 + +**入力** + + ````md + ::: details クリックしてコードを表示/非表示 {open} + ```js + console.log('こんにちは、VitePress!') + ``` + ::: + ```` + +**出力** + +::: details クリックしてコードを表示/非表示 {open} + ```js + console.log('こんにちは、VitePress!') + ``` +::: + +### `raw` + +これは、VitePress でのスタイルやルーターの衝突を防ぐための特別なコンテナです。コンポーネントライブラリのドキュメント化に特に有用です。より強力な分離が必要であれば、[whyframe](https://whyframe.dev/docs/integrations/vitepress) も検討してください。 + +**構文** + + ```md + ::: raw + Wraps in a `
` + ::: + ``` + +`vp-raw` クラスは要素に直接付与することも可能です。スタイルの分離は現在オプトインです。 + +- お好みのパッケージマネージャで `postcss` をインストールします: + + ```sh + $ npm add -D postcss + ``` + +- `docs/postcss.config.mjs` を作成し、次を追加します: + + ```js + import { postcssIsolateStyles } from 'vitepress' + + export default { + plugins: [postcssIsolateStyles()] + } + ``` + + オプションは次のように渡せます: + + ```js + postcssIsolateStyles({ + includeFiles: [/custom\.css/] // 既定は [/vp-doc\.css/, /base\.css/] + }) + ``` + +## GitHub 形式のアラート {#github-flavored-alerts} + +VitePress は [GitHub 形式のアラート](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) をコールアウトとしてレンダリングできます。表示は [カスタムコンテナ](#custom-containers) と同様です。 + +**入力** + + + ```md + > [!NOTE] + > 流し読みでも目に留めてほしい情報を強調します。 + + > [!TIP] + > 成功の手助けとなる任意の情報です。 + + > [!IMPORTANT] + > 成功に必須の重要情報です。 + + > [!WARNING] + > 危険性があるため即時の注意が必要な重要情報です。 + + > [!CAUTION] + > 行動による望ましくない結果の可能性です。 + +``` + +**出力** + + + > [!NOTE] + > 流し読みでも目に留めてほしい情報を強調します。 + + > [!TIP] + > 成功の手助けとなる任意の情報です。 + + > [!IMPORTANT] + > 成功に必須の重要情報です。 + + > [!WARNING] + > 危険性があるため即時の注意が必要な重要情報です。 + + > [!CAUTION] + > 行動による望ましくない結果の可能性です。 + + +## コードブロックのシンタックスハイライト {#syntax-highlighting-in-code-blocks} + +VitePress は [Shiki](https://github.com/shikijs/shiki) を使って、Markdown のコードブロックに色付きのシンタックスハイライトを適用します。Shiki は多くのプログラミング言語をサポートしています。コードブロックの先頭のバッククォートに有効な言語エイリアスを付けるだけで利用できます。 + +**入力** + + ```` + ```js + export default { + name: 'MyComponent', + // ... + } + ``` +```` + ```` + ```html +
    +
  • + {{ todo.text }} +
  • +
+ ``` + ```` + +**出力** + + ```js + export default { + name: 'MyComponent', + // ... + } + ``` + ```html +
    +
  • + {{ todo.text }} +
  • +
+ ``` + +有効な言語の [一覧](https://shiki.style/languages) は Shiki のリポジトリで確認できます。 + +また、シンタックスハイライトのテーマ変更、言語エイリアスの設定、言語ラベルのカスタマイズなどはアプリ設定の [`markdown` オプション](../reference/site-config#markdown) で行えます。 + +## コードブロックの行ハイライト {#line-highlighting-in-code-blocks} + +**入力** + + ```` + ```js{4} + export default { + data () { + return { + msg: 'ハイライト!' + } + } + } + ``` + ```` + +**出力** + + ```js{4} + export default { + data () { + return { + msg: 'ハイライト!' + } + } + } + ``` + +単一行だけでなく、複数の単一行や範囲、あるいはその組み合わせも指定できます: + +- 行範囲の例: `{5-8}`, `{3-10}`, `{10-17}` +- 複数の単一行: `{4,7,9}` +- 行範囲+単一行: `{4,7-13,16,23-27,40}` + +**入力** + + ```` + ```js{1,4,6-8} + export default { // Highlighted + data () { + return { + msg: `Highlighted! + This line isn't highlighted, + but this and the next 2 are.`, + motd: 'VitePress is awesome', + lorem: 'ipsum' + } + } + } + ``` + ```` + +**出力** + + + ```js{1,4,6-8} + export default { // Highlighted + data () { + return { + msg: `Highlighted! + This line isn't highlighted, + but this and the next 2 are.`, + motd: 'VitePress is awesome', + lorem: 'ipsum' + } + } + } + ``` + +代替案として、`// [!code highlight]` コメントを使って行内を直接ハイライトできます。 + +**入力** + + ``` + ```js + export default { + data () { + return { + msg: 'ハイライト!' // [!code highlight] + } + } + } + ``` + +**出力** + + + ```js + export default { + data () { + return { + msg: 'ハイライト!' // [!code highlight] + } + } + } + ``` + +## コードブロックでのフォーカス {#focus-in-code-blocks} + +`// [!code focus]` コメントを行に付けると、その行にフォーカスし、他の部分がぼかされます。 + +また、`// [!code focus:]` を使ってフォーカスする行数を指定することもできます。 + +**入力** + + ```` + ```js + export default { + data () { + return { + msg: 'フォーカス!' // [!!code focus] + } + } + } + ``` + ```` + +**出力** + +```js +export default { + data() { + return { + msg: 'フォーカス!' // [!code focus] + } + } +} +``` + +## コードブロックのカラー差分表示 {#colored-diffs-in-code-blocks} + +`// [!code --]` または `// [!code ++]` コメントを行に付けると、その行に差分(削除/追加)スタイルを適用できます。コードブロックの色付けは維持されます。 + +**入力** + + ```` + ```js + export default { + data () { + return { + msg: 'Removed' // [!!code --] + msg: 'Added' // [!!code ++] + } + } + } + ``` + ```` + +**出力** + +```js +export default { + data () { + return { + msg: 'Removed' // [!code --] + msg: 'Added' // [!code ++] + } + } +} +``` + +## コードブロック内のエラー/警告表示 {#errors-and-warnings-in-code-blocks} + +行に `// [!code warning]` または `// [!code error]` コメントを付けると、その行が対応する色で表示されます。 + +**入力** + + ```` + ```js + export default { + data () { + return { + msg: 'Error', // [!!code error] + msg: 'Warning' // [!!code warning] + } + } + } + ``` + ```` + +**出力** + +```js +export default { + data() { + return { + msg: 'Error', // [!code error] + msg: 'Warning' // [!code warning] + } + } +} +``` + +## 行番号 {#line-numbers} + +設定で、各コードブロックに行番号を表示できます: + + ```js + export default { + markdown: { + lineNumbers: true + } + } + ``` + +詳しくは [`markdown` オプション](../reference/site-config#markdown) を参照してください。 + +設定値を上書きするために、フェンス付きコードブロックに `:line-numbers` / `:no-line-numbers` マークを付与できます。 + +また、`:line-numbers` の後ろに `=` を付けて開始行番号を指定できます。例:`:line-numbers=2` は行番号が `2` から始まることを意味します。 + +**入力** + + ```` + ```ts {1} + // 既定では line-numbers は無効 + const line2 = 'This is line 2' + const line3 = 'This is line 3' + ``` + + ```ts:line-numbers {1} + // line-numbers が有効 + const line2 = 'This is line 2' + const line3 = 'This is line 3' + ``` + + ```ts:line-numbers=2 {1} + // line-numbers が有効で、2 から開始 + const line3 = 'This is line 3' + const line4 = 'This is line 4' + ``` + ```` + +**出力** + + ```ts {1} + // 既定では line-numbers は無効 + const line2 = 'This is line 2' + const line3 = 'This is line 3' + ``` + + ```ts:line-numbers {1} + // line-numbers が有効 + const line2 = 'This is line 2' + const line3 = 'This is line 3' + ``` + + ```ts:line-numbers=2 {1} + // line-numbers が有効で、2 から開始 + const line3 = 'This is line 3' + const line4 = 'This is line 4' + ``` + +## コードスニペットのインポート {#import-code-snippets} + +既存ファイルから、次の構文でコードスニペットをインポートできます: + + ```md + <<< @/filepath + ``` + +また、[行のハイライト](#line-highlighting-in-code-blocks)にも対応しています: + + ```md + <<< @/filepath{highlightLines} + ``` + +**入力** + + ```md + <<< @/snippets/snippet.js{2} + ``` + +**コードファイル** + +<<< @/snippets/snippet.js + +**出力** + +<<< @/snippets/snippet.js{2} + +::: tip +`@` の値はソースルートを表します。既定では VitePress プロジェクトのルートですが、`srcDir` を設定している場合はその値になります。代替として、相対パスからのインポートも可能です: + + ```md + <<< ../snippets/snippet.js + ``` +::: + +また、[VS Code のリージョン](https://code.visualstudio.com/docs/editor/codebasics#_folding)を利用して、コードファイルの該当部分のみを取り込むことができます。ファイルパスの後ろに `#` を付けてカスタムリージョン名を指定します: + +**入力** + + ```md + <<< @/snippets/snippet-with-region.js#snippet{1} + ``` + +**コードファイル** + +<<< @/snippets/snippet-with-region.js + +**出力** + +<<< @/snippets/snippet-with-region.js#snippet{1} + +中括弧(`{}`)の中で言語を指定することもできます: + + ```md + <<< @/snippets/snippet.cs{c#} + + + + <<< @/snippets/snippet.cs{1,2,4-6 c#} + + + + <<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers} + ``` + +これは、ファイル拡張子からソース言語を推論できない場合に有用です。 + +## コードグループ {#code-groups} + +複数のコードブロックを、次のようにグループ化できます。 + +**入力** + + ````md + ::: code-group + + ```js [config.js] + /** + * @type {import('vitepress').UserConfig} + */ + const config = { + // ... + } + + export default config + ``` + + ```ts [config.ts] + import type { UserConfig } from 'vitepress' + + const config: UserConfig = { + // ... + } + + export default config + ``` + + ::: + ```` + +**出力** + + + ::: code-group + + ```js [config.js] + /** + * @type {import('vitepress').UserConfig} + */ + const config = { + // ... + } + + export default config + ``` + + ```ts [config.ts] + import type { UserConfig } from 'vitepress' + + const config: UserConfig = { + // ... + } + + export default config + ``` + + ::: + +コードグループ内でも [スニペットのインポート](#import-code-snippets) が可能です: + +**入力** + + ```md + ::: code-group + + + + <<< @/snippets/snippet.js + + + + <<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [リージョン付きスニペット] + + ::: + ``` + +**出力** + +::: code-group + +<<< @/snippets/snippet.js + +<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [リージョン付きスニペット] + +::: + +## Markdown ファイルのインクルード {#markdown-file-inclusion} + +ある Markdown ファイルの中に、別の Markdown ファイルを取り込めます(入れ子も可能)。 + +::: tip +Markdown パスの先頭に `@` を付けることもでき、その場合はソースルートとして扱われます。既定では VitePress プロジェクトのルートですが、`srcDir` を設定している場合はその値になります。 +::: + +例えば、相対パスの Markdown ファイルを次のように取り込めます。 + +**入力** + + ```md + # ドキュメント + + ## 基本 + + + ``` + +**パートファイル**(`parts/basics.md`) + + ```md + はじめに知っておきたいこと。 + + ### 設定 + + `.foorc.json` を使用して作成できます。 + ``` + +**等価なコード** + + ```md + # ドキュメント + + ## 基本 + + はじめに知っておきたいこと。 + + ### 設定 + + `.foorc.json` を使用して作成できます。 + ``` + +行範囲の選択にも対応しています。 + +**入力** + + ```md:line-numbers + # ドキュメント + + ## 基本 + + + ``` + +**パートファイル**(`parts/basics.md`) + + ```md:line-numbers + はじめに知っておきたいこと。 + + ### 設定 + + `.foorc.json` を使って作成できます。 + ``` + +**等価なコード** + + ```md:line-numbers + # ドキュメント + + ## 基本 + + ### 設定 + + `.foorc.json` を使って作成できます。 + ``` + +選択できる行範囲の書式は、`{3,}`、`{,10}`、`{1,10}` のいずれかです。 + +[VS Code のリージョン](https://code.visualstudio.com/docs/editor/codebasics#_folding)を使って、コードファイルの該当部分だけを取り込むこともできます。ファイルパスの後ろに `#` を付けて、カスタムリージョン名を指定します。 + +**入力** + + ```md:line-numbers + # ドキュメント + + ## 基本 + + + + ``` + +**パートファイル**(`parts/basics.md`) + + ```md:line-numbers + + ## 使用例 1 + + ## 使用例 2 + + ## 使用例 3 + + ``` + +**等価なコード** + + ```md:line-numbers + # ドキュメント + + ## 基本 + + ## 使用例 1 + + ## 使用例 3 + ``` + +::: warning +ファイルが存在しない場合でもエラーは発生しません。したがって、この機能を使う際は、期待どおりに内容がレンダリングされているか必ず確認してください。 +::: + +VS Code のリージョンの代わりに、ヘッダーアンカーを使ってファイル内の特定セクションだけを取り込むこともできます。たとえば、Markdown ファイルに次のようなヘッダーがある場合: + + ```md + ## ベースのセクション + + ここに本文。 + + ### サブセクション + + ここに本文(サブ)。 + + ## 別のセクション + + `ベースのセクション` の外側の内容。 + ``` + +`ベースのセクション` を次のように取り込めます: + + ```md + ## 拡張セクション + + ``` + +**等価なコード** + + ```md + ## 拡張セクション + + ここに本文。 + + ### サブセクション + + ここに本文(サブ)。 + ``` + +ここで `my-base-section` は見出し要素から生成される ID です。推測しづらい場合は、パートファイルをブラウザで開いて見出しのアンカー(ホバー時に見出しの左に表示される `#` 記号)をクリックし、URL バーで ID を確認してください。あるいはブラウザの開発者ツールで要素を検査して確認できます。別案として、パートファイル側で明示的に ID を指定できます: + + ```md + ## ベースのセクション {#custom-id} + ``` + +そして次のように取り込みます: + + ```md + + ``` + +## 数式 {#math-equations} + +この機能はオプトインです。利用するには `markdown-it-mathjax3` をインストールし、設定ファイルで `markdown.math` を `true` に設定します。 + + ```sh + npm add -D markdown-it-mathjax3 + ``` + + ```ts [.vitepress/config.ts] + export default { + markdown: { + math: true + } + } + ``` + +**入力** + + ```md + もし $a \ne 0$ のとき、$(ax^2 + bx + c = 0)$ の解は 2 つ存在し、次式で与えられます + $$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$ + + **マクスウェル方程式:** + + | 方程式 | 説明 | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | + | $\nabla \cdot \vec{\mathbf{B}} = 0$ | 磁束密度 $\vec{\mathbf{B}}$ の発散は 0 | + | $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | 電場 $\vec{\mathbf{E}}$ の回転は、磁束密度 $\vec{\mathbf{B}}$ の時間変化に比例 | + | $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _え?_ | + ``` + +**出力** + + もし $a \ne 0$ のとき、$(ax^2 + bx + c = 0)$ の解は 2 つ存在し、次式で与えられます + $$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$ + + **マクスウェル方程式:** + + | 方程式 | 説明 | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | + | $\nabla \cdot \vec{\mathbf{B}} = 0$ | 磁束密度 $\vec{\mathbf{B}}$ の発散は 0 | + | $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | 電場 $\vec{\mathbf{E}}$ の回転は、磁束密度 $\vec{\mathbf{B}}$ の時間変化に比例 | + | $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _え?_ | + +## 画像の遅延読み込み {#image-lazy-loading} + +Markdown で追加した各画像に対して遅延読み込みを有効化するには、設定ファイルで `lazyLoading` を `true` にします: + + ```js + export default { + markdown: { + image: { + // 既定では画像の遅延読み込みは無効 + lazyLoading: true + } + } + } + ``` + +## 高度な設定 {#advanced-configuration} + +VitePress は Markdown レンダラーとして [markdown-it](https://github.com/markdown-it/markdown-it) を使用しています。上記の多くの拡張はカスタムプラグインとして実装されています。`.vitepress/config.js` の `markdown` オプションを使って、`markdown-it` のインスタンスをさらにカスタマイズできます。 + + ```js + import { defineConfig } from 'vitepress' + import markdownItAnchor from 'markdown-it-anchor' + import markdownItFoo from 'markdown-it-foo' + + export default defineConfig({ + markdown: { + // markdown-it-anchor のオプション + // https://github.com/valeriangalliat/markdown-it-anchor#usage + anchor: { + permalink: markdownItAnchor.permalink.headerLink() + }, + + // @mdit-vue/plugin-toc のオプション + // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options + toc: { level: [1, 2] }, + + config: (md) => { + // markdown-it のプラグインをもっと使えます! + md.use(markdownItFoo) + } + } + }) + ``` + +設定可能なプロパティの完全な一覧は、[設定リファレンス: アプリ設定](../reference/site-config#markdown) を参照してください。 diff --git a/docs/ja/guide/mpa-mode.md b/docs/ja/guide/mpa-mode.md new file mode 100644 index 000000000000..312cc3f7d573 --- /dev/null +++ b/docs/ja/guide/mpa-mode.md @@ -0,0 +1,23 @@ +# MPA モード {#mpa-mode} + +MPA(Multi-Page Application)モードは、コマンドラインの `vitepress build --mpa`、または設定で `mpa: true` を指定することで有効化できます。 + +MPA モードでは、既定で **あらゆるページが JavaScript を含まずに** レンダリングされます。結果として、本番サイトは監査ツールにおける初回訪問のパフォーマンススコアが向上しやすくなります。 + +一方、SPA のナビゲーションがないため、ページ間リンクはフルリロードになります。読み込み後のページ遷移は、SPA モードのような即時性はありません。 + +また、「既定で JS なし」ということは、実質的に Vue をサーバーサイドのテンプレート言語としてのみ使うことを意味します。ブラウザ側ではイベントハンドラがアタッチされないため、インタラクティブ性はありません。クライアントサイドの JavaScript を読み込むには、特別な ` + + # Hello + ``` + +` + ``` + +### 生コンテンツのレンダリング {#rendering-raw-content} + +ページに渡したパラメータはクライアント JavaScript のペイロードにシリアライズされます。そのため、リモート CMS から取得した生の Markdown や HTML など、重いデータをパラメータに含めるのは避けてください。 + +代わりに、各パスオブジェクトの `content` プロパティでコンテンツを渡せます: + + ```js + export default { + async paths() { + const posts = await (await fetch('https://my-cms.com/blog-posts')).json() + + return posts.map((post) => { + return { + params: { id: post.id }, + content: post.content // 生の Markdown または HTML + } + }) + } + } + ``` + +そのうえで、Markdown ファイル内で次の特別な構文を使って、そのコンテンツを埋め込みます: + + ```md + + ``` diff --git a/docs/ja/guide/sitemap-generation.md b/docs/ja/guide/sitemap-generation.md new file mode 100644 index 000000000000..db44942c02e6 --- /dev/null +++ b/docs/ja/guide/sitemap-generation.md @@ -0,0 +1,58 @@ +# サイトマップ生成 {#sitemap-generation} + +VitePress には、サイト用の `sitemap.xml` を生成する機能が標準で用意されています。有効化するには、`.vitepress/config.js` に次を追加します。 + + ```ts + export default { + sitemap: { + hostname: 'https://example.com' + } + } + ``` + +`siteamp.xml` に `` タグを含めるには、[`lastUpdated`](../reference/default-theme-last-updated) オプションを有効にします。 + +## オプション {#options} + +サイトマップ生成は [`sitemap`](https://www.npmjs.com/package/sitemap) モジュールで行われます。設定ファイルの `sitemap` に、このモジュールがサポートする任意のオプションを渡せます。指定した値はそのまま `SitemapStream` コンストラクタに渡されます。詳しくは [`sitemap` のドキュメント](https://www.npmjs.com/package/sitemap#options-you-can-pass) を参照してください。例: + + ```ts + export default { + sitemap: { + hostname: 'https://example.com', + lastmodDateOnly: false + } + } + ``` + +設定で `base` を使っている場合は、`hostname` にもそれを付与してください: + + ```ts + export default { + base: '/my-site/', + sitemap: { + hostname: 'https://example.com/my-site/' + } + } + ``` + +## `transformItems` フック {#transformitems-hook} + +`siteamp.xml` に書き出す直前にサイトマップ項目を加工するには、`sitemap.transformItems` フックを使います。このフックはサイトマップ項目の配列を受け取り、配列を返す必要があります。例: + + ```ts + export default { + sitemap: { + hostname: 'https://example.com', + transformItems: (items) => { + // 既存項目の追加・変更・フィルタリングが可能 + items.push({ + url: '/extra-page', + changefreq: 'monthly', + priority: 0.8 + }) + return items + } + } + } + ``` diff --git a/docs/ja/guide/ssr-compat.md b/docs/ja/guide/ssr-compat.md new file mode 100644 index 000000000000..d756d6d14408 --- /dev/null +++ b/docs/ja/guide/ssr-compat.md @@ -0,0 +1,135 @@ +--- +outline: deep +--- + +# SSR 互換性 {#ssr-compatibility} + +VitePress は本番ビルド時に、Node.js 上で Vue のサーバーサイドレンダリング(SSR)機能を使ってアプリを事前レンダリングします。つまり、テーマコンポーネント内のすべてのカスタムコードは SSR 互換性の対象になります。 + +[公式 Vue ドキュメントの SSR セクション](https://vuejs.org/guide/scaling-up/ssr.html)では、SSR とは何か、SSR と SSG の関係、そして SSR に優しいコードを書く際の一般的な注意点が解説されています。経験則としては、**ブラウザ / DOM API へのアクセスは Vue コンポーネントの `beforeMount` または `mounted` フック内に限定** するのが安全です。 + +## `` {#clientonly} + +SSR に適さないコンポーネント(例:カスタムディレクティブを含むなど)を使用・デモする場合は、組み込みの `` コンポーネントでラップできます。 + + ```md + + + + ``` + +## インポート時に Browser API にアクセスするライブラリ {#libraries-that-access-browser-api-on-import} + +一部のコンポーネントやライブラリは **インポート時に** ブラウザ API にアクセスします。インポート時にブラウザ環境を前提とするコードを使うには、動的インポートが必要です。 + +### mounted フック内でのインポート {#importing-in-mounted-hook} + + ```vue + + ``` + +### 条件付きインポート {#conditional-import} + +[`import.meta.env.SSR`](https://vitejs.dev/guide/env-and-mode.html#env-variables) フラグ(Vite の環境変数の一部)を使って、依存関係を条件付きでインポートすることもできます。 + + ```js + if (!import.meta.env.SSR) { + import('./lib-that-access-window-on-import').then((module) => { + // ここでコードを利用 + }) + } + ``` + +[`Theme.enhanceApp`](./custom-theme#theme-interface) は非同期にできるため、**インポート時に Browser API に触れる Vue プラグイン** を条件付きでインポート・登録できます。 + + ```js [.vitepress/theme/index.js] + /** @type {import('vitepress').Theme} */ + export default { + // ... + async enhanceApp({ app }) { + if (!import.meta.env.SSR) { + const plugin = await import('plugin-that-access-window-on-import') + app.use(plugin.default) + } + } + } + ``` + +TypeScript を使う場合: + + ```ts [.vitepress/theme/index.ts] + import type { Theme } from 'vitepress' + + export default { + // ... + async enhanceApp({ app }) { + if (!import.meta.env.SSR) { + const plugin = await import('plugin-that-access-window-on-import') + app.use(plugin.default) + } + } + } satisfies Theme + ``` + +### `defineClientComponent` + +VitePress は、**インポート時に Browser API にアクセスする Vue コンポーネント** を読み込むためのユーティリティを提供します。 + + ```vue + + + + ``` + +ターゲットコンポーネントに props / children / slots を渡すこともできます。 + + ```vue + + + + ``` + +ターゲットコンポーネントは、ラッパーコンポーネントの mounted フックで初めてインポートされます。 diff --git a/docs/ja/guide/using-vue.md b/docs/ja/guide/using-vue.md new file mode 100644 index 000000000000..65f2383e82b1 --- /dev/null +++ b/docs/ja/guide/using-vue.md @@ -0,0 +1,288 @@ +# MarkdownでVueを使う {#using-vue-in-markdown} + +VitePress では、各 Markdown ファイルはまず HTML にコンパイルされ、その後 [Vue の単一ファイルコンポーネント(SFC)](https://vuejs.org/guide/scaling-up/sfc.html) として処理されます。つまり、Markdown 内で Vue のあらゆる機能が使えます。動的テンプレート、Vue コンポーネントの利用、` + + ## Markdown コンテンツ + + 現在の値: {{ count }} + + + + + ``` + +::: warning Markdown での ` + ``` + +## Teleport の利用 {#using-teleports} + +現時点で VitePress は、SSG における Teleport を **body** へのみサポートしています。その他のターゲットへ Teleport したい場合は、組み込みの `` でラップするか、[`postRender` フック](../reference/site-config#postrender)で最終ページ HTML の適切な位置に Teleport のマークアップを注入してください。 + + + +::: details +<<< @/components/ModalDemo.vue +::: + + ```md + + +
+ // ... +
+
+
+ ``` + + + + + +## VS Code の IntelliSense サポート {#vs-code-intellisense-support} + + + +Vue は [Vue - Official VS Code plugin](https://marketplace.visualstudio.com/items?itemName=Vue.volar) により、標準で IntelliSense を提供します。ただし `.md` ファイルでも有効にするには、設定ファイルをいくつか調整する必要があります。 + +1. tsconfig/jsconfig の `include` と `vueCompilerOptions.vitePressExtensions` に `.md` パターンを追加します。 + + ::: code-group + ```json [tsconfig.json] + { + "include": [ + "docs/**/*.ts", + "docs/**/*.vue", + "docs/**/*.md", + ], + "vueCompilerOptions": { + "vitePressExtensions": [".md"], + }, + } + ``` + ::: + +2. VS Code の設定で、`vue.server.includeLanguages` に `markdown` を追加します。 + + ::: code-group + ```json [.vscode/settings.json] + { + "vue.server.includeLanguages": ["vue", "markdown"] + } + ``` + ::: diff --git a/docs/ja/guide/what-is-vitepress.md b/docs/ja/guide/what-is-vitepress.md new file mode 100644 index 000000000000..8d96c80c42d9 --- /dev/null +++ b/docs/ja/guide/what-is-vitepress.md @@ -0,0 +1,57 @@ +# VitePress とは? {#what-is-vitepress} + +VitePress は、高速でコンテンツ中心の Web サイトを構築するための [静的サイトジェネレーター(SSG)](https://en.wikipedia.org/wiki/Static_site_generator) です。要するに、VitePress は [Markdown](https://en.wikipedia.org/wiki/Markdown) で書かれたソースコンテンツにテーマを適用し、どこにでも簡単にデプロイできる静的 HTML ページを生成します。 + +
+ +まずは試してみたい? [クイックスタート](./getting-started) へどうぞ。 + +
+ +## ユースケース {#use-cases} + +- **ドキュメント** + + VitePress には技術ドキュメント向けに設計されたデフォルトテーマが同梱されています。今あなたが読んでいるこのページのほか、[Vite](https://vitejs.dev/)、[Rollup](https://rollupjs.org/)、[Pinia](https://pinia.vuejs.org/)、[VueUse](https://vueuse.org/)、[Vitest](https://vitest.dev/)、[D3](https://d3js.org/)、[UnoCSS](https://unocss.dev/)、[Iconify](https://iconify.design/) など、[まだまだたくさん](https://github.com/search?q=/"vitepress":+/+language:json&type=code)のドキュメントサイトで使われています。 + + [公式の Vue.js ドキュメント](https://vuejs.org/) も VitePress をベースにしています(複数言語で共有されるカスタムテーマを使用)。 + +- **ブログ/ポートフォリオ/マーケティングサイト** + + VitePress は [フルカスタムテーマ](./custom-theme) をサポートし、標準的な Vite + Vue アプリ同様の開発体験を提供します。Vite 上に構築されているため、豊富なエコシステムから Vite プラグインを直接活用できます。さらに、[データの読み込み](./data-loading)(ローカル/リモート)や [ルートの動的生成](./routing#dynamic-routes) のための柔軟な API も提供します。ビルド時にデータが確定できる限り、ほとんど何でも構築できます。 + + 公式の [Vue.js ブログ](https://blog.vuejs.org/) は、ローカルコンテンツに基づいてインデックスページを生成するシンプルなブログです。 + +## 開発体験 {#developer-experience} + +VitePress は、Markdown コンテンツを扱う際の優れた開発体験(DX)を目指しています。 + +- **[Vite 駆動](https://vitejs.dev/)**:即時サーバー起動、編集はページリロードなしで常に瞬時(<100ms)に反映。 + +- **[ビルトインの Markdown 拡張](./markdown)**:Frontmatter、表、シンタックスハイライト…必要なものはひと通り。特にコードブロック周りの機能が充実しており、高度な技術ドキュメントに最適です。 + +- **[Vue 拡張 Markdown](./using-vue)**:各 Markdown ページは Vue の [単一ファイルコンポーネント(SFC)](https://vuejs.org/guide/scaling-up/sfc.html) としても機能します。HTML と 100% 互換な Vue テンプレートを活かし、Vue のテンプレート機能やインポートしたコンポーネントで静的コンテンツにインタラクションを埋め込めます。 + +## パフォーマンス {#performance} + +多くの従来型 SSG と異なり、VitePress で生成されたサイトは **初回訪問では静的 HTML** を返し、その後のサイト内ナビゲーションは [シングルページアプリケーション(SPA)](https://en.wikipedia.org/wiki/Single-page_application) として動作します。これはパフォーマンス面で最適なバランスだと考えています。 + +- **初期ロードが速い** + + どのページへの初回訪問でも、静的な事前レンダリング HTML が配信され、高速な読み込みと最適な SEO を実現します。続いて JavaScript バンドルが読み込まれ、ページが Vue の SPA に「ハイドレート」されます。SPA のハイドレーションは遅いという通説に反し、Vue 3 の素のパフォーマンスとコンパイラ最適化により非常に高速です。[PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F) でも、VitePress サイトは低速回線のローエンド端末でもほぼ満点のスコアを達成できます。 + +- **読み込み後のナビゲーションが速い** + + さらに重要なのは、初回ロード**後**の体験が向上することです。サイト内の以降の移動ではフルリロードは発生せず、遷移先のコンテンツを取得して動的に更新します。VitePress はビューポート内のリンクに対してページチャンクを自動プリフェッチするため、ほとんどの場合で遷移は「即時」に感じられます。 + +- **インタラクションのペナルティなし** + + 静的 Markdown に埋め込まれた動的な Vue 部分をハイドレートできるよう、各 Markdown ページは Vue コンポーネントとして処理され JavaScript にコンパイルされます。一見非効率に思えますが、Vue コンパイラは静的部分と動的部分を賢く分離し、ハイドレーションのコストとペイロードを最小化します。初回ロードでは静的部分は自動的に JS ペイロードから除外され、ハイドレーションでもスキップされます。 + +## VuePress はどうなるの? {#what-about-vuepress} + +VitePress は VuePress 1 の精神的後継です。元の VuePress 1 は Vue 2 と webpack をベースとしていました。VitePress は内部に Vue 3 と Vite を採用し、開発体験・本番性能・完成度の高いデフォルトテーマ・より柔軟なカスタマイズ API を提供します。 + +VitePress と VuePress 1 の API の違いは主にテーマやカスタマイズ周りにあります。VuePress 1 でデフォルトテーマを使っている場合は、比較的容易に移行できます。 + +2 つの SSG を並行して維持するのは現実的ではないため、Vue チームは長期的に VitePress を推奨 SSG とする方針に集中しています。現在、VuePress 1 は非推奨となり、VuePress 2 は今後の開発・保守を VuePress コミュニティチームに委ねています。 diff --git a/docs/ja/index.md b/docs/ja/index.md new file mode 100644 index 000000000000..ab3ee24315c1 --- /dev/null +++ b/docs/ja/index.md @@ -0,0 +1,35 @@ +--- +layout: home + +hero: + name: VitePress + text: Vite & Vue をベースにした静的サイトジェネレーター + tagline: Markdown から美しいドキュメントを数分で + actions: + - theme: brand + text: VitePress とは? + link: /ja/guide/what-is-vitepress + - theme: alt + text: クイックスタート + link: /ja/guide/getting-started + - theme: alt + text: GitHub + link: https://github.com/vuejs/vitepress + image: + src: /vitepress-logo-large.svg + alt: VitePress + +features: + - icon: 📝 + title: コンテンツに集中 + details: Markdown だけで、美しいドキュメントサイトを簡単に作成できます。 + - icon: + title: Vite の開発体験を享受 + details: 即時サーバー起動、超高速ホットリロード、そして Vite エコシステムのプラグイン活用。 + - icon: + title: Vue でカスタマイズ + details: Markdown 内で直接 Vue 構文やコンポーネントを利用したり、Vue で独自テーマを構築できます。 + - icon: 🚀 + title: 高速サイトを公開 + details: 静的 HTML による高速初期ロードと、クライアントサイドルーティングによる快適なページ遷移。 +--- diff --git a/docs/ja/reference/cli.md b/docs/ja/reference/cli.md new file mode 100644 index 000000000000..78d06b8b7b39 --- /dev/null +++ b/docs/ja/reference/cli.md @@ -0,0 +1,73 @@ +# コマンドラインインターフェイス {#command-line-interface} + +## `vitepress dev` + +指定したディレクトリをルートとして VitePress の開発サーバーを起動します。既定はカレントディレクトリです。カレントディレクトリで実行する場合、`dev` コマンドは省略できます。 + +### 使い方 {#usage} + + ```sh + # カレントディレクトリで起動(`dev` を省略) + vitepress + + # サブディレクトリで起動 + vitepress dev [root] + ``` + +### オプション {#options} + +| オプション | 説明 | +| ------------------ | -------------------------------------------------------------------- | +| `--open [path]` | 起動時にブラウザを開く(`boolean \| string`) | +| `--port ` | ポート番号を指定(`number`) | +| `--base ` | 公開時のベースパス(既定: `/`)(`string`) | +| `--cors` | CORS を有効化 | +| `--strictPort` | 指定ポートが使用中なら終了(`boolean`) | +| `--force` | 最適化時にキャッシュを無視して再バンドル(`boolean`) | + +## `vitepress build` + +本番用に VitePress サイトをビルドします。 + +### 使い方 {#usage-1} + + ```sh + vitepress build [root] + ``` + +### オプション {#options-1} + +| オプション | 説明 | +| ----------------------------- | -------------------------------------------------------------------------------------------------- | +| `--mpa`(実験的) | クライアント側ハイドレーションなしの [MPA モード](../guide/mpa-mode) でビルド(`boolean`) | +| `--base ` | 公開時のベースパス(既定: `/`)(`string`) | +| `--target ` | トランスパイルターゲット(既定: `"modules"`)(`string`) | +| `--outDir ` | 出力先ディレクトリ(**cwd** からの相対)(既定: `/.vitepress/dist`)(`string`) | +| `--assetsInlineLimit `| 静的アセットを base64 インライン化する閾値(バイト)(既定: `4096`)(`number`) | + +## `vitepress preview` + +本番ビルドをローカルでプレビューします。 + +### 使い方 {#usage-2} + + ```sh + vitepress preview [root] + ``` + +### オプション {#options-2} + +| オプション | 説明 | +| ------------------ | ----------------------------------------- | +| `--base ` | 公開時のベースパス(既定: `/`)(`string`) | +| `--port ` | ポート番号を指定(`number`) | + +## `vitepress init` + +カレントディレクトリで [セットアップウィザード](../guide/getting-started#setup-wizard) を起動します。 + +### 使い方 {#usage-3} + + ```sh + vitepress init + ``` diff --git a/docs/ja/reference/default-theme-badge.md b/docs/ja/reference/default-theme-badge.md new file mode 100644 index 000000000000..034f1a2f27a1 --- /dev/null +++ b/docs/ja/reference/default-theme-badge.md @@ -0,0 +1,69 @@ +# バッジ {#badge} + +バッジを使うと、見出しにステータスを追加できます。たとえば、そのセクションの種類や対応バージョンを示すのに便利です。 + +## 使い方 {#usage} + +グローバルに利用可能な `Badge` コンポーネントを使用します。 + + ```html + ### Title + ### Title + ### Title + ### Title + ``` + +上記のコードは次のように表示されます: + +### Title +### Title +### Title +### Title + +## 子要素のカスタマイズ {#custom-children} + +`` は子要素(`children`)を受け取り、バッジ内に表示できます。 + + ```html + ### Title custom element + ``` + +### Title custom element + +## 種類ごとの色をカスタマイズ {#customize-type-color} + +CSS 変数を上書きすることで、バッジのスタイルをカスタマイズできます。以下はデフォルト値です: + + ```css + :root { + --vp-badge-info-border: transparent; + --vp-badge-info-text: var(--vp-c-text-2); + --vp-badge-info-bg: var(--vp-c-default-soft); + + --vp-badge-tip-border: transparent; + --vp-badge-tip-text: var(--vp-c-brand-1); + --vp-badge-tip-bg: var(--vp-c-brand-soft); + + --vp-badge-warning-border: transparent; + --vp-badge-warning-text: var(--vp-c-warning-1); + --vp-badge-warning-bg: var(--vp-c-warning-soft); + + --vp-badge-danger-border: transparent; + --vp-badge-danger-text: var(--vp-c-danger-1); + --vp-badge-danger-bg: var(--vp-c-danger-soft); + } + ``` + +## `` + +`` コンポーネントは次の props を受け取ります。 + + ```ts + interface Props { + // `` が渡された場合、この値は無視されます。 + text?: string + + // 既定値は `tip`。 + type?: 'info' | 'tip' | 'warning' | 'danger' + } + ``` diff --git a/docs/ja/reference/default-theme-carbon-ads.md b/docs/ja/reference/default-theme-carbon-ads.md new file mode 100644 index 000000000000..222c80b3ce0f --- /dev/null +++ b/docs/ja/reference/default-theme-carbon-ads.md @@ -0,0 +1,22 @@ +# Carbon 広告 {#carbon-ads} + +VitePress は [Carbon Ads](https://www.carbonads.net/) をネイティブにサポートしています。設定で Carbon Ads の認証情報を定義すると、ページ上に広告が表示されます。 + + ```js + export default { + themeConfig: { + carbonAds: { + code: 'your-carbon-code', + placement: 'your-carbon-placement' + } + } + } + ``` + +これらの値は、次のように Carbon の CDN スクリプトを呼び出すために使用されます。 + + ```js + `//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}` + ``` + +Carbon Ads の設定について詳しくは、[Carbon Ads のウェブサイト](https://www.carbonads.net/)を参照してください。 diff --git a/docs/ja/reference/default-theme-config.md b/docs/ja/reference/default-theme-config.md new file mode 100644 index 000000000000..bb37d13a1de2 --- /dev/null +++ b/docs/ja/reference/default-theme-config.md @@ -0,0 +1,494 @@ +# デフォルトテーマの設定 {#default-theme-config} + +テーマ設定では、テーマのカスタマイズができます。設定ファイルの `themeConfig` オプションで定義します。 + + ```ts + export default { + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + + // テーマ関連の設定 + themeConfig: { + logo: '/logo.svg', + nav: [...], + sidebar: { ... } + } + } + ``` + +**このページで説明するオプションは、デフォルトテーマにのみ適用されます。** テーマによって期待する設定は異なります。カスタムテーマを使用する場合、ここで定義したテーマ設定オブジェクトはテーマへ渡され、テーマ側がそれに基づいて条件付きの挙動を定義できます。 + +## i18nRouting + +- 型: `boolean` + +ロケールを `zh` のように切り替えると、URL は `/foo`(または `/en/foo/`)から `/zh/foo` に変わります。`themeConfig.i18nRouting` を `false` に設定すると、この挙動を無効化できます。 + +## logo + +- 型: `ThemeableImage` + +サイトタイトルの直前に、ナビゲーションバーに表示されるロゴ。パス文字列、またはライト/ダークモードで異なるロゴを設定するオブジェクトを受け取ります。 + + ```ts + export default { + themeConfig: { + logo: '/logo.svg' + } + } + ``` + + ```ts + type ThemeableImage = + | string + | { src: string; alt?: string } + | { light: string; dark: string; alt?: string } + ``` + +## siteTitle + +- 型: `string | false` + +ナビゲーション内の既定サイトタイトル(アプリ設定の `title`)を置き換えます。`false` の場合、ナビのタイトルを非表示にします。ロゴ自体にサイト名が含まれている場合に便利です。 + + ```ts + export default { + themeConfig: { + siteTitle: 'Hello World' + } + } + ``` + +## nav + +- 型: `NavItem` + +ナビゲーションメニューの設定。[デフォルトテーマ: ナビ](./default-theme-nav#navigation-links) を参照してください。 + + ```ts + export default { + themeConfig: { + nav: [ + { text: 'Guide', link: '/guide' }, + { + text: 'Dropdown Menu', + items: [ + { text: 'Item A', link: '/item-1' }, + { text: 'Item B', link: '/item-2' }, + { text: 'Item C', link: '/item-3' } + ] + } + ] + } + } + ``` + + ```ts + type NavItem = NavItemWithLink | NavItemWithChildren + + interface NavItemWithLink { + text: string + link: string | ((payload: PageData) => string) + activeMatch?: string + target?: string + rel?: string + noIcon?: boolean + } + + interface NavItemChildren { + text?: string + items: NavItemWithLink[] + } + + interface NavItemWithChildren { + text?: string + items: (NavItemChildren | NavItemWithLink)[] + activeMatch?: string + } + ``` + +## sidebar + +- 型: `Sidebar` + +サイドバーメニューの設定。[デフォルトテーマ: サイドバー](./default-theme-sidebar) を参照してください。 + + ```ts + export default { + themeConfig: { + sidebar: [ + { + text: 'Guide', + items: [ + { text: 'Introduction', link: '/introduction' }, + { text: 'Getting Started', link: '/getting-started' }, + ... + ] + } + ] + } + } + ``` + + ```ts + export type Sidebar = SidebarItem[] | SidebarMulti + + export interface SidebarMulti { + [path: string]: SidebarItem[] | { items: SidebarItem[]; base: string } + } + + export type SidebarItem = { + /** + * 項目のテキストラベル + */ + text?: string + + /** + * 項目のリンク + */ + link?: string + + /** + * 子項目 + */ + items?: SidebarItem[] + + /** + * 指定しない場合、グループは折りたたみ不可。 + * + * `true` なら折りたたみ可能でデフォルト折りたたみ + * + * `false` なら折りたたみ可能だがデフォルト展開 + */ + collapsed?: boolean + + /** + * 子項目のベースパス + */ + base?: string + + /** + * 前/次リンクのフッターに表示するテキストをカスタマイズ + */ + docFooterText?: string + + rel?: string + target?: string + } + ``` + +## aside + +- 型: `boolean | 'left'` +- 既定値: `true` +- ページごとに [frontmatter](./frontmatter-config#aside) で上書き可能 + +`false` でサイドコンテナの描画を無効化。\ +`true` で右側に表示。\ +`left` で左側に表示。 + +すべてのビューポートで無効にしたい場合は、代わりに `outline: false` を使用してください。 + +## outline + +- 型: `Outline | Outline['level'] | false` +- レベルはページごとに [frontmatter](./frontmatter-config#outline) で上書き可能 + +`false` でアウトラインコンテナの描画を無効化。詳細は以下を参照: + + ```ts + interface Outline { + /** + * アウトラインに表示する見出しレベル + * 単一の数値なら、そのレベルのみ表示 + * タプルなら最小レベルと最大レベル + * `'deep'` は `[2, 6]` と同じ(`

` 〜 `

` を表示) + * + * @default 2 + */ + level?: number | [number, number] | 'deep' + + /** + * アウトラインに表示するタイトル + * + * @default 'On this page' + */ + label?: string + } + ``` + +## socialLinks + +- 型: `SocialLink[]` + +ナビゲーションにアイコン付きのソーシャルリンクを表示します。 + + ```ts + export default { + themeConfig: { + socialLinks: [ + // simple-icons (https://simpleicons.org/) の任意のアイコンを指定可能 + { icon: 'github', link: 'https://github.com/vuejs/vitepress' }, + { icon: 'twitter', link: '...' }, + // SVG 文字列を渡してカスタムアイコンも可 + { + icon: { + svg: 'Dribbble' + }, + link: '...', + // アクセシビリティ向けにカスタムラベルも指定可(推奨) + ariaLabel: 'cool link' + } + ] + } + } + ``` + + ```ts + interface SocialLink { + icon: string | { svg: string } + link: string + ariaLabel?: string + } + ``` + +## footer + +- 型: `Footer` +- ページごとに [frontmatter](./frontmatter-config#footer) で上書き可能 + +フッター設定。メッセージや著作権表示を追加できますが、ページにサイドバーがある場合はデザイン上表示されません。 + + ```ts + export default { + themeConfig: { + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright © 2019-present Evan You' + } + } + } + ``` + + ```ts + export interface Footer { + message?: string + copyright?: string + } + ``` + +## editLink + +- 型: `EditLink` +- ページごとに [frontmatter](./frontmatter-config#editlink) で上書き可能 + +「このページを編集」リンクを表示します(GitHub/GitLab など)。詳細は [デフォルトテーマ: 編集リンク](./default-theme-edit-link) を参照。 + + ```ts + export default { + themeConfig: { + editLink: { + pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path', + text: 'Edit this page on GitHub' + } + } + } + ``` + + ```ts + export interface EditLink { + pattern: string + text?: string + } + ``` + +## lastUpdated + +- 型: `LastUpdatedOptions` + +最終更新の文言と日付フォーマットをカスタマイズします。 + + ```ts + export default { + themeConfig: { + lastUpdated: { + text: 'Updated at', + formatOptions: { + dateStyle: 'full', + timeStyle: 'medium' + } + } + } + } + ``` + + ```ts + export interface LastUpdatedOptions { + /** + * @default 'Last updated' + */ + text?: string + + /** + * @default + * { dateStyle: 'short', timeStyle: 'short' } + */ + formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean } + } + ``` + +## algolia + +- 型: `AlgoliaSearch` + +[Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch) によるサイト内検索の設定。[デフォルトテーマ: 検索](./default-theme-search) を参照。 + + ```ts + export interface AlgoliaSearchOptions extends DocSearchProps { + locales?: Record> + } + ``` + +完全なオプションは[こちら](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts)。 + +## carbonAds {#carbon-ads} + +- 型: `CarbonAdsOptions` + +[Carbon Ads](https://www.carbonads.net/) を表示します。 + + ```ts + export default { + themeConfig: { + carbonAds: { + code: 'your-carbon-code', + placement: 'your-carbon-placement' + } + } + } + ``` + + ```ts + export interface CarbonAdsOptions { + code: string + placement: string + } + ``` + +詳細は [デフォルトテーマ: Carbon Ads](./default-theme-carbon-ads) を参照。 + +## docFooter + +- 型: `DocFooter` + +前/次リンクの上に表示される文言をカスタマイズします。英語以外のドキュメントで便利。前/次リンク自体をグローバルに無効化することも可能。ページごとに切り替えたい場合は [frontmatter](./default-theme-prev-next-links) を使用します。 + + ```ts + export default { + themeConfig: { + docFooter: { + prev: 'Pagina prior', + next: 'Proxima pagina' + } + } + } + ``` + + ```ts + export interface DocFooter { + prev?: string | false + next?: string | false + } + ``` + +## darkModeSwitchLabel + +- 型: `string` +- 既定値: `Appearance` + +ダークモード切替スイッチのラベル(モバイル表示のみ)をカスタマイズします。 + +## lightModeSwitchTitle + +- 型: `string` +- 既定値: `Switch to light theme` + +ホバー時に表示されるライトモード切替のタイトルをカスタマイズします。 + +## darkModeSwitchTitle + +- 型: `string` +- 既定値: `Switch to dark theme` + +ホバー時に表示されるダークモード切替のタイトルをカスタマイズします。 + +## sidebarMenuLabel + +- 型: `string` +- 既定値: `Menu` + +サイドバーメニューのラベル(モバイル表示のみ)をカスタマイズします。 + +## returnToTopLabel + +- 型: `string` +- 既定値: `Return to top` + +トップに戻るボタンのラベル(モバイル表示のみ)をカスタマイズします。 + +## langMenuLabel + +- 型: `string` +- 既定値: `Change language` + +ナビバーの言語切替ボタンの aria-label をカスタマイズします。[i18n](../guide/i18n) を使う場合に有効です。 + +## skipToContentLabel + +- 型: `string` +- 既定値: `Skip to content` + +コンテンツへスキップリンクのラベルをカスタマイズします。キーボード操作時に表示されます。 + +## externalLinkIcon + +- 型: `boolean` +- 既定値: `false` + +Markdown 内の外部リンクの横に外部リンクアイコンを表示するかどうか。 + +## `useLayout` + +レイアウト関連のデータを返します。返り値の型は次のとおりです。 + + ```ts + interface { + isHome: ComputedRef + + sidebar: Readonly> + sidebarGroups: ComputedRef + hasSidebar: ComputedRef + isSidebarEnabled: ComputedRef + + hasAside: ComputedRef + leftAside: ComputedRef + + headers: Readonly> + hasLocalNav: ComputedRef + } + ``` + +**例:** + + ```vue + + + + ``` diff --git a/docs/ja/reference/default-theme-edit-link.md b/docs/ja/reference/default-theme-edit-link.md new file mode 100644 index 000000000000..035739442cb4 --- /dev/null +++ b/docs/ja/reference/default-theme-edit-link.md @@ -0,0 +1,60 @@ +# 編集リンク {#edit-link} + +## サイトレベルの設定 {#site-level-config} + +編集リンクは、GitHub や GitLab などの Git 管理サービスでそのページを編集できるリンクを表示します。有効化するには、設定に `themeConfig.editLink` オプションを追加します。 + + ```js + export default { + themeConfig: { + editLink: { + pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path' + } + } + } + ``` + +`pattern` オプションはリンクの URL 構造を定義します。`:path` はページパスに置き換えられます。 + +また、引数に [`PageData`](./runtime-api#usedata) を受け取り、URL 文字列を返す純粋関数を指定することもできます。 + + ```js + export default { + themeConfig: { + editLink: { + pattern: ({ filePath }) => { + if (filePath.startsWith('packages/')) { + return `https://github.com/acme/monorepo/edit/main/${filePath}` + } else { + return `https://github.com/acme/monorepo/edit/main/docs/${filePath}` + } + } + } + } + } + ``` + +この関数はブラウザでシリアライズされ実行されるため、副作用を持たず、スコープ外のものへアクセスしないでください。 + +既定では、ドキュメント下部に「Edit this page」というリンクテキストが表示されます。`text` オプションでこの文言をカスタマイズできます。 + + ```js + export default { + themeConfig: { + editLink: { + pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path', + text: 'GitHub でこのページを編集' + } + } + } + ``` + +## フロントマターでの設定 {#frontmatter-config} + +ページごとに無効化するには、フロントマターで `editLink` オプションを使用します。 + + ```yaml + --- + editLink: false + --- + ``` diff --git a/docs/ja/reference/default-theme-footer.md b/docs/ja/reference/default-theme-footer.md new file mode 100644 index 000000000000..f8226c89fadc --- /dev/null +++ b/docs/ja/reference/default-theme-footer.md @@ -0,0 +1,55 @@ +# フッター {#footer} + +`themeConfig.footer` を設定すると、ページ下部にグローバルフッターが表示されます。 + +```ts +export default { + themeConfig: { + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright © 2019-present Evan You' + } + } +} +``` + +```ts +export interface Footer { + // 著作権表示の直前に表示されるメッセージ + message?: string + + // 実際の著作権表記 + copyright?: string +} +``` + +上記の設定は HTML 文字列にも対応しています。たとえば、フッター内のテキストにリンクを含めたい場合は、次のように設定できます。 + +```ts +export default { + themeConfig: { + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright © 2019-present Evan You' + } + } +} +``` + +::: warning +`message` と `copyright` は `

` 要素内にレンダリングされるため、 +使用できるのはインライン要素のみです。ブロック要素を追加したい場合は、 +[`layout-bottom`](../guide/extending-default-theme#layout-slots) スロットの利用を検討してください。 +::: + +なお、[SideBar](./default-theme-sidebar) が表示されている場合はフッターは表示されません。 + +## フロントマターでの設定 {#frontmatter-config} + +ページ単位で無効化するには、フロントマターの `footer` オプションを使用します。 + +```yaml +--- +footer: false +--- +``` diff --git a/docs/ja/reference/default-theme-home-page.md b/docs/ja/reference/default-theme-home-page.md new file mode 100644 index 000000000000..e472a4785a66 --- /dev/null +++ b/docs/ja/reference/default-theme-home-page.md @@ -0,0 +1,188 @@ +# ホームページ {#home-page} + +VitePress のデフォルトテーマにはホームページ用レイアウトが用意されています([このサイトのトップページ](../) でも使われています)。[フロントマター](./frontmatter-config) に `layout: home` を指定すれば、任意のページで利用できます。 + +```yaml +--- +layout: home +--- +``` + +ただし、この指定だけでは多くのことは起きません。`hero` や `features` などの追加オプションを設定して、ホームページにあらかじめ用意された複数の「セクション」を配置できます。 + +## ヒーローセクション {#hero-section} + +ヒーローセクションはホームページの最上部に表示されます。設定例は次のとおりです。 + +```yaml +--- +layout: home + +hero: + name: VitePress + text: Vite & Vue powered static site generator. + tagline: 概要テキスト... + image: + src: /logo.png + alt: VitePress + actions: + - theme: brand + text: はじめる + link: /guide/what-is-vitepress + - theme: alt + text: GitHub で見る + link: https://github.com/vuejs/vitepress +--- +``` + +```ts +interface Hero { + // `text` の上に表示される短い文字列。ブランドカラーで表示。 + // 製品名のような短い文言を想定。 + name?: string + + // ヒーローセクションのメインテキスト。`h1` として出力。 + text: string + + // `text` の下に表示されるタグライン。 + tagline?: string + + // テキストとタグラインの横に表示する画像。 + image?: ThemeableImage + + // ヒーローに表示するアクションボタン。 + actions?: HeroAction[] +} + +type ThemeableImage = + | string + | { src: string; alt?: string } + | { light: string; dark: string; alt?: string } + +interface HeroAction { + // ボタンのカラーテーマ。既定は `brand`。 + theme?: 'brand' | 'alt' + + // ボタンのラベル。 + text: string + + // ボタンのリンク先。 + link: string + + // a 要素の target 属性。 + target?: string + + // a 要素の rel 属性。 + rel?: string +} +``` + +### name の色をカスタマイズする {#customizing-the-name-color} + +`name` にはブランドカラー(`--vp-c-brand-1`)が使われますが、`--vp-home-hero-name-color` 変数を上書きして色を変更できます。 + +```css +:root { + --vp-home-hero-name-color: blue; +} +``` + +さらに、`--vp-home-hero-name-background` を組み合わせると、`name` にグラデーションを適用できます。 + +```css +:root { + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff); +} +``` + +## フィーチャーセクション {#features-section} + +フィーチャーセクションでは、ヒーロー直下に任意の数の機能説明を並べられます。フロントマターに `features` オプションを指定して設定します。 + +各フィーチャーにはアイコン(絵文字または画像)を指定できます。アイコンが画像(svg, png, jpeg など)の場合は、**適切な幅・高さ** を指定してください。必要に応じて説明テキストや実サイズ、ライト/ダーク用の差し替えも指定できます。 + +```yaml +--- +layout: home + +features: + - icon: 🛠️ + title: いつでもシンプル&ミニマル + details: 概要テキスト... + - icon: + src: /cool-feature-icon.svg + title: もうひとつの便利機能 + details: 概要テキスト... + - icon: + dark: /dark-feature-icon.svg + light: /light-feature-icon.svg + title: さらに別の機能 + details: 概要テキスト... +--- +``` + +```ts +interface Feature { + // 各フィーチャーボックスに表示するアイコン。 + icon?: FeatureIcon + + // フィーチャーのタイトル。 + title: string + + // フィーチャーの詳細説明。 + details: string + + // フィーチャーをクリックしたときのリンク(内部・外部どちらも可)。 + // + // 例: `guide/reference/default-theme-home-page` や `https://example.com` + link?: string + + // フィーチャー内に表示するリンクテキスト。 + // `link` と併用するのが最適。 + // + // 例: `Learn more`, `Visit page` など + linkText?: string + + // `link` 用の rel 属性。 + // + // 例: `external` + rel?: string + + // `link` 用の target 属性。 + target?: string +} + +type FeatureIcon = + | string + | { src: string; alt?: string; width?: string; height: string } + | { + light: string + dark: string + alt?: string + width?: string + height: string + } +``` + +## Markdown コンテンツ {#markdown-content} + +`---` で区切るフロントマターの下に Markdown を書くだけで、ホームページに追加コンテンツを表示できます。 + +````md +--- +layout: home + +hero: + name: VitePress + text: Vite & Vue powered static site generator. +--- + +## はじめに + +`npx` を使えば、すぐに VitePress を始められます! + +```sh +npm init +npx vitepress init +``` diff --git a/docs/ja/reference/default-theme-last-updated.md b/docs/ja/reference/default-theme-last-updated.md new file mode 100644 index 000000000000..2c85f2a89d76 --- /dev/null +++ b/docs/ja/reference/default-theme-last-updated.md @@ -0,0 +1,46 @@ +# 最終更新日時 {#last-updated} + +ページ右下に、コンテンツの最終更新時刻を表示できます。有効化するには、設定に `lastUpdated` オプションを追加します。 + +::: info +VitePress は各ファイルの **直近の Git コミットのタイムスタンプ** を用いて「最終更新」を表示します。これを有効にするには、対象の Markdown ファイルが Git にコミットされている必要があります。 + +内部的には、各ファイルに対して `git log -1 --pretty="%ai"` を実行してタイムスタンプを取得します。すべてのページで同じ更新時刻が表示される場合、(CI 環境でよくある)**浅いクローン(shallow clone)** により Git の履歴が取得できていない可能性があります。 + +**GitHub Actions** での修正例は次のとおりです。 + +```yaml{4} +- name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 +``` + +他の CI/CD プラットフォームでも同様の設定が用意されています。 + +もしそのようなオプションが使えない場合は、`package.json` のビルドスクリプトで手動フェッチを前置してください。 + +```json +"docs:build": "git fetch --unshallow && vitepress build docs" +``` +::: + +## サイトレベルの設定 {#site-level-config} + +```js +export default { + lastUpdated: true +} +``` + +## フロントマターでの設定 {#frontmatter-config} + +ページ単位で無効化するには、フロントマターで `lastUpdated` を指定します。 + +```yaml +--- +lastUpdated: false +--- +``` + +より詳しくは [デフォルトテーマ: 最終更新](./default-theme-config#lastupdated) を参照してください。テーマレベルで truthy な値を設定すると、サイトまたはページで明示的に無効化しない限り、この機能は有効になります。 diff --git a/docs/ja/reference/default-theme-layout.md b/docs/ja/reference/default-theme-layout.md new file mode 100644 index 000000000000..e241d03ec4d1 --- /dev/null +++ b/docs/ja/reference/default-theme-layout.md @@ -0,0 +1,62 @@ +# レイアウト {#layout} + +ページの [フロントマター](./frontmatter-config) の `layout` オプションでページのレイアウトを選択できます。利用可能なレイアウトは `doc`、`page`、`home` の 3 種類です。何も指定しない場合は `doc` として扱われます。 + +```yaml +--- +layout: doc +--- +``` + +## Doc レイアウト {#doc-layout} + +`doc` は既定のレイアウトで、Markdown 全体を「ドキュメント」風にスタイリングします。コンテンツ全体を `vp-doc` という CSS クラスでラップし、その配下の要素にスタイルを適用します。 + +`p` や `h2` などほぼすべての汎用要素に特別なスタイルが当たります。そのため、Markdown 内にカスタム HTML を追加した場合も、これらのスタイルの影響を受ける点に注意してください。 + +また、以下のようなドキュメント特有の機能も提供します。これらはこのレイアウトでのみ有効になります。 + +- 編集リンク(Edit Link) +- 前後リンク(Prev / Next Link) +- アウトライン(Outline) +- [Carbon 広告](./default-theme-carbon-ads) + +## Page レイアウト {#page-layout} + +`page` は「ブランクページ」として扱われます。Markdown はパースされ、[Markdown 拡張](../guide/markdown) も `doc` と同様に機能しますが、既定のスタイルは適用されません。 + +このレイアウトでは、VitePress テーマにマークアップを干渉させず、すべてを自分でスタイルできます。独自のカスタムページを作成したい場合に便利です。 + +なお、このレイアウトでも、ページがサイドバー設定に一致する場合はサイドバーが表示されます。 + +## Home レイアウト {#home-layout} + +`home` はテンプレート化された「ホームページ」を生成します。このレイアウトでは、`hero` や `features` などの追加オプションでコンテンツをさらにカスタマイズできます。詳しくは [デフォルトテーマ: ホームページ](./default-theme-home-page) を参照してください。 + +## レイアウトなし {#no-layout} + +レイアウトを一切適用したくない場合は、フロントマターで `layout: false` を指定します。これは(既定でサイドバー/ナビバー/フッターなしの)完全にカスタマイズ可能なランディングページを作りたい場合に役立ちます。 + +## カスタムレイアウト {#custom-layout} + +カスタムレイアウトを使用することもできます。 + +```md +--- +layout: foo +--- +``` + +これは、コンテキストに登録された `foo` という名前のコンポーネントを探します。たとえば、`.vitepress/theme/index.ts` でグローバル登録できます。 + +```ts +import DefaultTheme from 'vitepress/theme' +import Foo from './Foo.vue' + +export default { + extends: DefaultTheme, + enhanceApp({ app }) { + app.component('foo', Foo) + } +} +``` diff --git a/docs/ja/reference/default-theme-nav.md b/docs/ja/reference/default-theme-nav.md new file mode 100644 index 000000000000..207bf9e918ab --- /dev/null +++ b/docs/ja/reference/default-theme-nav.md @@ -0,0 +1,215 @@ +# ナビゲーション {#nav} + +ナビはページ上部に表示されるナビゲーションバーです。サイトタイトル、グローバルメニューリンクなどを含みます。 + +## サイトタイトルとロゴ {#site-title-and-logo} + +既定では、ナビには [`config.title`](./site-config#title) の値が表示されます。ナビに表示する文字列を変更したい場合は、`themeConfig.siteTitle` にカスタム文字列を指定します。 + +```js +export default { + themeConfig: { + siteTitle: 'My Custom Title' + } +} +``` + +サイトのロゴがある場合は、画像へのパスを渡すと表示できます。ロゴは `public` 直下に配置し、絶対パスで指定してください。 + +```js +export default { + themeConfig: { + logo: '/my-logo.svg' + } +} +``` + +ロゴを追加すると、サイトタイトルと並んで表示されます。ロゴだけを表示したい場合は、`siteTitle` を `false` に設定してタイトル文字列を非表示にできます。 + +```js +export default { + themeConfig: { + logo: '/my-logo.svg', + siteTitle: false + } +} +``` + +ダーク/ライトモードでロゴを切り替えたり、`alt` 属性を付けたい場合は、ロゴにオブジェクトを渡すこともできます。詳細は [`themeConfig.logo`](./default-theme-config#logo) を参照してください。 + +## ナビゲーションリンク {#navigation-links} + +`themeConfig.nav` オプションでナビにリンクを追加できます。 + +```js +export default { + themeConfig: { + nav: [ + { text: 'Guide', link: '/guide' }, + { text: 'Config', link: '/config' }, + { text: 'Changelog', link: 'https://github.com/...' } + ] + } +} +``` + +`text` はナビに表示される文字列、`link` はクリック時に遷移するリンクです。内部リンクは `.md` 拡張子を付けず、必ず `/` で始めるようにしてください。 + +`link` には、[`PageData`](./runtime-api#usedata) を受け取ってパスを返す関数を指定することもできます。 + +ナビリンクはドロップダウンメニューにもできます。リンクオプションに `items` を設定してください。 + +```js +export default { + themeConfig: { + nav: [ + { text: 'Guide', link: '/guide' }, + { + text: 'Dropdown Menu', + items: [ + { text: 'Item A', link: '/item-1' }, + { text: 'Item B', link: '/item-2' }, + { text: 'Item C', link: '/item-3' } + ] + } + ] + } +} +``` + +なお、ドロップダウンのタイトル(上の例の `Dropdown Menu`)には `link` は設定できません。ドロップダウンを開くボタンになるためです。 + +さらに、ドロップダウン内を「セクション」に分けることもできます(入れ子の `items` を使います)。 + +```js +export default { + themeConfig: { + nav: [ + { text: 'Guide', link: '/guide' }, + { + text: 'Dropdown Menu', + items: [ + { + // セクションのタイトル + text: 'Section A Title', + items: [ + { text: 'Section A Item A', link: '...' }, + { text: 'Section B Item B', link: '...' } + ] + } + ] + }, + { + text: 'Dropdown Menu', + items: [ + { + // タイトルは省略することも可能 + items: [ + { text: 'Section A Item A', link: '...' }, + { text: 'Section B Item B', link: '...' } + ] + } + ] + } + ] + } +} +``` + +### リンクの「アクティブ」状態をカスタマイズ {#customize-link-s-active-state} + +現在のページが特定のパス配下にあるとき、該当するナビ項目がハイライトされます。一致させるパスをカスタマイズしたい場合は、`activeMatch` に **正規表現文字列** を指定します。 + +```js +export default { + themeConfig: { + nav: [ + // ユーザーが `/config/` 配下にいるときにアクティブになる + { + text: 'Guide', + link: '/guide', + activeMatch: '/config/' + } + ] + } +} +``` + +::: warning +`activeMatch` は正規表現 **オブジェクト** ではなく、**文字列** で指定してください。ビルド時のシリアライズの都合で `RegExp` は使用できません。 +::: + +### リンクの `target` と `rel` をカスタマイズ {#customize-link-s-target-and-rel-attributes} + +既定では、リンクが外部かどうかに応じて VitePress が `target` と `rel` を自動設定します。必要であれば明示的に指定することもできます。 + +```js +export default { + themeConfig: { + nav: [ + { + text: 'Merchandise', + link: 'https://www.thegithubshop.com/', + target: '_self', + rel: 'sponsored' + } + ] + } +} +``` + +## ソーシャルリン� {#social-links} + +[`socialLinks`](./default-theme-config#sociallinks) を参照してください。 + +## カスタムコンポーネント {#custom-components} + +`component` オプションを使って、ナビゲーションバーにカスタムコンポーネントを配置できます。`component` には Vue コンポーネント名を指定し、[Theme.enhanceApp](../guide/custom-theme#theme-interface) で **グローバル登録** しておく必要があります。 + +```js [.vitepress/config.js] +export default { + themeConfig: { + nav: [ + { + text: 'My Menu', + items: [ + { + component: 'MyCustomComponent', + // コンポーネントに渡す任意の props + props: { + title: 'My Custom Component' + } + } + ] + }, + { + component: 'AnotherCustomComponent' + } + ] + } +} +``` + +次に、コンポーネントをグローバル登録します。 + +```js [.vitepress/theme/index.js] +import DefaultTheme from 'vitepress/theme' + +import MyCustomComponent from './components/MyCustomComponent.vue' +import AnotherCustomComponent from './components/AnotherCustomComponent.vue' + +/** @type {import('vitepress').Theme} */ +export default { + extends: DefaultTheme, + enhanceApp({ app }) { + app.component('MyCustomComponent', MyCustomComponent) + app.component('AnotherCustomComponent', AnotherCustomComponent) + } +} +``` + +コンポーネントはナビゲーションバー内にレンダリングされます。VitePress は次の追加 props をコンポーネントに提供します。 + +- `screenMenu`: モバイルのナビメニュー内にあるかどうかを示す任意の boolean + +e2e テスト内の例は[こちら](https://github.com/vuejs/vitepress/tree/main/__tests__/e2e/.vitepress)を参照してください。 diff --git a/docs/ja/reference/default-theme-prev-next-links.md b/docs/ja/reference/default-theme-prev-next-links.md new file mode 100644 index 000000000000..7b15d699c128 --- /dev/null +++ b/docs/ja/reference/default-theme-prev-next-links.md @@ -0,0 +1,43 @@ +# 前/次リンク {#prev-next-links} + +ドキュメントのフッターに表示される「前のページ」「次のページ」のテキストとリンクをカスタマイズできます。サイドバーに表示しているタイトルとは別の文言を使いたい場合や、フッターを無効化したり、サイドバーに含まれていないページへリンクしたい場合に便利です。 + +## prev + +- 型: `string | false | { text?: string; link?: string }` + +- 詳細: + + 前のページへのリンクに表示するテキスト/リンクを指定します。フロントマターで設定しない場合は、サイドバー設定から自動推測されます。 + +- 例: + + - テキストだけをカスタマイズ: + + ```yaml + --- + prev: 'Get Started | Markdown' + --- + ``` + + - テキストとリンクの両方をカスタマイズ: + + ```yaml + --- + prev: + text: 'Markdown' + link: '/guide/markdown' + --- + ``` + + - 前のページを非表示にする: + + ```yaml + --- + prev: false + --- + ``` + +## next + +`prev` と同様ですが、次のページ用の設定です。 diff --git a/docs/ja/reference/default-theme-search.md b/docs/ja/reference/default-theme-search.md new file mode 100644 index 000000000000..e15de4ef3e41 --- /dev/null +++ b/docs/ja/reference/default-theme-search.md @@ -0,0 +1,451 @@ +--- +outline: deep +--- + +# 検索 {#search} + +## ローカル検索 {#local-search} + +VitePress は、[minisearch](https://github.com/lucaong/minisearch/) によるブラウザ内インデックスを使った曖昧一致の全文検索をサポートします。有効化するには、`.vitepress/config.ts` で `themeConfig.search.provider` を `'local'` に設定します。 + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local' + } + } +}) +``` + +表示例: + +![screenshot of the search modal](/search.png) + +代わりに [Algolia DocSearch](#algolia-search) や、次のコミュニティ製プラグインを使うこともできます。 + +- +- +- + +### i18n {#local-search-i18n} + +多言語検索を行う設定例です。 + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + locales: { + zh: { // 既定ロケールの文言も翻訳したい場合はこれを `root` に + translations: { + button: { + buttonText: '搜索', + buttonAriaLabel: '搜索' + }, + modal: { + displayDetails: '显示详细列表', + resetButtonTitle: '重置搜索', + backButtonTitle: '关闭搜索', + noResultsText: '没有结果', + footer: { + selectText: '选择', + selectKeyAriaLabel: '输入', + navigateText: '导航', + navigateUpKeyAriaLabel: '上箭头', + navigateDownKeyAriaLabel: '下箭头', + closeText: '关闭', + closeKeyAriaLabel: 'esc' + } + } + } + } + } + } + } + } +}) +``` + +### miniSearch のオプション {#mini-search-options} + +MiniSearch の設定例です。 + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + miniSearch: { + /** + * @type {Pick} + */ + options: { + /* ... */ + }, + /** + * @type {import('minisearch').SearchOptions} + * @default + * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } } + */ + searchOptions: { + /* ... */ + } + } + } + } + } +}) +``` + +詳しくは [MiniSearch のドキュメント](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html) を参照してください。 + +### コンテンツレンダラーのカスタマイズ {#custom-content-renderer} + +インデックス前に Markdown コンテンツをレンダリングする関数をカスタマイズできます。 + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + /** + * @param {string} src + * @param {import('vitepress').MarkdownEnv} env + * @param {import('markdown-it-async')} md + */ + async _render(src, env, md) { + // HTML 文字列を返す + } + } + } + } +}) +``` + +この関数はクライアント側のサイトデータからは除外されるため、Node.js の API を使用できます。 + +#### 例: 検索対象からページを除外する {#example-excluding-pages-from-search} + +フロントマターに `search: false` を追加すると、そのページを検索対象から除外できます。あるいは次のようにもできます。 + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + async _render(src, env, md) { + const html = await md.renderAsync(src, env) + if (env.frontmatter?.search === false) return '' + if (env.relativePath.startsWith('some/path')) return '' + return html + } + } + } + } +}) +``` + +::: warning 注意 +カスタムの `_render` 関数を提供する場合、`search: false` の処理は自分で行う必要があります。また、`env` は `md.renderAsync` の呼び出し前には完全ではないため、`frontmatter` などの任意プロパティのチェックはその後に行ってください。 +::: + +#### 例: コンテンツの変換 — 見出しアンカーを追加 {#example-transforming-content-adding-anchors} + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + async _render(src, env, md) { + const html = await md.renderAsync(src, env) + if (env.frontmatter?.title) + return await md.renderAsync(`# ${env.frontmatter.title}`) + html + return html + } + } + } + } +}) +``` + +## Algolia 検索 {#algolia-search} + +VitePress は [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch) によるサイト検索をサポートします。導入は公式のガイドを参照してください。`.vitepress/config.ts` では最低限次の設定が必要です。 + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'algolia', + options: { + appId: '...', + apiKey: '...', + indexName: '...' + } + } + } +}) +``` + +### i18n {#algolia-search-i18n} + +多言語検索の設定例です。 + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'algolia', + options: { + appId: '...', + apiKey: '...', + indexName: '...', + locales: { + zh: { + placeholder: '搜索文档', + translations: { + button: { + buttonText: '搜索文档', + buttonAriaLabel: '搜索文档' + }, + modal: { + searchBox: { + clearButtonTitle: '清除查询条件', + clearButtonAriaLabel: '清除查询条件', + closeButtonText: '关闭', + closeButtonAriaLabel: '关闭', + placeholderText: '搜索文档', + placeholderTextAskAi: '向 AI 提问:', + placeholderTextAskAiStreaming: '回答中...', + searchInputLabel: '搜索', + backToKeywordSearchButtonText: '返回关键字搜索', + backToKeywordSearchButtonAriaLabel: '返回关键字搜索' + }, + startScreen: { + recentSearchesTitle: '搜索历史', + noRecentSearchesText: '没有搜索历史', + saveRecentSearchButtonTitle: '保存至搜索历史', + removeRecentSearchButtonTitle: '从搜索历史中移除', + favoriteSearchesTitle: '收藏', + removeFavoriteSearchButtonTitle: '从收藏中移除', + recentConversationsTitle: '最近的对话', + removeRecentConversationButtonTitle: '从历史记录中删除对话' + }, + errorScreen: { + titleText: '无法获取结果', + helpText: '你可能需要检查你的网络连接' + }, + noResultsScreen: { + noResultsText: '无法找到相关结果', + suggestedQueryText: '你可以尝试查询', + reportMissingResultsText: '你认为该查询应该有结果?', + reportMissingResultsLinkText: '点击反馈' + }, + resultsScreen: { + askAiPlaceholder: '向 AI 提问: ' + }, + askAiScreen: { + disclaimerText: '答案由 AI 生成,可能不准确,请自行验证。', + relatedSourcesText: '相关来源', + thinkingText: '思考中...', + copyButtonText: '复制', + copyButtonCopiedText: '已复制!', + copyButtonTitle: '复制', + likeButtonTitle: '赞', + dislikeButtonTitle: '踩', + thanksForFeedbackText: '感谢你的反馈!', + preToolCallText: '搜索中...', + duringToolCallText: '搜索 ', + afterToolCallText: '已搜索' + }, + footer: { + selectText: '选择', + submitQuestionText: '提交问题', + selectKeyAriaLabel: 'Enter 键', + navigateText: '切换', + navigateUpKeyAriaLabel: '向上箭头', + navigateDownKeyAriaLabel: '向下箭头', + closeText: '关闭', + backToSearchText: '返回搜索', + closeKeyAriaLabel: 'Esc 键', + poweredByText: '搜索提供者' + } + } + } + } + } + } + } + } +}) +``` + +[これらのオプション](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) は上書きできます。詳細は Algolia の公式ドキュメントを参照してください。 + +### Algolia Ask AI のサポート {#ask-ai} + +**Ask AI** を有効にするには、`options` 内に `askAi` オプション(またはその一部)を指定します。 + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'algolia', + options: { + appId: '...', + apiKey: '...', + indexName: '...', + // askAi: "YOUR-ASSISTANT-ID" + // または + askAi: { + // 少なくとも Algolia から受け取った assistantId を指定 + assistantId: 'XXXYYY', + // 任意の上書き — 省略時は上位の appId/apiKey/indexName を再利用 + // apiKey: '...', + // appId: '...', + // indexName: '...' + } + } + } + } +}) +``` + +::: warning 注意 +キーワード検索を既定にして Ask AI を使わない場合は、`askAi` を指定しないでください。 +::: + +Ask AI UI の翻訳は `options.translations.modal.askAiScreen` と `options.translations.resultsScreen` にあります。すべてのキーは[型定義](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts)を参照してください。 + +### クローラー設定 {#crawler-config} + +このサイトで使用している設定を元にした例です。 + +```ts +new Crawler({ + appId: '...', + apiKey: '...', + rateLimit: 8, + startUrls: ['https://vitepress.dev/'], + renderJavaScript: false, + sitemaps: [], + exclusionPatterns: [], + ignoreCanonicalTo: false, + discoveryPatterns: ['https://vitepress.dev/**'], + schedule: 'at 05:10 on Saturday', + actions: [ + { + indexName: 'vitepress', + pathsToMatch: ['https://vitepress.dev/**'], + recordExtractor: ({ $, helpers }) => { + return helpers.docsearch({ + recordProps: { + lvl1: '.content h1', + content: '.content p, .content li', + lvl0: { + selectors: 'section.has-active div h2', + defaultValue: 'Documentation' + }, + lvl2: '.content h2', + lvl3: '.content h3', + lvl4: '.content h4', + lvl5: '.content h5' + }, + indexHeadings: true + }) + } + } + ], + initialIndexSettings: { + vitepress: { + attributesForFaceting: ['type', 'lang'], + attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'], + attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'], + attributesToSnippet: ['content:10'], + camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'], + searchableAttributes: [ + 'unordered(hierarchy_radio_camel.lvl0)', + 'unordered(hierarchy_radio.lvl0)', + 'unordered(hierarchy_radio_camel.lvl1)', + 'unordered(hierarchy_radio.lvl1)', + 'unordered(hierarchy_radio_camel.lvl2)', + 'unordered(hierarchy_radio.lvl2)', + 'unordered(hierarchy_radio_camel.lvl3)', + 'unordered(hierarchy_radio.lvl3)', + 'unordered(hierarchy_radio_camel.lvl4)', + 'unordered(hierarchy_radio.lvl4)', + 'unordered(hierarchy_radio_camel.lvl5)', + 'unordered(hierarchy_radio.lvl5)', + 'unordered(hierarchy_radio_camel.lvl6)', + 'unordered(hierarchy_radio.lvl6)', + 'unordered(hierarchy_camel.lvl0)', + 'unordered(hierarchy.lvl0)', + 'unordered(hierarchy_camel.lvl1)', + 'unordered(hierarchy.lvl1)', + 'unordered(hierarchy_camel.lvl2)', + 'unordered(hierarchy.lvl2)', + 'unordered(hierarchy_camel.lvl3)', + 'unordered(hierarchy.lvl3)', + 'unordered(hierarchy_camel.lvl4)', + 'unordered(hierarchy.lvl4)', + 'unordered(hierarchy_camel.lvl5)', + 'unordered(hierarchy.lvl5)', + 'unordered(hierarchy_camel.lvl6)', + 'unordered(hierarchy.lvl6)', + 'content' + ], + distinct: true, + attributeForDistinct: 'url', + customRanking: [ + 'desc(weight.pageRank)', + 'desc(weight.level)', + 'asc(weight.position)' + ], + ranking: [ + 'words', + 'filters', + 'typo', + 'attribute', + 'proximity', + 'exact', + 'custom' + ], + highlightPreTag: '', + highlightPostTag: '', + minWordSizefor1Typo: 3, + minWordSizefor2Typos: 7, + allowTyposOnNumericTokens: false, + minProximity: 1, + ignorePlurals: true, + advancedSyntax: true, + attributeCriteriaComputedByMinProximity: true, + removeWordsIfNoResults: 'allOptional' + } + } +}) +``` diff --git a/docs/ja/reference/default-theme-sidebar.md b/docs/ja/reference/default-theme-sidebar.md new file mode 100644 index 000000000000..ddd87383c881 --- /dev/null +++ b/docs/ja/reference/default-theme-sidebar.md @@ -0,0 +1,180 @@ +# サイドバー {#sidebar} + +サイドバーはドキュメントの主要なナビゲーションブロックです。[`themeConfig.sidebar`](./default-theme-config#sidebar) でメニューを設定できます。 + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Guide', + items: [ + { text: 'Introduction', link: '/introduction' }, + { text: 'Getting Started', link: '/getting-started' }, + ... + ] + } + ] + } +} +``` + +## 基本 {#the-basics} + +最もシンプルな構成は、リンクの配列を 1 つ渡す方法です。第 1 階層のアイテムがサイドバーの「セクション」を表します。各セクションは `text`(セクションのタイトル)と、実際のナビゲーションリンクである `items` を持ちます。 + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Section Title A', + items: [ + { text: 'Item A', link: '/item-a' }, + { text: 'Item B', link: '/item-b' }, + ... + ] + }, + { + text: 'Section Title B', + items: [ + { text: 'Item C', link: '/item-c' }, + { text: 'Item D', link: '/item-d' }, + ... + ] + } + ] + } +} +``` + +各 `link` は `/` で始まる実ファイルへのパスを指定します。リンクの末尾を `/` で終わらせると、対応するディレクトリの `index.md` が表示されます。 + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Guide', + items: [ + // `/guide/index.md` を表示 + { text: 'Introduction', link: '/guide/' } + ] + } + ] + } +} +``` + +サイドバーのアイテムは、ルートから数えて最大 6 階層まで入れ子にできます。7 階層以上は無視され、表示されません。 + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Level 1', + items: [ + { + text: 'Level 2', + items: [ + { + text: 'Level 3', + items: [ + ... + ] + } + ] + } + ] + } + ] + } +} +``` + +## 複数のサイドバー {#multiple-sidebars} + +ページのパスに応じて異なるサイドバーを表示できます。たとえば、このサイトのように「Guide」セクションと「Config」セクションでナビゲーションを分けたい場合に便利です。 + +まず、対象のセクションごとにディレクトリを分けてページを配置します。 + +``` +. +├─ guide/ +│ ├─ index.md +│ ├─ one.md +│ └─ two.md +└─ config/ + ├─ index.md + ├─ three.md + └─ four.md +``` + +次に、各セクション用のサイドバーを設定します。この場合、配列ではなくオブジェクトを渡します。 + +```js +export default { + themeConfig: { + sidebar: { + // ユーザーが `guide` ディレクトリ配下にいるときに表示 + '/guide/': [ + { + text: 'Guide', + items: [ + { text: 'Index', link: '/guide/' }, + { text: 'One', link: '/guide/one' }, + { text: 'Two', link: '/guide/two' } + ] + } + ], + + // ユーザーが `config` ディレクトリ配下にいるときに表示 + '/config/': [ + { + text: 'Config', + items: [ + { text: 'Index', link: '/config/' }, + { text: 'Three', link: '/config/three' }, + { text: 'Four', link: '/config/four' } + ] + } + ] + } + } +} +``` + +## 折りたたみ可能なサイドバーグループ {#collapsible-sidebar-groups} + +サイドバーグループに `collapsed` オプションを追加すると、各セクションの開閉トグルが表示されます。 + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Section Title A', + collapsed: false, + items: [...] + } + ] + } +} +``` + +既定ではすべてのセクションが「開いた」状態です。初回表示時に「閉じた」状態にしたい場合は、`collapsed` を `true` に設定します。 + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Section Title A', + collapsed: true, + items: [...] + } + ] + } +} +``` diff --git a/docs/ja/reference/default-theme-team-page.md b/docs/ja/reference/default-theme-team-page.md new file mode 100644 index 000000000000..5f02d4d0df3a --- /dev/null +++ b/docs/ja/reference/default-theme-team-page.md @@ -0,0 +1,255 @@ + + +# チームページ {#team-page} + +チームを紹介したい場合は、Team コンポーネント群を使ってチームページを構成できます。使い方は 2 通りあり、ドキュメントページに埋め込む方法と、専用のチームページを作成する方法があります。 + +## ページ内にメンバー一覧を表示する {#show-team-members-in-a-page} + +任意のページでチームメンバーの一覧を表示するには、`vitepress/theme` からエクスポートされている `` コンポーネントを使用します。 + +```html + + +# 私たちのチーム + +私たちの素晴らしいチームを紹介します。 + + +``` + +上記のように、カード風の要素でメンバーが表示されます。下図のような見た目になります。 + + + +`` コンポーネントには `small` と `medium` の 2 種類のサイズがあります。好みによりますが、ドキュメントページ内で使う場合は `small` が馴染みやすいことが多いでしょう。各メンバーに「説明文」や「スポンサー」ボタンなど、追加のプロパティを付けることもできます。詳細は [``](#vpteammembers) を参照してください。 + +小規模なチームで専用ページまでは不要な場合や、文脈上の参考として一部のメンバーのみを紹介したい場合は、ドキュメントページへ埋め込む方法が適しています。 + +メンバーが多い場合や、より広いスペースで紹介したい場合は、[専用のチームページを作成する](#専用のチームページを作成する) ことを検討してください。 + +## 専用のチームページを作成する {#create-a-full-team-page} + +ドキュメントページにメンバーを追加する代わりに、カスタムの [ホームページ](./default-theme-home-page) と同様、専用のチームページを作成することもできます。 + +まず新しい md ファイルを作成します。ファイル名は任意ですが、ここでは `team.md` とします。このファイルでフロントマターに `layout: page` を設定し、その後 `TeamPage` コンポーネント群を使ってページを構成します。 + +```html +--- +layout: page +--- + + + + + + + + + +``` + +専用のチームページを作る際は、必ずすべてのチーム関連コンポーネントを `` でラップしてください。レイアウトや余白などが適切に適用されます。 + +`` はページタイトルのセクションを追加します。タイトルは `

` 見出しになります。`#title` と `#lead` スロットでチームについて説明を書きましょう。 + +`` はドキュメントページで使う場合と同様に、メンバー一覧を表示します。 + +### セクションを追加してメンバーを分ける {#add-sections-to-divide-team-members} + +チームページに「セクション」を追加できます。たとえば、コアメンバーとコミュニティパートナーなど、役割ごとにメンバーを分けて説明しやすくできます。 + +そのためには、先ほど作成した `team.md` に `` コンポーネントを追加します。 + +```html +--- +layout: page +--- + + + + + + + + + + + + + + +``` + +`` は `VPTeamPageTitle` と同様に `#title` と `#lead` のスロットを持ち、さらにメンバー表示用の `#members` スロットを備えます。 + +`#members` スロット内に `` を配置するのを忘れないでください。 + +## `` + +`` コンポーネントは、与えられたメンバー配列を表示します。 + +```html + +``` + +```ts +interface Props { + // 各メンバーカードのサイズ。既定は `medium`。 + size?: 'small' | 'medium' + + // 表示するメンバー一覧。 + members: TeamMember[] +} + +interface TeamMember { + // メンバーのアバター画像 + avatar: string + + // メンバー名 + name: string + + // 名前の下に表示する肩書き(例: Developer, Software Engineer など) + title?: string + + // 所属組織名 + org?: string + + // 所属組織への URL + orgLink?: string + + // メンバーの説明 + desc?: string + + // ソーシャルリンク(例: GitHub, Twitter など) + // Social Links オブジェクトを渡せます。 + // 参照: https://vitepress.dev/reference/default-theme-config.html#sociallinks + links?: SocialLink[] + + // メンバーのスポンサー用 URL + sponsor?: string + + // スポンサーボタンのテキスト。既定は 'Sponsor' + actionText?: string +} +``` + +## `` + +専用のチームページを作成する際のルートコンポーネントです。単一のスロットのみを受け取り、渡されたチーム関連コンポーネント全体に適切なスタイルを適用します。 + +## `` + +ページの「タイトル」セクションを追加します。`` の直下に置くのが最適です。`#title` と `#lead` のスロットを受け取ります。 + +```html + + + + + + +``` + +## `` + +チームページ内に「セクション」を作成します。`#title`、`#lead`、`#members` の各スロットを受け取ります。`` の中に必要な数だけ追加できます。 + +```html + + ... + + + + + + +``` diff --git a/docs/ja/reference/frontmatter-config.md b/docs/ja/reference/frontmatter-config.md new file mode 100644 index 000000000000..e6b8b5ca16c6 --- /dev/null +++ b/docs/ja/reference/frontmatter-config.md @@ -0,0 +1,240 @@ +--- +outline: deep +--- + +# フロントマター設定 {#frontmatter-config} + +フロントマターはページ単位の設定を可能にします。各 Markdown ファイルで、サイト全体やテーマレベルの設定を上書きできます。フロントマターでしか定義できない項目もあります。 + +使用例: + +```md +--- +title: Docs with VitePress +editLink: true +--- +``` + +Vue の式内では、グローバル `$frontmatter` を介してフロントマターデータにアクセスできます。 + +```md +{{ $frontmatter.title }} +``` + +## title + +- 型: `string` + +ページのタイトルです。[config.title](./site-config#title) と同じ意味で、サイトレベルの設定を上書きします。 + +```yaml +--- +title: VitePress +--- +``` + +## titleTemplate + +- 型: `string | boolean` + +タイトルのサフィックスです。[config.titleTemplate](./site-config#titletemplate) と同じ意味で、サイトレベルの設定を上書きします。 + +```yaml +--- +title: VitePress +titleTemplate: Vite & Vue powered static site generator +--- +``` + +## description + +- 型: `string` + +ページの説明です。[config.description](./site-config#description) と同じ意味で、サイトレベルの設定を上書きします。 + +```yaml +--- +description: VitePress +--- +``` + +## head + +- 型: `HeadConfig[]` + +現在のページに追加で挿入する `` タグを指定します。サイトレベル設定で挿入されたタグの後に追加されます。 + +```yaml +--- +head: + - - meta + - name: description + content: hello + - - meta + - name: keywords + content: super duper SEO +--- +``` + +```ts +type HeadConfig = + | [string, Record] + | [string, Record, string] +``` + +## デフォルトテーマ専用 {#default-theme-only} + +以下のフロントマター項目は、デフォルトテーマ使用時にのみ適用されます。 + +### layout + +- 型: `doc | home | page` +- 既定値: `doc` + +ページのレイアウトを決めます。 + +- `doc` — Markdown コンテンツにドキュメント向けの既定スタイルを適用します。 +- `home` — 「ホームページ」用の特別なレイアウト。`hero` や `features` を追加指定して、ランディングページを素早く構築できます。 +- `page` — `doc` と似ていますが、コンテンツにスタイルを適用しません。完全にカスタムなページを作りたい場合に便利です。 + +```yaml +--- +layout: doc +--- +``` + +### hero + +`layout: home` のときのヒーローセクションの内容を定義します。詳しくは [デフォルトテーマ: ホームページ](./default-theme-home-page) を参照。 + +### features + +`layout: home` のときのフィーチャーセクションに表示する項目を定義します。詳しくは [デフォルトテーマ: ホームページ](./default-theme-home-page) を参照。 + +### navbar + +- 型: `boolean` +- 既定値: `true` + +[ナビゲーションバー](./default-theme-nav) を表示するかどうか。 + +```yaml +--- +navbar: false +--- +``` + +### sidebar + +- 型: `boolean` +- 既定値: `true` + +[サイドバー](./default-theme-sidebar) を表示するかどうか。 + +```yaml +--- +sidebar: false +--- +``` + +### aside + +- 型: `boolean | 'left'` +- 既定値: `true` + +`doc` レイアウトでの aside コンポーネントの位置を定義します。 + +この値を `false` にすると aside コンテナを表示しません。\ +`true` にすると右側に表示します。\ +`'left'` にすると左側に表示します。 + +```yaml +--- +aside: false +--- +``` + +### outline + +- 型: `number | [number, number] | 'deep' | false` +- 既定値: `2` + +ページのアウトラインに表示する見出しレベルです。[config.themeConfig.outline.level](./default-theme-config#outline) と同じ意味で、サイトレベルの設定を上書きします。 + +```yaml +--- +outline: [2, 4] +--- +``` + +### lastUpdated + +- 型: `boolean | Date` +- 既定値: `true` + +現在のページのフッターに[最終更新](./default-theme-last-updated)を表示するかどうか。日時を指定した場合は、その日時が Git の最終更新時刻の代わりに表示されます。 + +```yaml +--- +lastUpdated: false +--- +``` + +### editLink + +- 型: `boolean` +- 既定値: `true` + +現在のページのフッターに[編集リンク](./default-theme-edit-link)を表示するかどうか。 + +```yaml +--- +editLink: false +--- +``` + +### footer + +- 型: `boolean` +- 既定値: `true` + +[フッター](./default-theme-footer) を表示するかどうか。 + +```yaml +--- +footer: false +--- +``` + +### pageClass + +- 型: `string` + +特定のページに追加のクラス名を付与します。 + +```yaml +--- +pageClass: custom-page-class +--- +``` + +その後、`.vitepress/theme/custom.css` でこのページ専用のスタイルを記述できます。 + +```css +.custom-page-class { + /* ページ固有のスタイル */ +} +``` + +### isHome + +- 型: `boolean` + +デフォルトテーマは通常、`frontmatter.layout === 'home'` のチェックに基づいてホームページかどうかを判断します。\ +カスタムレイアウトでホームページ用の要素を強制的に表示したい場合に便利です。 + +```yaml +--- +isHome: true +--- +``` diff --git a/docs/ja/reference/runtime-api.md b/docs/ja/reference/runtime-api.md new file mode 100644 index 000000000000..b73b8503f3fd --- /dev/null +++ b/docs/ja/reference/runtime-api.md @@ -0,0 +1,173 @@ +# ランタイム API {#runtime-api} + +VitePress には、アプリのデータへアクセスするための組み込み API がいくつか用意されています。さらに、グローバルに使用できる組み込みコンポーネントも提供されています。 + +ヘルパーメソッドは `vitepress` からグローバルインポートでき、主にカスタムテーマの Vue コンポーネントで使われます。Markdown ファイルは Vue の [Single File Component](https://vuejs.org/guide/scaling-up/sfc.html) にコンパイルされるため、`.md` ファイル内でも使用できます。 + +`use*` で始まるメソッドは [Vue 3 Composition API](https://vuejs.org/guide/introduction.html#composition-api) の関数(Composable)で、`setup()` または ` + + +``` + +## `useRoute` + +現在のルートオブジェクトを返します。型は次のとおりです。 + +```ts +interface Route { + path: string + data: PageData + component: Component | null +} +``` + +## `useRouter` + +VitePress のルーターインスタンスを返し、プログラムで別ページへ遷移できます。 + +```ts +interface Router { + /** + * 現在のルート + */ + route: Route + /** + * 新しい URL へ遷移 + */ + go: (to?: string) => Promise + /** + * ルートが変わる前に呼ばれる。`false` を返すと遷移をキャンセル + */ + onBeforeRouteChange?: (to: string) => Awaitable + /** + * ページコンポーネントが読み込まれる前(履歴が更新された後)に呼ばれる。 + * `false` を返すと遷移をキャンセル + */ + onBeforePageLoad?: (to: string) => Awaitable + /** + * ページコンポーネントが読み込まれた後(更新前)に呼ばれる + */ + onAfterPageLoad?: (to: string) => Awaitable + /** + * ルートが変わった後に呼ばれる + */ + onAfterRouteChange?: (to: string) => Awaitable +} +``` + +## `withBase` + +- **型**: `(path: string) => string` + +設定された [`base`](./site-config#base) を指定の URL パスに付与します。[Base URL](../guide/asset-handling#base-url) も参照。 + +## `` + +レンダリング済みの Markdown コンテンツを表示します。[独自テーマの作成時](../guide/custom-theme) に便利です。 + +```vue + +``` + +## `` + +スロット内容をクライアント側でのみレンダリングします。 + +VitePress アプリは静的ビルド時に Node.js 上でサーバーレンダリングされるため、Vue の使用はユニバーサルコードの要件に従う必要があります。要するに、ブラウザ/DOM API へのアクセスは beforeMount / mounted フック内に限定してください。 + +SSR 非対応(例: カスタムディレクティブを含む)なコンポーネントを使用・デモする場合は、`ClientOnly` でラップできます。 + +```vue-html + + + +``` + +- 関連: [SSR 互換性](../guide/ssr-compat) + +## `$frontmatter` + +Vue の式内で現在ページの [フロントマター](../guide/frontmatter) に直接アクセスします。 + +```md +--- +title: Hello +--- + +# {{ $frontmatter.title }} +``` + +## `$params` + +Vue の式内で現在ページの [動的ルートのパラメータ](../guide/routing#dynamic-routes) に直接アクセスします。 + +```md +- package name: {{ $params.pkg }} +- version: {{ $params.version }} +``` diff --git a/docs/ja/reference/site-config.md b/docs/ja/reference/site-config.md new file mode 100644 index 000000000000..acea9ca7f009 --- /dev/null +++ b/docs/ja/reference/site-config.md @@ -0,0 +1,722 @@ +--- +outline: deep +--- + +# サイト設定 {#site-config} + +サイト設定では、サイト全体のグローバル設定を定義します。アプリ設定オプションは、使用するテーマに関係なく、すべての VitePress サイトに適用されます。たとえば、ベースディレクトリやサイトのタイトルなどです。 + +## 概要 {#overview} + +### 設定ファイルの解決 {#config-resolution} + +設定ファイルは常に `/.vitepress/config.[ext]` から解決されます。`` は VitePress の[プロジェクトルート](../guide/routing#root-and-source-directory)で、`[ext]` にはサポートされる拡張子が入ります。TypeScript はそのまま使えます。サポートされる拡張子は `.js`、`.ts`、`.mjs`、`.mts` です。 + +設定ファイルでは ES Modules 構文の使用を推奨します。設定オブジェクトをデフォルトエクスポートしてください。 + +```ts +export default { + // アプリレベルの設定 + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + ... +} +``` + +::: details 動的(非同期)設定 + +設定を動的に生成する必要がある場合は、関数をデフォルトエクスポートすることもできます。例: + +```ts +import { defineConfig } from 'vitepress' + +export default async () => { + const posts = await (await fetch('https://my-cms.com/blog-posts')).json() + + return defineConfig({ + // アプリレベル設定 + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + + // テーマレベル設定 + themeConfig: { + sidebar: [ + ...posts.map((post) => ({ + text: post.name, + link: `/posts/${post.name}` + })) + ] + } + }) +} +``` + +トップレベル `await` も使用できます。例: + +```ts +import { defineConfig } from 'vitepress' + +const posts = await (await fetch('https://my-cms.com/blog-posts')).json() + +export default defineConfig({ + // アプリレベル設定 + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + + // テーマレベル設定 + themeConfig: { + sidebar: [ + ...posts.map((post) => ({ + text: post.name, + link: `/posts/${post.name}` + })) + ] + } +}) +``` + +::: + +### 設定のインテリセンス {#config-intellisense} + +`defineConfig` ヘルパーを使うと、TypeScript による補完が効きます。対応 IDE であれば、JavaScript と TypeScript のどちらでも動作します。 + +```js +import { defineConfig } from 'vitepress' + +export default defineConfig({ + // ... +}) +``` + +### 型付きのテーマ設定 {#typed-theme-config} + +デフォルトでは、`defineConfig` はデフォルトテーマのテーマ設定型を想定します。 + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + // 型は `DefaultTheme.Config` + } +}) +``` + +カスタムテーマを使用しており、そのテーマ設定に型チェックを効かせたい場合は、代わりに `defineConfigWithTheme` を使い、ジェネリクスでカスタムテーマの設定型を渡してください。 + +```ts +import { defineConfigWithTheme } from 'vitepress' +import type { ThemeConfig } from 'your-theme' + +export default defineConfigWithTheme({ + themeConfig: { + // 型は `ThemeConfig` + } +}) +``` + +### Vite・Vue・Markdown の設定 {#vite-vue-markdown-config} + +- **Vite** + + Vite の設定は VitePress 設定の [vite](#vite) オプションで行えます。別途 Vite の設定ファイルを作る必要はありません。 + +- **Vue** + + VitePress には公式の Vue プラグイン([@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue))が同梱されています。オプションは VitePress 設定の [vue](#vue) から指定できます。 + +- **Markdown** + + 既定の [Markdown-It](https://github.com/markdown-it/markdown-it) インスタンスは、VitePress 設定の [markdown](#markdown) オプションでカスタマイズできます。 + +## サイトメタデータ {#site-metadata} + +### title + +- 型: `string` +- 既定値: `VitePress` +- ページ単位での上書き: [frontmatter](./frontmatter-config#title) + +サイトのタイトル。デフォルトテーマではナビバーに表示されます。 + +[`titleTemplate`](#titletemplate) を定義していない場合、個々のページタイトルの既定のサフィックスとしても使われます。各ページの最終タイトルは、そのページの最初の `

` 見出しのテキストに、グローバルの `title` をサフィックスとして結合したものになります。次の設定とページ内容の例: + +```ts +export default { + title: 'My Awesome Site' +} +``` + +```md +# Hello +``` + +このページのタイトルは `Hello | My Awesome Site` になります。 + +### titleTemplate + +- 型: `string | boolean` +- ページ単位での上書き: [frontmatter](./frontmatter-config#titletemplate) + +各ページタイトルのサフィックス、またはタイトル全体のカスタマイズができます。例: + +```ts +export default { + title: 'My Awesome Site', + titleTemplate: 'Custom Suffix' +} +``` + +```md +# Hello +``` + +このページのタイトルは `Hello | Custom Suffix` になります。 + +タイトルの描画方法を完全にカスタマイズするには、`titleTemplate` 内で `:title` シンボルを使います。 + +```ts +export default { + titleTemplate: ':title - Custom Suffix' +} +``` + +ここで `:title` はページ先頭の `

` から推論されたテキストに置き換えられます。先ほどの例では `Hello - Custom Suffix` になります。 + +`false` を設定するとタイトルのサフィックスを無効にできます。 + +### description + +- 型: `string` +- 既定値: `A VitePress site` +- ページ単位での上書き: [frontmatter](./frontmatter-config#description) + +サイトの説明。ページの HTML に `` タグとして出力されます。 + +```ts +export default { + description: 'A VitePress site' +} +``` + +### head + +- 型: `HeadConfig[]` +- 既定値: `[]` +- ページ単位での追加: [frontmatter](./frontmatter-config#head) + +ページ HTML の `` に追加で出力する要素。ユーザーが追加したタグは、VitePress のタグの後、`` の直前にレンダリングされます。 + +```ts +type HeadConfig = + | [string, Record] + | [string, Record, string] +``` + +#### 例: favicon を追加 {#example-adding-a-favicon} + +```ts +export default { + head: [['link', { rel: 'icon', href: '/favicon.ico' }]] +} // favicon.ico は public に配置。base を設定している場合は /base/favicon.ico を利用 + +/* 出力結果: + +*/ +``` + +#### 例: Google Fonts を追加 {#example-adding-google-fonts} + +```ts +export default { + head: [ + [ + 'link', + { rel: 'preconnect', href: 'https://fonts.googleapis.com' } + ], + [ + 'link', + { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' } + ], + [ + 'link', + { href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' } + ] + ] +} + +/* 出力結果: + + + +*/ +``` + +#### 例: Service Worker を登録 {#example-registering-a-service-worker} + +```ts +export default { + head: [ + [ + 'script', + { id: 'register-sw' }, + `;(() => { + if ('serviceWorker' in navigator) { + navigator.serviceWorker.register('/sw.js') + } + })()` + ] + ] +} + +/* 出力結果: + +*/ +``` + +#### 例: Google Analytics を使用 {#example-using-google-analytics} + +```ts +export default { + head: [ + [ + 'script', + { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' } + ], + [ + 'script', + {}, + `window.dataLayer = window.dataLayer || []; + function gtag(){dataLayer.push(arguments);} + gtag('js', new Date()); + gtag('config', 'TAG_ID');` + ] + ] +} + +/* 出力結果: + + +*/ +``` + +### lang + +- 型: `string` +- 既定値: `en-US` + +サイトの言語属性。ページ HTML の `` として出力されます。 + +```ts +export default { + lang: 'en-US' +} +``` + +### base + +- 型: `string` +- 既定値: `/` + +サイトをデプロイするベース URL。GitHub Pages などサブパス配下にデプロイする場合に設定が必要です。たとえば `https://foo.github.io/bar/` にデプロイする場合、`base` は `'/bar/'` にします。先頭と末尾は必ずスラッシュにしてください。 + +`/` で始まる他のオプション内の URL には、この `base` が自動的に付与されます。1 回設定すれば十分です。 + +```ts +export default { + base: '/base/' +} +``` + +## ルーティング {#routing} + +### cleanUrls + +- 型: `boolean` +- 既定値: `false` + +`true` にすると、URL の末尾の `.html` を削除します。あわせて [クリーン URL の生成](../guide/routing#generating-clean-url) も参照してください。 + +::: warning サーバ設定が必要 +ホスティング環境によっては追加の設定が必要です。`/foo` へのアクセス時に **リダイレクトなしで** `/foo.html` を返せるサーバ設定が必要です。 +::: + +### rewrites + +- 型: `Record` + +ディレクトリと URL のカスタム対応を定義します。詳しくは [ルーティング: ルートのリライト](../guide/routing#route-rewrites) を参照。 + +```ts +export default { + rewrites: { + 'source/:page': 'destination/:page' + } +} +``` + +## ビルド {#build} + +### srcDir + +- 型: `string` +- 既定値: `.` + +Markdown ページを置くディレクトリ(プロジェクトルートからの相対パス)。[ルートとソースディレクトリ](../guide/routing#root-and-source-directory) も参照。 + +```ts +export default { + srcDir: './src' +} +``` + +### srcExclude + +- 型: `string[]` +- 既定値: `undefined` + +ソースとして除外したい Markdown ファイルにマッチする [glob パターン](https://github.com/mrmlnc/fast-glob#pattern-syntax)。 + +```ts +export default { + srcExclude: ['**/README.md', '**/TODO.md'] +} +``` + +### outDir + +- 型: `string` +- 既定値: `./.vitepress/dist` + +ビルド出力先([プロジェクトルート](../guide/routing#root-and-source-directory) からの相対パス)。 + +```ts +export default { + outDir: '../public' +} +``` + +### assetsDir + +- 型: `string` +- 既定値: `assets` + +生成されるアセットを配置するサブディレクトリ名。パスは [`outDir`](#outdir) の内部で、相対解決されます。 + +```ts +export default { + assetsDir: 'static' +} +``` + +### cacheDir + +- 型: `string` +- 既定値: `./.vitepress/cache` + +キャッシュファイル用ディレクトリ([プロジェクトルート](../guide/routing#root-and-source-directory) からの相対パス)。参考: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir) + +```ts +export default { + cacheDir: './.vitepress/.vite' +} +``` + +### ignoreDeadLinks + +- 型: `boolean | 'localhostLinks' | (string | RegExp | ((link: string, source: string) => boolean))[]` +- 既定値: `false` + +`true` にすると、デッドリンクがあってもビルド失敗にしません。 + +`'localhostLinks'` にすると、`localhost` へのリンクはチェック対象外にしつつ、その他のデッドリンクではビルドを失敗させます。 + +```ts +export default { + ignoreDeadLinks: true +} +``` + +正確な URL 文字列、正規表現、カスタムフィルタ関数の配列として指定することもできます。 + +```ts +export default { + ignoreDeadLinks: [ + // 正確に "/playground" を無視 + '/playground', + // すべての localhost リンクを無視 + /^https?:\/\/localhost/, + // パスに "/repl/" を含むリンクを無視 + /\/repl\//, + // カスタム関数: "ignore" を含むリンクを無視 + (url) => { + return url.toLowerCase().includes('ignore') + } + ] +} +``` + +### metaChunk + +- 型: `boolean` +- 既定値: `false` + +`true` にすると、各ページのメタデータを初期 HTML にインラインせず、別の JavaScript チャンクに抽出します。これにより各ページの HTML ペイロードが小さくなり、メタデータをキャッシュ可能にすることで、多数のページがあるサイトでサーバ帯域を削減できます。 + +### mpa + +- 型: `boolean` +- 既定値: `false` + +`true` にすると、本番アプリは [MPA モード](../guide/mpa-mode) でビルドされます。MPA モードは既定でクライアント JavaScript を 0kb で配信する代わりに、クライアントサイドのナビゲーションを無効にし、相互作用には明示的な opt-in が必要です。 + +## テーマ関連 {#theming} + +### appearance + +- 型: `boolean | 'dark' | 'force-dark' | 'force-auto' | import('@vueuse/core').UseDarkOptions` +- 既定値: `true` + +ダークモードを有効にするか(`` に `.dark` クラスを付与)。 + +- `true` の場合、ユーザーの環境設定に従います。 +- `dark` の場合、ユーザーが切り替えない限りダークを既定にします。 +- `false` の場合、ユーザーはテーマを切り替えできません。 +- `'force-dark'` の場合、常にダークで固定(切替不可)。 +- `'force-auto'` の場合、常にユーザーの環境設定に従い(切替不可)。 + +このオプションは、ローカルストレージの `vitepress-theme-appearance` から設定を復元するインラインスクリプトを挿入します。これにより、ページ描画前に `.dark` クラスを適用してフリッカを防ぎます。 + +`appearance.initialValue` は `'dark' | undefined` のみサポート。Ref や getter は使えません。 + +### lastUpdated + +- 型: `boolean` +- 既定値: `false` + +Git を使って各ページの最終更新時刻を取得します。タイムスタンプは各ページのデータに含まれ、[`useData`](./runtime-api#usedata) から参照できます。 + +デフォルトテーマ使用時にこのオプションを有効にすると、各ページの最終更新時刻が表示されます。テキストは [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext) でカスタマイズ可能です。 + +## カスタマイズ {#customization} + +### markdown + +- 型: `MarkdownOption` + +Markdown パーサの設定。VitePress はパーサに [Markdown-it](https://github.com/markdown-it/markdown-it)、構文ハイライトに [Shiki](https://github.com/shikijs/shiki) を使用しています。必要に応じて Markdown 関連の各種オプションを指定できます。 + +```js +export default { + markdown: {...} +} +``` + +利用可能なオプションは [型定義と JSDoc](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) を参照してください。 + +### vite + +- 型: `import('vite').UserConfig` + +内部の Vite 開発サーバ/バンドラへ生の [Vite Config](https://vitejs.dev/config/) を渡します。 + +```js +export default { + vite: { + // Vite の設定 + } +} +``` + +### vue + +- 型: `import('@vitejs/plugin-vue').Options` + +内部の `@vitejs/plugin-vue` インスタンスへオプションをそのまま渡します。 + +```js +export default { + vue: { + // @vitejs/plugin-vue のオプション + } +} +``` + +## ビルドフック {#build-hooks} + +VitePress のビルドフックを使うと、サイトに機能や振る舞いを追加できます。 + +- サイトマップ +- 検索インデックス +- PWA +- Teleport + +### buildEnd + +- 型: `(siteConfig: SiteConfig) => Awaitable` + +`buildEnd` はビルド CLI フックです。ビルド(SSG)が完了した後、VitePress CLI プロセスが終了する前に実行されます。 + +```ts +export default { + async buildEnd(siteConfig) { + // ... + } +} +``` + +### postRender + +- 型: `(context: SSGContext) => Awaitable` + +`postRender` は SSG のレンダリング完了時に呼ばれるビルドフックです。SSG 中の teleport コンテンツの処理に利用できます。 + +```ts +export default { + async postRender(context) { + // ... + } +} +``` + +```ts +interface SSGContext { + content: string + teleports?: Record + [key: string]: any +} +``` + +### transformHead + +- 型: `(context: TransformContext) => Awaitable` + +`transformHead` は、各ページを生成する前に head を変換するためのビルドフックです。設定ファイルでは静的に追加できない head 要素を追加できます。追加分のみ返せば、既存のものと自動でマージされます。 + +::: warning +`context` 内の値は変更しないでください。 +::: + +```ts +export default { + async transformHead(context) { + // ... + } +} +``` + +```ts +interface TransformContext { + page: string // 例: index.md(srcDir からの相対) + assets: string[] // 解決済みの公開 URL(非 js/css アセット) + siteConfig: SiteConfig + siteData: SiteData + pageData: PageData + title: string + description: string + head: HeadConfig[] + content: string +} +``` + +このフックは静的サイト生成時のみ呼ばれ、開発中には呼ばれません。開発中に動的な head 要素を追加したい場合は、代わりに [`transformPageData`](#transformpagedata) を使用できます。 + +```ts +export default { + transformPageData(pageData) { + pageData.frontmatter.head ??= [] + pageData.frontmatter.head.push([ + 'meta', + { + name: 'og:title', + content: + pageData.frontmatter.layout === 'home' + ? `VitePress` + : `${pageData.title} | VitePress` + } + ]) + } +} +``` + +#### 例: 正規 URL の `` を追加 {#example-adding-a-canonical-url-link} + +```ts +export default { + transformPageData(pageData) { + const canonicalUrl = `https://example.com/${pageData.relativePath}` + .replace(/index\.md$/, '') + .replace(/\.md$/, '.html') + + pageData.frontmatter.head ??= [] + pageData.frontmatter.head.push([ + 'link', + { rel: 'canonical', href: canonicalUrl } + ]) + } +} +``` + +### transformHtml + +- 型: `(code: string, id: string, context: TransformContext) => Awaitable` + +`transformHtml` は、各ページの内容をディスクへ保存する前に変換するためのビルドフックです。 + +::: warning +`context` 内の値は変更しないでください。また、HTML を変更すると実行時のハイドレーション問題を引き起こす可能性があります。 +::: + +```ts +export default { + async transformHtml(code, id, context) { + // ... + } +} +``` + +### transformPageData + +- 型: `(pageData: PageData, context: TransformPageContext) => Awaitable | { [key: string]: any } | void>` + +`transformPageData` は各ページの `pageData` を変換するためのフックです。`pageData` を直接変更するか、変更値を返してマージさせることができます。 + +::: warning +`context` 内の値は変更しないでください。ネットワークリクエストや重い計算(画像生成など)を行うと開発サーバのパフォーマンスに影響します。`process.env.NODE_ENV === 'production'` を用いた条件分岐を検討してください。 +::: + +```ts +export default { + async transformPageData(pageData, { siteConfig }) { + pageData.contributors = await getPageContributors(pageData.relativePath) + } + + // あるいはマージ用の値を返す + async transformPageData(pageData, { siteConfig }) { + return { + contributors: await getPageContributors(pageData.relativePath) + } + } +} +``` + +```ts +interface TransformPageContext { + siteConfig: SiteConfig +} +``` diff --git a/docs/lunaria.config.json b/docs/lunaria.config.json index 4f93f4dca566..2de958b9e743 100644 --- a/docs/lunaria.config.json +++ b/docs/lunaria.config.json @@ -44,6 +44,10 @@ { "label": "فارسی", "lang": "fa" + }, + { + "label": "日本語", + "lang": "ja" } ], "outDir": ".vitepress/dist/_translations",