From 0233972a2feec14b095500928d61680a65c4692f Mon Sep 17 00:00:00 2001 From: Kenzo-Wada Date: Thu, 2 Oct 2025 11:28:47 +0900 Subject: [PATCH 1/7] i18n(ja): add japanese guide pages --- docs/ja/config.ts | 225 ++++ docs/ja/guide/asset-handling.md | 66 ++ docs/ja/guide/cms.md | 56 + docs/ja/guide/custom-theme.md | 212 ++++ docs/ja/guide/data-loading.md | 210 ++++ docs/ja/guide/deploy.md | 343 ++++++ docs/ja/guide/extending-default-theme.md | 332 ++++++ docs/ja/guide/frontmatter.md | 48 + docs/ja/guide/getting-started.md | 197 ++++ docs/ja/guide/i18n.md | 111 ++ docs/ja/guide/markdown.md | 1040 +++++++++++++++++ docs/ja/guide/migration-from-vitepress-0.md | 23 + docs/ja/guide/migration-from-vuepress.md | 33 + docs/ja/guide/mpa-mode.md | 23 + docs/ja/guide/routing.md | 385 ++++++ docs/ja/guide/sitemap-generation.md | 58 + docs/ja/guide/ssr-compat.md | 135 +++ docs/ja/guide/using-vue.md | 288 +++++ docs/ja/guide/what-is-vitepress.md | 57 + docs/ja/index.md | 35 + docs/ja/reference/cli.md | 73 ++ docs/ja/reference/default-theme-badge.md | 69 ++ docs/ja/reference/default-theme-carbon-ads.md | 22 + docs/ja/reference/default-theme-config.md | 494 ++++++++ docs/ja/reference/default-theme-edit-link.md | 60 + docs/ja/reference/default-theme-footer.md | 53 + docs/ja/reference/default-theme-home-page.md | 195 ++++ .../reference/default-theme-last-updated.md | 46 + docs/ja/reference/default-theme-layout.md | 62 + docs/ja/reference/default-theme-nav.md | 216 ++++ .../default-theme-prev-next-links.md | 43 + docs/ja/reference/default-theme-search.md | 451 +++++++ docs/ja/reference/default-theme-sidebar.md | 182 +++ docs/ja/reference/default-theme-team-page.md | 256 ++++ docs/ja/reference/frontmatter-config.md | 240 ++++ docs/ja/reference/runtime-api.md | 173 +++ docs/ja/reference/site-config.md | 722 ++++++++++++ docs/lunaria.config.json | 4 + 38 files changed, 7238 insertions(+) create mode 100644 docs/ja/config.ts create mode 100644 docs/ja/guide/asset-handling.md create mode 100644 docs/ja/guide/cms.md create mode 100644 docs/ja/guide/custom-theme.md create mode 100644 docs/ja/guide/data-loading.md create mode 100644 docs/ja/guide/deploy.md create mode 100644 docs/ja/guide/extending-default-theme.md create mode 100644 docs/ja/guide/frontmatter.md create mode 100644 docs/ja/guide/getting-started.md create mode 100644 docs/ja/guide/i18n.md create mode 100644 docs/ja/guide/markdown.md create mode 100644 docs/ja/guide/migration-from-vitepress-0.md create mode 100644 docs/ja/guide/migration-from-vuepress.md create mode 100644 docs/ja/guide/mpa-mode.md create mode 100644 docs/ja/guide/routing.md create mode 100644 docs/ja/guide/sitemap-generation.md create mode 100644 docs/ja/guide/ssr-compat.md create mode 100644 docs/ja/guide/using-vue.md create mode 100644 docs/ja/guide/what-is-vitepress.md create mode 100644 docs/ja/index.md create mode 100644 docs/ja/reference/cli.md create mode 100644 docs/ja/reference/default-theme-badge.md create mode 100644 docs/ja/reference/default-theme-carbon-ads.md create mode 100644 docs/ja/reference/default-theme-config.md create mode 100644 docs/ja/reference/default-theme-edit-link.md create mode 100644 docs/ja/reference/default-theme-footer.md create mode 100644 docs/ja/reference/default-theme-home-page.md create mode 100644 docs/ja/reference/default-theme-last-updated.md create mode 100644 docs/ja/reference/default-theme-layout.md create mode 100644 docs/ja/reference/default-theme-nav.md create mode 100644 docs/ja/reference/default-theme-prev-next-links.md create mode 100644 docs/ja/reference/default-theme-search.md create mode 100644 docs/ja/reference/default-theme-sidebar.md create mode 100644 docs/ja/reference/default-theme-team-page.md create mode 100644 docs/ja/reference/frontmatter-config.md create mode 100644 docs/ja/reference/runtime-api.md create mode 100644 docs/ja/reference/site-config.md 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..38e9b3eacc18 --- /dev/null +++ b/docs/ja/guide/asset-handling.md @@ -0,0 +1,66 @@ +# アセットの取り扱い + +## 静的アセットの参照 + +すべての 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 ディレクトリ + +Markdown やテーマコンポーネントで直接参照されない静的アセットを提供する必要がある場合や、特定のファイルをオリジナルのファイル名のまま提供したい場合があります。 +例えば `robots.txt`、favicon、PWA 用アイコンなどです。 + +これらのファイルは [ソースディレクトリ](./routing#source-directory) 配下の `public` ディレクトリに配置できます。たとえばプロジェクトルートが `./docs` で、デフォルトのソースディレクトリを使用している場合、`public` ディレクトリは `./docs/public` になります。 + +`public` に配置されたアセットは、出力ディレクトリのルートにそのままコピーされます。 + +なお、`public` 内のファイルはルート絶対パスで参照する必要があります。例えば `public/icon.png` は常に `/icon.png` として参照しなければなりません。 + +## ベース 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..f13169448ffe --- /dev/null +++ b/docs/ja/guide/cms.md @@ -0,0 +1,56 @@ +--- +outline: deep +--- + +# CMS との接続 + +## 全体のワークフロー + +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 }} が作成 + + + ``` + +## 連携ガイドの募集 + +特定の 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..eec1a1e3d662 --- /dev/null +++ b/docs/ja/guide/custom-theme.md @@ -0,0 +1,212 @@ +# カスタムテーマを使う + +## テーマの解決 + +カスタムテーマを有効にするには、`.vitepress/theme/index.js` または `.vitepress/theme/index.ts` ファイル（「テーマエントリファイル」）を作成します。 + +``` +. +├─ docs # プロジェクトルート +│ ├─ .vitepress +│ │ ├─ theme +│ │ │ └─ index.js # テーマエントリ +│ │ └─ config.js # 設定ファイル +│ └─ index.md +└─ package.json +``` + +VitePress はテーマエントリファイルを検出すると、常にデフォルトテーマではなくカスタムテーマを使用します。ただし、[デフォルトテーマを拡張](./extending-default-theme) してその上で高度なカスタマイズを行うことも可能です。 + +## テーマインターフェース + +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) である必要があります。 + +## レイアウトの構築 + +最も基本的なレイアウトコンポーネントには [``](../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) を活用すれば、ブログ記事一覧ページのようなデータ駆動型のレイアウトも実現できます。 + +## カスタムテーマの配布 + +最も簡単な配布方法は [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. テーマの利用方法を明確に説明する（以下を参照）。 + +## カスタムテーマの利用 + +外部テーマを利用するには、カスタムテーマエントリからインポートして再エクスポートします。 + +```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..971078692e27 --- /dev/null +++ b/docs/ja/guide/data-loading.md @@ -0,0 +1,210 @@ +# ビルド時のデータの読み込み + +VitePress には **データローダー (data loaders)** という機能があり、任意のデータを読み込み、ページやコンポーネントからインポートすることができます。データの読み込みは **ビルド時のみ** 実行され、最終的な JavaScript バンドルには JSON としてシリアライズされたデータが含まれます。 + +データローダーはリモートデータの取得や、ローカルファイルに基づいたメタデータの生成に利用できます。たとえば、ローカルの API ページをすべて解析して API エントリのインデックスを自動生成するといったことが可能です。 + +## 基本的な使い方 + +データローダーファイルは `.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() + } +} +``` + +## ローカルファイルからのデータ + +ローカルファイルに基づいたデータを生成する必要がある場合は、データローダー内で `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 + + + +``` + +### オプション + +デフォルトデータが要件に合わない場合は、オプションで変換処理を追加できます。 + +```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 +} +``` + +## 型付きデータローダー + +TypeScript を使用する場合は、ローダーと `data` エクスポートを型付けできます。 + +```ts +import { defineLoader } from 'vitepress' + +export interface Data { + // データ型 +} + +declare const data: Data +export { data } + +export default defineLoader({ + watch: ['...'], + async load(): Promise { + // ... + } +}) +``` + +## 設定情報の取得 + +ローダー内で設定情報を取得するには次のようにします。 + +```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..95cc030a0ff4 --- /dev/null +++ b/docs/ja/guide/deploy.md @@ -0,0 +1,343 @@ +--- +outline: deep +--- + +# VitePress サイトをデプロイする + +以下のガイドは、次の前提に基づいています。 + +- VitePress のサイトはプロジェクトの `docs` ディレクトリ内にある。 +- デフォルトのビルド出力ディレクトリ（`.vitepress/dist`）を使用している。 +- VitePress はプロジェクトのローカル依存としてインストールされており、`package.json` に次のスクリプトが設定されている。 + +```json [package.json] + { + "scripts": { + "docs:build": "vitepress build docs", + "docs:preview": "vitepress preview docs" + } + } +``` + +## ローカルでビルドしてテストする + +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` でサーバーを起動します。 + +## 公開ベースパスの設定 + +デフォルトでは、サイトはドメインのルートパス（`/`）にデプロイされることを想定しています。サイトをサブパス、例：`https://mywebsite.com/blog/` で配信する場合は、VitePress の設定で [`base`](../reference/site-config#base) オプションを `'/blog/'` に設定してください。 + +**例:** GitHub（または GitLab）Pages に `user.github.io/repo/` としてデプロイするなら、`base` を `/repo/` に設定します。 + +## HTTP キャッシュヘッダー + +本番サーバーの 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) + +::: + +## プラットフォーム別ガイド + +### 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 + +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 + +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 + +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 + +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 + +1. `npm run docs:build` の後、次のコマンドでデプロイします。 + + ```sh + npx surge docs/.vitepress/dist + ``` + +### 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 + +[Creating and Deploying a VitePress App To Edgio](https://docs.edg.io/guides/vitepress) を参照してください。 + +### Kinsta Static Site Hosting + +[VitePress](https://kinsta.com/static-site-hosting/) を [こちらの手順](https://kinsta.com/docs/vitepress-static-site-example/) に従ってデプロイできます。 + +### Stormkit + +[VitePress プロジェクトを Stormkit にデプロイ](https://stormkit.io/blog/how-to-deploy-vitepress) する手順を参照してください。 + +### CloudRay + +[CloudRay](https://cloudray.io/) でのデプロイ方法は [こちらの手順](https://cloudray.io/articles/how-to-deploy-vitepress-site) を参照してください。 + +### 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..8381bb119858 --- /dev/null +++ b/docs/ja/guide/extending-default-theme.md @@ -0,0 +1,332 @@ +--- +outline: deep +--- + +# デフォルトテーマの拡張 + +VitePress のデフォルトテーマはドキュメント向けに最適化されており、カスタマイズ可能です。利用できるオプションの一覧は [デフォルトテーマの概要](../reference/default-theme-config) を参照してください。 + +しかし、設定だけでは不十分なケースもあります。例えば: + +1. CSS のスタイルを微調整したい +2. グローバルコンポーネントの登録など、Vue アプリインスタンスを変更したい +3. レイアウトのスロット経由でテーマに独自コンテンツを挿入したい + +これらの高度なカスタマイズには、デフォルトテーマを「拡張」するカスタムテーマを使用する必要があります。 + +::: tip +先に [カスタムテーマの使用](./custom-theme) を読み、カスタムテーマの仕組みを理解してから進めてください。 +::: + +## 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) を参照してください。 + +## フォントを変更する + +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: '' + } + ] + ] + } + } +} +``` + +## グローバルコンポーネントの登録 + +```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) を利用してディレクトリ内のコンポーネントを自動登録することもできます。 + +## レイアウトスロット + +デフォルトテーマの `` コンポーネントには、ページ内の特定の位置にコンテンツを挿入するためのスロットがいくつか用意されています。以下は、アウトラインの前にコンポーネントを挿入する例です。 + +```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 の利用 + +### 外観切り替え時（ライト/ダーク） + +カラーモード切り替え時にカスタムトランジションを提供するよう、デフォルトテーマを拡張できます。例: + +```vue [.vitepress/theme/Layout.vue] + + + + + +``` + +結果（**注意！**：点滅や急な動き、明るい光を含みます）: + +
+デモ + +![Appearance Toggle Transition Demo](/appearance-toggle-transition.webp) + +
+ +詳細は [Chrome Docs](https://developer.chrome.com/docs/web-platform/view-transitions/) を参照してください。 + +### ルート遷移時 + +近日公開。 + +## 内部コンポーネントの置き換え + +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..3350e8790d30 --- /dev/null +++ b/docs/ja/guide/frontmatter.md @@ -0,0 +1,48 @@ +# フロントマター + +## 使い方 + +VitePress はすべての Markdown ファイルで YAML フロントマターをサポートしており、[gray-matter](https://github.com/jonschlinkert/gray-matter) で解析します。フロントマターは Markdown ファイルの先頭（` + + +``` + +## RTL サポート（実験的） + +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..6a7e80abdfc3 --- /dev/null +++ b/docs/ja/guide/markdown.md @@ -0,0 +1,1040 @@ +# Markdown 拡張 + +VitePress には組み込みの Markdown 拡張機能が用意されています。 + +## 見出しアンカー + +見出しには自動的にアンカーリンクが付与されます。アンカーのレンダリングは `markdown.anchor` オプションで設定できます。 + +### カスタムアンカー + +自動生成ではなく任意のアンカーを指定したい場合は、見出しの末尾にサフィックスを追加します。 + + ```md + # カスタムアンカーを使う {#my-anchor} + ``` + +これにより、デフォルトの `#using-custom-anchors` ではなく `#my-anchor` でその見出しにリンクできます。 + +## リンク + +内部リンクと外部リンクは特別に処理されます。 + +### 内部リンク + +内部リンクは 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) + ``` + +### ページサフィックス + +ページと内部リンクはデフォルトで `.html` サフィックス付きで生成されます。 + +### 外部リンク + +外部リンクには自動的に `target="_blank" rel="noreferrer"` が付与されます。 + +- [vuejs.org](https://vuejs.org) +- [VitePress on GitHub](https://github.com/vuejs/vitepress) + +## フロントマター + +[YAML フロントマター](https://jekyllrb.com/docs/front-matter/) をそのままサポートしています。 + + ```yaml + --- + title: ハッカーのようにブログを書く + lang: ja-JP + --- + ``` + +このデータはページ内や、カスタム／テーマコンポーネントからも利用できます。詳しくは [Frontmatter](../reference/frontmatter-config) を参照してください。 + +## GitHub 風テーブル + +**入力** + + ```md + | テーブル | は | クール | + | -------------- | :---------: | ------: | + | 3列目は | 右寄せ | $1600 | + | 2列目は | 中央 | $12 | + | シマ模様 | neat です | $1 | + ``` + +**出力** + +| テーブル | は | クール | +| -------- | :----: | ------: | +| 3列目は | 右寄せ | \$1600 | +| 2列目は | 中央 | \$12 | +| シマ模様 | neatです | \$1 | + +## 絵文字 :tada: + +**入力** + + ``` + :tada: :100: + ``` + +**出力** + +:tada: :100: + +すべての絵文字の [一覧はこちら](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs)。 + +## 目次 + +**入力** + + ``` + [[toc]] + ``` + +**出力** + +[[toc]] + +TOC のレンダリングは `markdown.toc` オプションで設定できます。 + +## カスタムコンテナ + +タイプ、タイトル、内容を指定してカスタムコンテナを定義できます。 + +### デフォルトタイトル + +**入力** + + ```md + ::: info + これは情報ボックスです。 + ::: + + ::: tip + これはヒントです。 + ::: + + ::: warning + これは警告です。 + ::: + + ::: danger + これは危険の警告です。 + ::: + + ::: details + これは詳細ブロックです。 + ::: + ``` + +**出力** + +::: info +これは情報ボックスです。 +::: + +::: tip +これはヒントです。 +::: + +::: warning +これは警告です。 +::: + +::: danger +これは危険の警告です。 +::: + +::: details +これは詳細ブロックです。 +::: + +### カスタムタイトル + +コンテナの「タイプ」の直後に文字列を追加することで、タイトルをカスタマイズできます。 + +**入力** + + ````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: '詳細' + } + } + // ... + }) + ``` + +### 追加属性 + +カスタムコンテナには追加の属性を付与できます。この機能には [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 形式のアラート + +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] + > 行動による望ましくない結果の可能性です。 + + +## コードブロックのシンタックスハイライト + +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) で行えます。 + +## コードブロックの行ハイライト + +**入力** + + ```` + ```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] + } + } + } + ``` + +## コードブロックでのフォーカス + +`// [!code focus]` コメントを行に付けると、その行にフォーカスし、他の部分がぼかされます。 + +また、`// [!code focus:]` を使ってフォーカスする行数を指定することもできます。 + +**入力** + + ```` + ```js + export default { + data () { + return { + msg: 'フォーカス！' // [!!code focus] + } + } + } + ``` + ```` + +**出力** + +```js +export default { + data() { + return { + msg: 'フォーカス！' // [!code focus] + } + } +} +``` + +## コードブロックのカラー差分表示 + +`// [!code --]` または `// [!code ++]` コメントを行に付けると、その行に差分（削除/追加）スタイルを適用できます。コードブロックの色付けは維持されます。 + +**入力** + + ```` + ```js + export default { + data () { + return { + msg: 'Removed' // [!!code --] + msg: 'Added' // [!!code ++] + } + } + } + ``` + ```` + +**出力** + +```js +export default { + data () { + return { + msg: 'Removed' // [!code --] + msg: 'Added' // [!code ++] + } + } +} +``` + +## コードブロック内のエラー/警告表示 + +行に `// [!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' + ``` + +## コードスニペットのインポート + +既存ファイルから、次の構文でコードスニペットをインポートできます： + + ```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} + ``` + +これは、ファイル拡張子からソース言語を推論できない場合に有用です。 + +## コードグループ + +複数のコードブロックを、次のようにグループ化できます。 + +**入力** + + ````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 ファイルの中に、別の 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 + + ``` + +## 数式 + +この機能はオプトインです。利用するには `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$ | _え？_ | + +## 画像の遅延読み込み + +Markdown で追加した各画像に対して遅延読み込みを有効化するには、設定ファイルで `lazyLoading` を `true` にします： + + ```js + export default { + markdown: { + image: { + // 既定では画像の遅延読み込みは無効 + lazyLoading: true + } + } + } + ``` + +## 高度な設定 + +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/migration-from-vitepress-0.md b/docs/ja/guide/migration-from-vitepress-0.md new file mode 100644 index 000000000000..cb04c52a046d --- /dev/null +++ b/docs/ja/guide/migration-from-vitepress-0.md @@ -0,0 +1,23 @@ +# VitePress 0.x からの移行 + +VitePress 0.x をお使いの場合、新機能や強化に伴ういくつかの破壊的変更があります。ここでは最新の VitePress へアプリを移行する際の手順を説明します。 + +## アプリ設定 + +- 国際化機能（i18n）はまだ実装されていません。 + +## テーマ設定 + +- `sidebar` オプションの構造が変わりました。 + - `children` キーは `items` に名称変更されました。 + - ルート直下の項目に現在は `link` を含められません。将来的に再導入予定です。 +- `repo`, `repoLabel`, `docsDir`, `docsBranch`, `editLinks`, `editLinkText` は、より柔軟な API に置き換えられて削除されました。 + - ナビゲーションにアイコン付きの GitHub リンクを追加するには、[ソーシャルリンク](../reference/default-theme-nav#navigation-links) を使用してください。 + - 「このページを編集」リンクを追加するには、[編集リンク](../reference/default-theme-edit-link) を使用してください。 +- `lastUpdated` オプションは `config.lastUpdated` と `themeConfig.lastUpdatedText` に分割されました。 +- `carbonAds.carbon` は `carbonAds.code` に変更されました。 + +## フロントマター設定 + +- `home: true` は `layout: home` に変更されました。あわせてホームページ関連の設定が拡張され、多くが変更されています。詳細は [ホームページのガイド](../reference/default-theme-home-page) を参照してください。 +- `footer` オプションは [`themeConfig.footer`](../reference/default-theme-config#footer) に移動しました。 diff --git a/docs/ja/guide/migration-from-vuepress.md b/docs/ja/guide/migration-from-vuepress.md new file mode 100644 index 000000000000..12add2b2e05e --- /dev/null +++ b/docs/ja/guide/migration-from-vuepress.md @@ -0,0 +1,33 @@ +# VuePress からの移行 + +## 設定 + +### サイドバー + +サイドバーはフロントマターから自動生成されなくなりました。サイドバーを動的に生成するには、[自分でフロントマターを読み取り](https://github.com/vuejs/vitepress/issues/572#issuecomment-1170116225)、項目を構築してください。将来的に、[この用途のユーティリティ](https://github.com/vuejs/vitepress/issues/96) が提供される可能性があります。 + +## Markdown + +### 画像 + +VuePress と異なり、VitePress では静的画像を使用する場合、設定の [`base`](./asset-handling#base-url) を自動的に処理します。 + +そのため、`img` タグを使わずに画像をレンダリングできます。 + + ```diff + - foo + + ![foo](/foo.png) + ``` + +::: warning +動的な画像については、[ベース URL のガイド](./asset-handling#base-url) にあるとおり、引き続き `withBase` が必要です。 +::: + +すべての `img` タグを `![](...)` 構文へ置換するには、次の正規表現を使って `![$2]($1)` に置き換えてください。 + +- 検索：`` +- 置換：`![$2]($1)` + +--- + +続きは今後追加予定です… diff --git a/docs/ja/guide/mpa-mode.md b/docs/ja/guide/mpa-mode.md new file mode 100644 index 000000000000..f79e7f6e1438 --- /dev/null +++ b/docs/ja/guide/mpa-mode.md @@ -0,0 +1,23 @@ +# MPA モード + +MPA（Multi-Page Application）モードは、コマンドラインの `vitepress build --mpa`、または設定で `mpa: true` を指定することで有効化できます。 + +MPA モードでは、既定で **あらゆるページが JavaScript を含まずに** レンダリングされます。結果として、本番サイトは監査ツールにおける初回訪問のパフォーマンススコアが向上しやすくなります。 + +一方、SPA のナビゲーションがないため、ページ間リンクはフルリロードになります。読み込み後のページ遷移は、SPA モードのような即時性はありません。 + +また、「既定で JS なし」ということは、実質的に Vue をサーバーサイドのテンプレート言語としてのみ使うことを意味します。ブラウザ側ではイベントハンドラがアタッチされないため、インタラクティブ性はありません。クライアントサイドの JavaScript を読み込むには、特別な ` + + # Hello + ``` + +` + ``` + +### 生コンテンツのレンダリング + +ページに渡したパラメータはクライアント 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..dd5dbf38f80e --- /dev/null +++ b/docs/ja/guide/sitemap-generation.md @@ -0,0 +1,58 @@ +# サイトマップ生成 + +VitePress には、サイト用の `sitemap.xml` を生成する機能が標準で用意されています。有効化するには、`.vitepress/config.js` に次を追加します。 + + ```ts + export default { + sitemap: { + hostname: 'https://example.com' + } + } + ``` + +`siteamp.xml` に `` タグを含めるには、[`lastUpdated`](../reference/default-theme-last-updated) オプションを有効にします。 + +## オプション + +サイトマップ生成は [`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` フック + +`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..3e566a8d0e55 --- /dev/null +++ b/docs/ja/guide/ssr-compat.md @@ -0,0 +1,135 @@ +--- +outline: deep +--- + +# SSR 互換性 + +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` フック内に限定** するのが安全です。 + +## `` + +SSR に適さないコンポーネント（例：カスタムディレクティブを含むなど）を使用・デモする場合は、組み込みの `` コンポーネントでラップできます。 + + ```md + + + + ``` + +## インポート時に Browser API にアクセスするライブラリ + +一部のコンポーネントやライブラリは **インポート時に** ブラウザ API にアクセスします。インポート時にブラウザ環境を前提とするコードを使うには、動的インポートが必要です。 + +### mounted フック内でのインポート + + ```vue + + ``` + +### 条件付きインポート + +[`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..80c8ac21df43 --- /dev/null +++ b/docs/ja/guide/using-vue.md @@ -0,0 +1,288 @@ +# Markdown で Vue を使う + +VitePress では、各 Markdown ファイルはまず HTML にコンパイルされ、その後 [Vue の単一ファイルコンポーネント（SFC）](https://vuejs.org/guide/scaling-up/sfc.html) として処理されます。つまり、Markdown 内で Vue のあらゆる機能が使えます。動的テンプレート、Vue コンポーネントの利用、` + + ## Markdown コンテンツ + + 現在の値: {{ count }} + + + + + ``` + +::: warning Markdown での ` + ``` + +## Teleport の利用 + +現時点で VitePress は、SSG における Teleport を **body** へのみサポートしています。その他のターゲットへ Teleport したい場合は、組み込みの `` でラップするか、[`postRender` フック](../reference/site-config#postrender)で最終ページ HTML の適切な位置に Teleport のマークアップを注入してください。 + + + +::: details +<<< @/components/ModalDemo.vue +::: + + ```md + + +
+ // ... +
+ + + ``` + + + + + +## VS Code の IntelliSense サポート + + + +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..11cf40b5f303 --- /dev/null +++ b/docs/ja/guide/what-is-vitepress.md @@ -0,0 +1,57 @@ +# VitePress とは？ + +VitePress は、高速でコンテンツ中心の Web サイトを構築するための [静的サイトジェネレーター（SSG）](https://en.wikipedia.org/wiki/Static_site_generator) です。要するに、VitePress は [Markdown](https://en.wikipedia.org/wiki/Markdown) で書かれたソースコンテンツにテーマを適用し、どこにでも簡単にデプロイできる静的 HTML ページを生成します。 + +
+ +まずは試してみたい？ [クイックスタート](./getting-started) へどうぞ。 + +
+ +## ユースケース + +- **ドキュメント** + + 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/) は、ローカルコンテンツに基づいてインデックスページを生成するシンプルなブログです。 + +## 開発体験（DX） + +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 のテンプレート機能やインポートしたコンポーネントで静的コンテンツにインタラクションを埋め込めます。 + +## パフォーマンス + +多くの従来型 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 はどうなるの？ + +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..d3503a542594 --- /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: /guide/what-is-vitepress + - theme: alt + text: クイックスタート + link: /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..9f2cadfa6f1f --- /dev/null +++ b/docs/ja/reference/cli.md @@ -0,0 +1,73 @@ +# Command Line Interface + +## `vitepress dev` + +Start VitePress dev server using designated directory as root. Defaults to current directory. The `dev` command can also be omitted when running in current directory. + +### Usage + +```sh +# start in current directory, omitting `dev` +vitepress + +# start in sub directory +vitepress dev [root] +``` + +### Options + +| Option | Description | +| --------------- | ----------------------------------------------------------------- | +| `--open [path]` | Open browser on startup (`boolean \| string`) | +| `--port ` | Specify port (`number`) | +| `--base ` | Public base path (default: `/`) (`string`) | +| `--cors` | Enable CORS | +| `--strictPort` | Exit if specified port is already in use (`boolean`) | +| `--force` | Force the optimizer to ignore the cache and re-bundle (`boolean`) | + +## `vitepress build` + +Build the VitePress site for production. + +### Usage + +```sh +vitepress build [root] +``` + +### Options + +| Option | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `--mpa` (experimental) | Build in [MPA mode](../guide/mpa-mode) without client-side hydration (`boolean`) | +| `--base ` | Public base path (default: `/`) (`string`) | +| `--target ` | Transpile target (default: `"modules"`) (`string`) | +| `--outDir ` | Output directory relative to **cwd** (default: `/.vitepress/dist`) (`string`) | +| `--assetsInlineLimit ` | Static asset base64 inline threshold in bytes (default: `4096`) (`number`) | + +## `vitepress preview` + +Locally preview the production build. + +### Usage + +```sh +vitepress preview [root] +``` + +### Options + +| Option | Description | +| --------------- | ------------------------------------------ | +| `--base ` | Public base path (default: `/`) (`string`) | +| `--port ` | Specify port (`number`) | + +## `vitepress init` + +Start the [Setup Wizard](../guide/getting-started#setup-wizard) in current directory. + +### Usage + +```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..e23fde008c36 --- /dev/null +++ b/docs/ja/reference/default-theme-badge.md @@ -0,0 +1,69 @@ +# Badge + +The badge lets you add status to your headers. For example, it could be useful to specify the section's type, or supported version. + +## Usage + +You may use the `Badge` component which is globally available. + +```html +### Title +### Title +### Title +### Title +``` + +Code above renders like: + +### Title +### Title +### Title +### Title + +## Custom Children + +`` accept `children`, which will be displayed in the badge. + +```html +### Title custom element +``` + +### Title custom element + +## Customize Type Color + +You can customize the style of badges by overriding css variables. The following are the default values: + +```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); +} +``` + +## `` + +`` component accepts following props: + +```ts +interface Props { + // When `` is passed, this value gets ignored. + text?: string + + // Defaults to `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..1c0c170edda4 --- /dev/null +++ b/docs/ja/reference/default-theme-carbon-ads.md @@ -0,0 +1,22 @@ +# Carbon Ads + +VitePress has built in native support for [Carbon Ads](https://www.carbonads.net/). By defining the Carbon Ads credentials in config, VitePress will display ads on the page. + +```js +export default { + themeConfig: { + carbonAds: { + code: 'your-carbon-code', + placement: 'your-carbon-placement' + } + } +} +``` + +These values are used to call carbon CDN script as shown below. + +```js +`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}` +``` + +To learn more about Carbon Ads configuration, please visit [Carbon Ads website](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..4868cda3216c --- /dev/null +++ b/docs/ja/reference/default-theme-config.md @@ -0,0 +1,494 @@ +# Default Theme Config + +Theme config lets you customize your theme. You can define theme config via the `themeConfig` option in the config file: + +```ts +export default { + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + + // Theme related configurations. + themeConfig: { + logo: '/logo.svg', + nav: [...], + sidebar: { ... } + } +} +``` + +**The options documented on this page only apply to the default theme.** Different themes expect different theme config. When using a custom theme, the theme config object will be passed to the theme so the theme can define conditional behavior based on it. + +## i18nRouting + +- Type: `boolean` + +Changing locale to say `zh` will change the URL from `/foo` (or `/en/foo/`) to `/zh/foo`. You can disable this behavior by setting `themeConfig.i18nRouting` to `false`. + +## logo + +- Type: `ThemeableImage` + +Logo file to display in nav bar, right before the site title. Accepts a path string, or an object to set a different logo for light/dark mode. + +```ts +export default { + themeConfig: { + logo: '/logo.svg' + } +} +``` + +```ts +type ThemeableImage = + | string + | { src: string; alt?: string } + | { light: string; dark: string; alt?: string } +``` + +## siteTitle + +- Type: `string | false` + +You can customize this item to replace the default site title (`title` in app config) in nav. When set to `false`, title in nav will be disabled. Useful when you have `logo` that already contains the site title text. + +```ts +export default { + themeConfig: { + siteTitle: 'Hello World' + } +} +``` + +## nav + +- Type: `NavItem` + +The configuration for the nav menu item. More details in [Default Theme: Nav](./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 + +- Type: `Sidebar` + +The configuration for the sidebar menu item. More details in [Default Theme: 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 = { + /** + * The text label of the item. + */ + text?: string + + /** + * The link of the item. + */ + link?: string + + /** + * The children of the item. + */ + items?: SidebarItem[] + + /** + * If not specified, group is not collapsible. + * + * If `true`, group is collapsible and collapsed by default + * + * If `false`, group is collapsible but expanded by default + */ + collapsed?: boolean + + /** + * Base path for the children items. + */ + base?: string + + /** + * Customize text that appears on the footer of previous/next page. + */ + docFooterText?: string + + rel?: string + target?: string +} +``` + +## aside + +- Type: `boolean | 'left'` +- Default: `true` +- Can be overridden per page via [frontmatter](./frontmatter-config#aside) + +Setting this value to `false` prevents rendering of aside container.\ +Setting this value to `true` renders the aside to the right.\ +Setting this value to `left` renders the aside to the left. + +If you want to disable it for all viewports, you should use `outline: false` instead. + +## outline + +- Type: `Outline | Outline['level'] | false` +- Level can be overridden per page via [frontmatter](./frontmatter-config#outline) + +Setting this value to `false` prevents rendering of outline container. Refer this interface for more details: + +```ts +interface Outline { + /** + * The levels of headings to be displayed in the outline. + * Single number means only headings of that level will be displayed. + * If a tuple is passed, the first number is the minimum level and the second number is the maximum level. + * `'deep'` is same as `[2, 6]`, which means all headings from `

` to `

` will be displayed. + * + * @default 2 + */ + level?: number | [number, number] | 'deep' + + /** + * The title to be displayed on the outline. + * + * @default 'On this page' + */ + label?: string +} +``` + +## socialLinks + +- Type: `SocialLink[]` + +You may define this option to show your social account links with icons in nav. + +```ts +export default { + themeConfig: { + socialLinks: [ + // You can add any icon from simple-icons (https://simpleicons.org/): + { icon: 'github', link: 'https://github.com/vuejs/vitepress' }, + { icon: 'twitter', link: '...' }, + // You can also add custom icons by passing SVG as string: + { + icon: { + svg: 'Dribbble' + }, + link: '...', + // You can include a custom label for accessibility too (optional but recommended): + ariaLabel: 'cool link' + } + ] + } +} +``` + +```ts +interface SocialLink { + icon: string | { svg: string } + link: string + ariaLabel?: string +} +``` + +## footer + +- Type: `Footer` +- Can be overridden per page via [frontmatter](./frontmatter-config#footer) + +Footer configuration. You can add a message or copyright text on the footer, however, it will only be displayed when the page doesn't contain a sidebar. This is due to design concerns. + +```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 + +- Type: `EditLink` +- Can be overridden per page via [frontmatter](./frontmatter-config#editlink) + +Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. See [Default Theme: Edit Link](./default-theme-edit-link) for more details. + +```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 + +- Type: `LastUpdatedOptions` + +Allows customization for the last updated text and date format. + +```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 + +- Type: `AlgoliaSearch` + +An option to support searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Learn more in [Default Theme: Search](./default-theme-search) + +```ts +export interface AlgoliaSearchOptions extends DocSearchProps { + locales?: Record> +} +``` + +View full options [here](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts). + +## carbonAds {#carbon-ads} + +- Type: `CarbonAdsOptions` + +An option to display [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 +} +``` + +Learn more in [Default Theme: Carbon Ads](./default-theme-carbon-ads) + +## docFooter + +- Type: `DocFooter` + +Can be used to customize text appearing above previous and next links. Helpful if not writing docs in English. Also can be used to disable prev/next links globally. If you want to selectively enable/disable prev/next links, you can use [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 + +- Type: `string` +- Default: `Appearance` + +Can be used to customize the dark mode switch label. This label is only displayed in the mobile view. + +## lightModeSwitchTitle + +- Type: `string` +- Default: `Switch to light theme` + +Can be used to customize the light mode switch title that appears on hovering. + +## darkModeSwitchTitle + +- Type: `string` +- Default: `Switch to dark theme` + +Can be used to customize the dark mode switch title that appears on hovering. + +## sidebarMenuLabel + +- Type: `string` +- Default: `Menu` + +Can be used to customize the sidebar menu label. This label is only displayed in the mobile view. + +## returnToTopLabel + +- Type: `string` +- Default: `Return to top` + +Can be used to customize the label of the return to top button. This label is only displayed in the mobile view. + +## langMenuLabel + +- Type: `string` +- Default: `Change language` + +Can be used to customize the aria-label of the language toggle button in navbar. This is only used if you're using [i18n](../guide/i18n). + +## skipToContentLabel + +- Type: `string` +- Default: `Skip to content` + +Can be used to customize the label of the skip to content link. This link is shown when the user is navigating the site using a keyboard. + +## externalLinkIcon + +- Type: `boolean` +- Default: `false` + +Whether to show an external link icon next to external links in markdown. + +## `useLayout` + +Returns layout-related data. The returned object has the following type: + +```ts +interface { + isHome: ComputedRef + + sidebar: Readonly> + sidebarGroups: ComputedRef + hasSidebar: ComputedRef + isSidebarEnabled: ComputedRef + + hasAside: ComputedRef + leftAside: ComputedRef + + headers: Readonly> + hasLocalNav: ComputedRef +} +``` + +**Example:** + +```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..ff049d59e3a9 --- /dev/null +++ b/docs/ja/reference/default-theme-edit-link.md @@ -0,0 +1,60 @@ +# Edit Link + +## Site-Level Config + +Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. To enable it, add `themeConfig.editLink` options to your config. + +```js +export default { + themeConfig: { + editLink: { + pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path' + } + } +} +``` + +The `pattern` option defines the URL structure for the link, and `:path` is going to be replaced with the page path. + +You can also put a pure function that accepts [`PageData`](./runtime-api#usedata) as the argument and returns the URL string. + +```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}` + } + } + } + } +} +``` + +It should not have side-effects nor access anything outside of its scope since it will be serialized and executed in the browser. + +By default, this will add the link text "Edit this page" at the bottom of the doc page. You may customize this text by defining the `text` option. + +```js +export default { + themeConfig: { + editLink: { + pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path', + text: 'Edit this page on GitHub' + } + } +} +``` + +## Frontmatter Config + +This can be disabled per-page using the `editLink` option on frontmatter: + +```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..a58e8ac6b198 --- /dev/null +++ b/docs/ja/reference/default-theme-footer.md @@ -0,0 +1,53 @@ +# Footer + +VitePress will display global footer at the bottom of the page when `themeConfig.footer` is present. + +```ts +export default { + themeConfig: { + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright © 2019-present Evan You' + } + } +} +``` + +```ts +export interface Footer { + // The message shown right before copyright. + message?: string + + // The actual copyright text. + copyright?: string +} +``` + +The above configuration also supports HTML strings. So, for example, if you want to configure footer text to have some links, you can adjust the configuration as follows: + +```ts +export default { + themeConfig: { + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright © 2019-present Evan You' + } + } +} +``` + +::: warning +Only inline elements can be used in `message` and `copyright` as they are rendered inside a `

` element. If you want to add block elements, consider using [`layout-bottom`](../guide/extending-default-theme#layout-slots) slot instead. +::: + +Note that footer will not be displayed when the [SideBar](./default-theme-sidebar) is visible. + +## Frontmatter Config + +This can be disabled per-page using the `footer` option on frontmatter: + +```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..f7baecca0138 --- /dev/null +++ b/docs/ja/reference/default-theme-home-page.md @@ -0,0 +1,195 @@ +# Home Page + +VitePress default theme provides a homepage layout, which you can also see used on [the homepage of this site](../). You may use it on any of your pages by specifying `layout: home` in the [frontmatter](./frontmatter-config). + +```yaml +--- +layout: home +--- +``` + +However, this option alone wouldn't do much. You can add several different pre templated "sections" to the homepage by setting additional other options such as `hero` and `features`. + +## Hero Section + +The Hero section comes at the top of the homepage. Here's how you can configure the Hero section. + +```yaml +--- +layout: home + +hero: + name: VitePress + text: Vite & Vue powered static site generator. + tagline: Lorem ipsum... + image: + src: /logo.png + alt: VitePress + actions: + - theme: brand + text: Get Started + link: /guide/what-is-vitepress + - theme: alt + text: View on GitHub + link: https://github.com/vuejs/vitepress +--- +``` + +```ts +interface Hero { + // The string shown top of `text`. Comes with brand color + // and expected to be short, such as product name. + name?: string + + // The main text for the hero section. This will be defined + // as `h1` tag. + text: string + + // Tagline displayed below `text`. + tagline?: string + + // The image is displayed next to the text and tagline area. + image?: ThemeableImage + + // Action buttons to display in home hero section. + actions?: HeroAction[] +} + +type ThemeableImage = + | string + | { src: string; alt?: string } + | { light: string; dark: string; alt?: string } + +interface HeroAction { + // Color theme of the button. Defaults to `brand`. + theme?: 'brand' | 'alt' + + // Label of the button. + text: string + + // Destination link of the button. + link: string + + // Link target attribute. + target?: string + + // Link rel attribute. + rel?: string +} +``` + +### Customizing the name color + +VitePress uses the brand color (`--vp-c-brand-1`) for the `name`. However, you may customize this color by overriding `--vp-home-hero-name-color` variable. + +```css +:root { + --vp-home-hero-name-color: blue; +} +``` + +Also you may customize it further by combining `--vp-home-hero-name-background` to give the `name` gradient color. + +```css +:root { + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff); +} +``` + +## Features Section + +In Features section, you can list any number of features you would like to show right after the Hero section. To configure it, pass `features` option to the frontmatter. + +You can provide an icon for each feature, which can be an emoji or any type of image. When the configured icon is an image (svg, png, jpeg...), you must provide the icon with the proper width and height; you can also provide the description, its intrinsic size as well as its variants for dark and light theme when required. + +```yaml +--- +layout: home + +features: + - icon: 🛠️ + title: Simple and minimal, always + details: Lorem ipsum... + - icon: + src: /cool-feature-icon.svg + title: Another cool feature + details: Lorem ipsum... + - icon: + dark: /dark-feature-icon.svg + light: /light-feature-icon.svg + title: Another cool feature + details: Lorem ipsum... +--- +``` + +```ts +interface Feature { + // Show icon on each feature box. + icon?: FeatureIcon + + // Title of the feature. + title: string + + // Details of the feature. + details: string + + // Link when clicked on feature component. The link can + // be both internal or external. + // + // e.g. `guide/reference/default-theme-home-page` or `https://example.com` + link?: string + + // Link text to be shown inside feature component. Best + // used with `link` option. + // + // e.g. `Learn more`, `Visit page`, etc. + linkText?: string + + // Link rel attribute for the `link` option. + // + // e.g. `external` + rel?: string + + // Link target attribute for the `link` option. + target?: string +} + +type FeatureIcon = + | string + | { src: string; alt?: string; width?: string; height: string } + | { + light: string + dark: string + alt?: string + width?: string + height: string + } +``` + +## Markdown Content + +You can add additional content to your site's homepage just by adding Markdown below the `---` frontmatter divider. + +````md +--- +layout: home + +hero: + name: VitePress + text: Vite & Vue powered static site generator. +--- + +## Getting Started + +You can get started using VitePress right away using `npx`! + +```sh +npm init +npx vitepress init +``` +```` + +::: info +VitePress didn't always auto-style the extra content of the `layout: home` page. To revert to older behavior, you can add `markdownStyles: false` to the frontmatter. +::: 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..55603269923f --- /dev/null +++ b/docs/ja/reference/default-theme-last-updated.md @@ -0,0 +1,46 @@ +# Last Updated + +The update time of the last content will be displayed in the lower right corner of the page. To enable it, add `lastUpdated` options to your config. + +::: info +VitePress displays the "last updated" time using the timestamp of the most recent Git commit for each file. To enable this, the Markdown file must be committed to Git. + +Internally, VitePress runs `git log -1 --pretty="%ai"` on each file to retrieve its timestamp. If all pages show the same update time, it's likely due to shallow cloning (common in CI environments), which limits Git history. + +To fix this in **GitHub Actions**, use the following in your workflow: + +```yaml{4} +- name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 +``` + +Other CI/CD platforms have similar settings. + +If such options aren't available, you can prepend the `docs:build` command in your `package.json` with a manual fetch: + +```json +"docs:build": "git fetch --unshallow && vitepress build docs" +``` +::: + +## Site-Level Config + +```js +export default { + lastUpdated: true +} +``` + +## Frontmatter Config + +This can be disabled per-page using the `lastUpdated` option on frontmatter: + +```yaml +--- +lastUpdated: false +--- +``` + +Also refer [Default Theme: Last Updated](./default-theme-config#lastupdated) for more details. Any truthy value at theme-level will also enable the feature unless explicitly disabled at site or page level. diff --git a/docs/ja/reference/default-theme-layout.md b/docs/ja/reference/default-theme-layout.md new file mode 100644 index 000000000000..246e20fa9f04 --- /dev/null +++ b/docs/ja/reference/default-theme-layout.md @@ -0,0 +1,62 @@ +# Layout + +You may choose the page layout by setting `layout` option to the page [frontmatter](./frontmatter-config). There are 3 layout options, `doc`, `page`, and `home`. If nothing is specified, then the page is treated as `doc` page. + +```yaml +--- +layout: doc +--- +``` + +## Doc Layout + +Option `doc` is the default layout and it styles the whole Markdown content into "documentation" look. It works by wrapping whole content within `vp-doc` css class, and applying styles to elements underneath it. + +Almost all generic elements such as `p`, or `h2` get special styling. Therefore, keep in mind that if you add any custom HTML inside a Markdown content, those will get affected by those styles as well. + +It also provides documentation specific features listed below. These features are only enabled in this layout. + +- Edit Link +- Prev Next Link +- Outline +- [Carbon Ads](./default-theme-carbon-ads) + +## Page Layout + +Option `page` is treated as "blank page". The Markdown will still be parsed, and all of the [Markdown Extensions](../guide/markdown) work as same as `doc` layout, but it wouldn't get any default stylings. + +The page layout will let you style everything by you without VitePress theme affecting the markup. This is useful when you want to create your own custom page. + +Note that even in this layout, sidebar will still show up if the page has a matching sidebar config. + +## Home Layout + +Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Default Theme: Home Page](./default-theme-home-page) for more details. + +## No Layout + +If you don't want any layout, you can pass `layout: false` through frontmatter. This option is helpful if you want a fully-customizable landing page (without any sidebar, navbar, or footer by default). + +## Custom Layout + +You can also use a custom layout: + +```md +--- +layout: foo +--- +``` + +This will look for a component named `foo` registered in context. For example, you can register your component globally in `.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..f7be114dbacc --- /dev/null +++ b/docs/ja/reference/default-theme-nav.md @@ -0,0 +1,216 @@ +# Nav + +The Nav is the navigation bar displayed on top of the page. It contains the site title, global menu links, etc. + +## Site Title and Logo + +By default, nav shows the title of the site referencing [`config.title`](./site-config#title) value. If you would like to change what's displayed on nav, you may define custom text in `themeConfig.siteTitle` option. + +```js +export default { + themeConfig: { + siteTitle: 'My Custom Title' + } +} +``` + +If you have a logo for your site, you can display it by passing in the path to the image. You should place the logo within `public` directly, and define the absolute path to it. + +```js +export default { + themeConfig: { + logo: '/my-logo.svg' + } +} +``` + +When adding a logo, it gets displayed along with the site title. If your logo is all you need and if you would like to hide the site title text, set `false` to the `siteTitle` option. + +```js +export default { + themeConfig: { + logo: '/my-logo.svg', + siteTitle: false + } +} +``` + +You can also pass an object as logo if you want to add `alt` attribute or customize it based on dark/light mode. Refer [`themeConfig.logo`](./default-theme-config#logo) for details. + +## Navigation Links + +You may define `themeConfig.nav` option to add links to your nav. + +```js +export default { + themeConfig: { + nav: [ + { text: 'Guide', link: '/guide' }, + { text: 'Config', link: '/config' }, + { text: 'Changelog', link: 'https://github.com/...' } + ] + } +} +``` + +The `text` is the actual text displayed in nav, and the `link` is the link that will be navigated to when the text is clicked. For the link, set path to the actual file without `.md` prefix, and always start with `/`. + +The `link` can also be a function that accepts [`PageData`](./runtime-api#usedata) as the argument and returns the path. + +Nav links can also be dropdown menus. To do this, set `items` key on link option. + +```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' } + ] + } + ] + } +} +``` + +Note that dropdown menu title (`Dropdown Menu` in the above example) can not have `link` property since it becomes a button to open dropdown dialog. + +You may further add "sections" to the dropdown menu items as well by passing in more nested items. + +```js +export default { + themeConfig: { + nav: [ + { text: 'Guide', link: '/guide' }, + { + text: 'Dropdown Menu', + items: [ + { + // Title for the section. + text: 'Section A Title', + items: [ + { text: 'Section A Item A', link: '...' }, + { text: 'Section B Item B', link: '...' } + ] + } + ] + }, + { + text: 'Dropdown Menu', + items: [ + { + // You may also omit the title. + items: [ + { text: 'Section A Item A', link: '...' }, + { text: 'Section B Item B', link: '...' } + ] + } + ] + } + ] + } +} +``` + +### Customize link's "active" state + +Nav menu items will be highlighted when the current page is under the matching path. if you would like to customize the path to be matched, define `activeMatch` property and regex as a string value. + +```js +export default { + themeConfig: { + nav: [ + // This link gets active state when the user is + // on `/config/` path. + { + text: 'Guide', + link: '/guide', + activeMatch: '/config/' + } + ] + } +} +``` + +::: warning +`activeMatch` is expected to be a regex string, but you must define it as a string. We can't use actual RegExp object here because it isn't serializable during the build time. +::: + +### Customize link's "target" and "rel" attributes + +By default, VitePress automatically determines `target` and `rel` attributes based on whether the link is an external link. But if you want, you can customize them too. + +```js +export default { + themeConfig: { + nav: [ + { + text: 'Merchandise', + link: 'https://www.thegithubshop.com/', + target: '_self', + rel: 'sponsored' + } + ] + } +} +``` + +## Social Links + +Refer [`socialLinks`](./default-theme-config#sociallinks). + +## Custom Components + +You can include custom components in the navigation bar by using the `component` option. The `component` key should be the Vue component name, and must be registered globally using [Theme.enhanceApp](../guide/custom-theme#theme-interface). + +```js [.vitepress/config.js] +export default { + themeConfig: { + nav: [ + { + text: 'My Menu', + items: [ + { + component: 'MyCustomComponent', + // Optional props to pass to the component + props: { + title: 'My Custom Component' + } + } + ] + }, + { + component: 'AnotherCustomComponent' + } + ] + } +} +``` + +Then, you need to register the component globally: + +```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) + } +} +``` + +Your component will be rendered in the navigation bar. VitePress will provide the following additional props to the component: + +- `screenMenu`: an optional boolean indicating whether the component is inside mobile navigation menu + +You can check an example in the e2e tests [here](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..7befe179b5bc --- /dev/null +++ b/docs/ja/reference/default-theme-prev-next-links.md @@ -0,0 +1,43 @@ +# Prev Next Links + +You can customize the text and link for the previous and next pages (shown at doc footer). This is helpful if you want a different text there than what you have on your sidebar. Additionally, you may find it useful to disable the footer or link to a page that is not included in your sidebar. + +## prev + +- Type: `string | false | { text?: string; link?: string }` + +- Details: + + Specifies the text/link to show on the link to the previous page. If you don't set this in frontmatter, the text/link will be inferred from the sidebar config. + +- Examples: + + - To customize only the text: + + ```yaml + --- + prev: 'Get Started | Markdown' + --- + ``` + + - To customize both text and link: + + ```yaml + --- + prev: + text: 'Markdown' + link: '/guide/markdown' + --- + ``` + + - To hide previous page: + + ```yaml + --- + prev: false + --- + ``` + +## next + +Same as `prev` but for the next page. diff --git a/docs/ja/reference/default-theme-search.md b/docs/ja/reference/default-theme-search.md new file mode 100644 index 000000000000..6bc2f4462cfd --- /dev/null +++ b/docs/ja/reference/default-theme-search.md @@ -0,0 +1,451 @@ +--- +outline: deep +--- + +# Search + +## Local Search + +VitePress supports fuzzy full-text search using an in-browser index thanks to [minisearch](https://github.com/lucaong/minisearch/). To enable this feature, simply set the `themeConfig.search.provider` option to `'local'` in your `.vitepress/config.ts` file: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local' + } + } +}) +``` + +Example result: + +![screenshot of the search modal](/search.png) + +Alternatively, you can use [Algolia DocSearch](#algolia-search) or some community plugins like: + +- +- +- + +### i18n {#local-search-i18n} + +You can use a config like this to use multilingual search: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + locales: { + zh: { // make this `root` if you want to translate the default locale + translations: { + button: { + buttonText: '搜索', + buttonAriaLabel: '搜索' + }, + modal: { + displayDetails: '显示详细列表', + resetButtonTitle: '重置搜索', + backButtonTitle: '关闭搜索', + noResultsText: '没有结果', + footer: { + selectText: '选择', + selectKeyAriaLabel: '输入', + navigateText: '导航', + navigateUpKeyAriaLabel: '上箭头', + navigateDownKeyAriaLabel: '下箭头', + closeText: '关闭', + closeKeyAriaLabel: 'esc' + } + } + } + } + } + } + } + } +}) +``` + +### miniSearch options + +You can configure MiniSearch like this: + +```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: { + /* ... */ + } + } + } + } + } +}) +``` + +Learn more in [MiniSearch docs](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html). + +### Custom content renderer + +You can customize the function used to render the markdown content before indexing it: + +```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) { + // return html string + } + } + } + } +}) +``` + +This function will be stripped from client-side site data, so you can use Node.js APIs in it. + +#### Example: Excluding pages from search + +You can exclude pages from search by adding `search: false` to the frontmatter of the page. Alternatively: + +```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 Note +In case a custom `_render` function is provided, you need to handle the `search: false` frontmatter yourself. Also, the `env` object won't be completely populated before `md.renderAsync` is called, so any checks on optional `env` properties like `frontmatter` should be done after that. +::: + +#### 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 Search + +VitePress supports searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Refer their getting started guide. In your `.vitepress/config.ts` you'll need to provide at least the following to make it work: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'algolia', + options: { + appId: '...', + apiKey: '...', + indexName: '...' + } + } + } +}) +``` + +### i18n {#algolia-search-i18n} + +You can use a config like this to use multilingual search: + +```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: '搜索提供者' + } + } + } + } + } + } + } + } +}) +``` + +[These options](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) can be overridden. Refer official Algolia docs to learn more about them. + +### Algolia Ask AI Support {#ask-ai} + +If you would like to include **Ask AI**, pass the `askAi` option (or any of the partial fields) inside `options`: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'algolia', + options: { + appId: '...', + apiKey: '...', + indexName: '...', + // askAi: "YOUR-ASSISTANT-ID" + // OR + askAi: { + // at minimum you must provide the assistantId you received from Algolia + assistantId: 'XXXYYY', + // optional overrides – if omitted, the top-level appId/apiKey/indexName values are reused + // apiKey: '...', + // appId: '...', + // indexName: '...' + } + } + } + } +}) +``` + +::: warning Note +If want to default to keyword search and do not want to use Ask AI, just omit the `askAi` property +::: + +The translations for the Ask AI UI live under `options.translations.modal.askAiScreen` and `options.translations.resultsScreen` — see the [type definitions](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) for all keys. + +### Crawler Config + +Here is an example config based on what this site uses: + +```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..67893cf6edd8 --- /dev/null +++ b/docs/ja/reference/default-theme-sidebar.md @@ -0,0 +1,182 @@ +# Sidebar + +The sidebar is the main navigation block for your documentation. You can configure the sidebar menu in [`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 + +The simplest form of the sidebar menu is passing in a single array of links. The first level item defines the "section" for the sidebar. It should contain `text`, which is the title of the section, and `items` which are the actual navigation links. + +```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' }, + ... + ] + } + ] + } +} +``` + +Each `link` should specify the path to the actual file starting with `/`. If you add trailing slash to the end of link, it will show `index.md` of the corresponding directory. + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Guide', + items: [ + // This shows `/guide/index.md` page. + { text: 'Introduction', link: '/guide/' } + ] + } + ] + } +} +``` + +You may further nest the sidebar items up to 6 level deep counting up from the root level. Note that deeper than 6 level of nested items gets ignored and will not be displayed on the sidebar. + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Level 1', + items: [ + { + text: 'Level 2', + items: [ + { + text: 'Level 3', + items: [ + ... + ] + } + ] + } + ] + } + ] + } +} +``` + +## Multiple Sidebars + +You may show different sidebar depending on the page path. For example, as shown on this site, you might want to create a separate sections of content in your documentation like "Guide" page and "Config" page. + +To do so, first organize your pages into directories for each desired section: + +``` +. +├─ guide/ +│ ├─ index.md +│ ├─ one.md +│ └─ two.md +└─ config/ + ├─ index.md + ├─ three.md + └─ four.md +``` + +Then, update your configuration to define your sidebar for each section. This time, you should pass an object instead of an array. + +```js +export default { + themeConfig: { + sidebar: { + // This sidebar gets displayed when a user + // is on `guide` directory. + '/guide/': [ + { + text: 'Guide', + items: [ + { text: 'Index', link: '/guide/' }, + { text: 'One', link: '/guide/one' }, + { text: 'Two', link: '/guide/two' } + ] + } + ], + + // This sidebar gets displayed when a user + // is on `config` directory. + '/config/': [ + { + text: 'Config', + items: [ + { text: 'Index', link: '/config/' }, + { text: 'Three', link: '/config/three' }, + { text: 'Four', link: '/config/four' } + ] + } + ] + } + } +} +``` + +## Collapsible Sidebar Groups + +By adding `collapsed` option to the sidebar group, it shows a toggle button to hide/show each section. + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Section Title A', + collapsed: false, + items: [...] + } + ] + } +} +``` + +All sections are "open" by default. If you would like them to be "closed" on initial page load, set `collapsed` option to `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..6c37c6a752d8 --- /dev/null +++ b/docs/ja/reference/default-theme-team-page.md @@ -0,0 +1,256 @@ + + +# Team Page + +If you would like to introduce your team, you may use Team components to construct the Team Page. There are two ways of using these components. One is to embed it in doc page, and another is to create a full Team Page. + +## Show team members in a page + +You may use `` component exposed from `vitepress/theme` to display a list of team members on any page. + +```html + + +# Our Team + +Say hello to our awesome team. + + +``` + +The above will display a team member in card looking element. It should display something similar to below. + + + +`` component comes in 2 different sizes, `small` and `medium`. While it boils down to your preference, usually `small` size should fit better when used in doc page. Also, you may add more properties to each member such as adding "description" or "sponsor" button. Learn more about it in [``](#vpteammembers). + +Embedding team members in doc page is good for small size team where having dedicated full team page might be too much, or introducing partial members as a reference to documentation context. + +If you have large number of members, or simply would like to have more space to show team members, consider [creating a full team page](#create-a-full-team-page). + +## Create a full Team Page + +Instead of adding team members to doc page, you may also create a full Team Page, similar to how you can create a custom [Home Page](./default-theme-home-page). + +To create a team page, first, create a new md file. The file name doesn't matter, but here lets call it `team.md`. In this file, set frontmatter option `layout: page`, and then you may compose your page structure using `TeamPage` components. + +```html +--- +layout: page +--- + + + + + + + + + +``` + +When creating a full team page, remember to wrap all components with `` component. This component will ensure all nested team related components get the proper layout structure like spacings. + +`` component adds the page title section. The title being `

` heading. Use `#title` and `#lead` slot to document about your team. + +`` works as same as when used in a doc page. It will display list of members. + +### Add sections to divide team members + +You may add "sections" to the team page. For example, you may have different types of team members such as Core Team Members and Community Partners. You can divide these members into sections to better explain the roles of each group. + +To do so, add `` component to the `team.md` file we created previously. + +```html +--- +layout: page +--- + + + + + + + + + + + + + + +``` + +The `` component can have `#title` and `#lead` slot similar to `VPTeamPageTitle` component, and also `#members` slot for displaying team members. + +Remember to put in `` component within `#members` slot. + +## `` + +The `` component displays a given list of members. + +```html + +``` + +```ts +interface Props { + // Size of each members. Defaults to `medium`. + size?: 'small' | 'medium' + + // List of members to display. + members: TeamMember[] +} + +interface TeamMember { + // Avatar image for the member. + avatar: string + + // Name of the member. + name: string + + // Title to be shown below member's name. + // e.g. Developer, Software Engineer, etc. + title?: string + + // Organization that the member belongs. + org?: string + + // URL for the organization. + orgLink?: string + + // Description for the member. + desc?: string + + // Social links. e.g. GitHub, Twitter, etc. You may pass in + // the Social Links object here. + // See: https://vitepress.dev/reference/default-theme-config.html#sociallinks + links?: SocialLink[] + + // URL for the sponsor page for the member. + sponsor?: string + + // Text for the sponsor link. Defaults to 'Sponsor'. + actionText?: string +} +``` + +## `` + +The root component when creating a full team page. It only accepts a single slot. It will style all passed in team related components. + +## `` + +Adds "title" section of the page. Best use at the very beginning under ``. It accepts `#title` and `#lead` slot. + +```html + + + + + + +``` + +## `` + +Creates a "section" with in team page. It accepts `#title`, `#lead`, and `#members` slot. You may add as many sections as you like inside ``. + +```html + + ... + + + + + + +``` diff --git a/docs/ja/reference/frontmatter-config.md b/docs/ja/reference/frontmatter-config.md new file mode 100644 index 000000000000..4d6f86c0172a --- /dev/null +++ b/docs/ja/reference/frontmatter-config.md @@ -0,0 +1,240 @@ +--- +outline: deep +--- + +# Frontmatter Config + +Frontmatter enables page based configuration. In every markdown file, you can use frontmatter config to override site-level or theme-level config options. Also, there are config options which you can only define in frontmatter. + +Example usage: + +```md +--- +title: Docs with VitePress +editLink: true +--- +``` + +You can access frontmatter data via the `$frontmatter` global in Vue expressions: + +```md +{{ $frontmatter.title }} +``` + +## title + +- Type: `string` + +Title for the page. It's same as [config.title](./site-config#title), and it overrides the site-level config. + +```yaml +--- +title: VitePress +--- +``` + +## titleTemplate + +- Type: `string | boolean` + +The suffix for the title. It's same as [config.titleTemplate](./site-config#titletemplate), and it overrides the site-level config. + +```yaml +--- +title: VitePress +titleTemplate: Vite & Vue powered static site generator +--- +``` + +## description + +- Type: `string` + +Description for the page. It's same as [config.description](./site-config#description), and it overrides the site-level config. + +```yaml +--- +description: VitePress +--- +``` + +## head + +- Type: `HeadConfig[]` + +Specify extra head tags to be injected for the current page. Will be appended after head tags injected by site-level config. + +```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 + +The following frontmatter options are only applicable when using the default theme. + +### layout + +- Type: `doc | home | page` +- Default: `doc` + +Determines the layout of the page. + +- `doc` - It applies default documentation styles to the markdown content. +- `home` - Special layout for "Home Page". You may add extra options such as `hero` and `features` to rapidly create beautiful landing page. +- `page` - Behave similar to `doc` but it applies no styles to the content. Useful when you want to create a fully custom page. + +```yaml +--- +layout: doc +--- +``` + +### hero + +Defines contents of home hero section when `layout` is set to `home`. More details in [Default Theme: Home Page](./default-theme-home-page). + +### features + +Defines items to display in features section when `layout` is set to `home`. More details in [Default Theme: Home Page](./default-theme-home-page). + +### navbar + +- Type: `boolean` +- Default: `true` + +Whether to display [navbar](./default-theme-nav). + +```yaml +--- +navbar: false +--- +``` + +### sidebar + +- Type: `boolean` +- Default: `true` + +Whether to display [sidebar](./default-theme-sidebar). + +```yaml +--- +sidebar: false +--- +``` + +### aside + +- Type: `boolean | 'left'` +- Default: `true` + +Defines the location of the aside component in the `doc` layout. + +Setting this value to `false` prevents rendering of aside container.\ +Setting this value to `true` renders the aside to the right.\ +Setting this value to `'left'` renders the aside to the left. + +```yaml +--- +aside: false +--- +``` + +### outline + +- Type: `number | [number, number] | 'deep' | false` +- Default: `2` + +The levels of header in the outline to display for the page. It's same as [config.themeConfig.outline.level](./default-theme-config#outline), and it overrides the value set in site-level config. + +```yaml +--- +outline: [2, 4] +--- +``` + +### lastUpdated + +- Type: `boolean | Date` +- Default: `true` + +Whether to display [last updated](./default-theme-last-updated) text in the footer of the current page. If a datetime is specified, it will be displayed instead of the last git modified timestamp. + +```yaml +--- +lastUpdated: false +--- +``` + +### editLink + +- Type: `boolean` +- Default: `true` + +Whether to display [edit link](./default-theme-edit-link) in the footer of the current page. + +```yaml +--- +editLink: false +--- +``` + +### footer + +- Type: `boolean` +- Default: `true` + +Whether to display [footer](./default-theme-footer). + +```yaml +--- +footer: false +--- +``` + +### pageClass + +- Type: `string` + +Add extra class name to a specific page. + +```yaml +--- +pageClass: custom-page-class +--- +``` + +Then you can customize styles of this specific page in `.vitepress/theme/custom.css` file: + +```css +.custom-page-class { + /* page-specific styles */ +} +``` + +### isHome + +- Type: `boolean` + +The default theme relies on checks like `frontmatter.layout === 'home'` to determine if the current page is the home page.\ +This is useful when you want to force show the home page elements in a custom layout. + +```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..d55165f50e59 --- /dev/null +++ b/docs/ja/reference/runtime-api.md @@ -0,0 +1,173 @@ +# Runtime API + +VitePress offers several built-in APIs to let you access app data. VitePress also comes with a few built-in components that can be used globally. + +The helper methods are globally importable from `vitepress` and are typically used in custom theme Vue components. However, they are also usable inside `.md` pages because markdown files are compiled into Vue [Single-File Components](https://vuejs.org/guide/scaling-up/sfc.html). + +Methods that start with `use*` indicates that it is a [Vue 3 Composition API](https://vuejs.org/guide/introduction.html#composition-api) function ("Composable") that can only be used inside `setup()` or ` + + +``` + +## `useRoute` + +Returns the current route object with the following type: + +```ts +interface Route { + path: string + data: PageData + component: Component | null +} +``` + +## `useRouter` + +Returns the VitePress router instance so you can programmatically navigate to another page. + +```ts +interface Router { + /** + * Current route. + */ + route: Route + /** + * Navigate to a new URL. + */ + go: (to?: string) => Promise + /** + * Called before the route changes. Return `false` to cancel the navigation. + */ + onBeforeRouteChange?: (to: string) => Awaitable + /** + * Called before the page component is loaded (after the history state is updated). + * Return `false` to cancel the navigation. + */ + onBeforePageLoad?: (to: string) => Awaitable + /** + * Called after the page component is loaded (before the page component is updated). + */ + onAfterPageLoad?: (to: string) => Awaitable + /** + * Called after the route changes. + */ + onAfterRouteChange?: (to: string) => Awaitable +} +``` + +## `withBase` + +- **Type**: `(path: string) => string` + +Appends the configured [`base`](./site-config#base) to a given URL path. Also see [Base URL](../guide/asset-handling#base-url). + +## `` + +The `` component displays the rendered markdown contents. Useful [when creating your own theme](../guide/custom-theme). + +```vue + +``` + +## `` + +The `` component renders its slot only at client side. + +Because VitePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the universal code requirements. In short, make sure to only access Browser / DOM APIs in beforeMount or mounted hooks. + +If you are using or demoing components that are not SSR-friendly (for example, contain custom directives), you can wrap them inside the `ClientOnly` component. + +```vue-html + + + +``` + +- Related: [SSR Compatibility](../guide/ssr-compat) + +## `$frontmatter` + +Directly access current page's [frontmatter](../guide/frontmatter) data in Vue expressions. + +```md +--- +title: Hello +--- + +# {{ $frontmatter.title }} +``` + +## `$params` + +Directly access current page's [dynamic route params](../guide/routing#dynamic-routes) in Vue expressions. + +```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..a6c64cb6ea45 --- /dev/null +++ b/docs/ja/reference/site-config.md @@ -0,0 +1,722 @@ +--- +outline: deep +--- + +# Site Config + +Site config is where you can define the global settings of the site. App config options define settings that apply to every VitePress site, regardless of what theme it is using. For example, the base directory or the title of the site. + +## Overview + +### Config Resolution + +The config file is always resolved from `/.vitepress/config.[ext]`, where `` is your VitePress [project root](../guide/routing#root-and-source-directory), and `[ext]` is one of the supported file extensions. TypeScript is supported out of the box. Supported extensions include `.js`, `.ts`, `.mjs`, and `.mts`. + +It is recommended to use ES modules syntax in config files. The config file should default export an object: + +```ts +export default { + // app level config options + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + ... +} +``` + +::: details Dynamic (Async) Config + +If you need to dynamically generate the config, you can also default export a function. For example: + +```ts +import { defineConfig } from 'vitepress' + +export default async () => { + const posts = await (await fetch('https://my-cms.com/blog-posts')).json() + + return defineConfig({ + // app level config options + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + + // theme level config options + themeConfig: { + sidebar: [ + ...posts.map((post) => ({ + text: post.name, + link: `/posts/${post.name}` + })) + ] + } + }) +} +``` + +You can also use top-level `await`. For example: + +```ts +import { defineConfig } from 'vitepress' + +const posts = await (await fetch('https://my-cms.com/blog-posts')).json() + +export default defineConfig({ + // app level config options + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + + // theme level config options + themeConfig: { + sidebar: [ + ...posts.map((post) => ({ + text: post.name, + link: `/posts/${post.name}` + })) + ] + } +}) +``` + +::: + +### Config Intellisense + +Using the `defineConfig` helper will provide TypeScript-powered intellisense for config options. Assuming your IDE supports it, this should work in both JavaScript and TypeScript. + +```js +import { defineConfig } from 'vitepress' + +export default defineConfig({ + // ... +}) +``` + +### Typed Theme Config + +By default, `defineConfig` helper expects the theme config type from default theme: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + // Type is `DefaultTheme.Config` + } +}) +``` + +If you use a custom theme and want type checks for the theme config, you'll need to use `defineConfigWithTheme` instead, and pass the config type for your custom theme via a generic argument: + +```ts +import { defineConfigWithTheme } from 'vitepress' +import type { ThemeConfig } from 'your-theme' + +export default defineConfigWithTheme({ + themeConfig: { + // Type is `ThemeConfig` + } +}) +``` + +### Vite, Vue & Markdown Config + +- **Vite** + + You can configure the underlying Vite instance using the [vite](#vite) option in your VitePress config. No need to create a separate Vite config file. + +- **Vue** + + VitePress already includes the official Vue plugin for Vite ([@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue)). You can configure its options using the [vue](#vue) option in your VitePress config. + +- **Markdown** + + You can configure the underlying [Markdown-It](https://github.com/markdown-it/markdown-it) instance using the [markdown](#markdown) option in your VitePress config. + +## Site Metadata + +### title + +- Type: `string` +- Default: `VitePress` +- Can be overridden per page via [frontmatter](./frontmatter-config#title) + +Title for the site. When using the default theme, this will be displayed in the nav bar. + +It will also be used as the default suffix for all individual page titles, unless [`titleTemplate`](#titletemplate) is defined. An individual page's final title will be the text content of its first `

` header, combined with the global `title` as the suffix. For example with the following config and page content: + +```ts +export default { + title: 'My Awesome Site' +} +``` + +```md +# Hello +``` + +The title of the page will be `Hello | My Awesome Site`. + +### titleTemplate + +- Type: `string | boolean` +- Can be overridden per page via [frontmatter](./frontmatter-config#titletemplate) + +Allows customizing each page's title suffix or the entire title. For example: + +```ts +export default { + title: 'My Awesome Site', + titleTemplate: 'Custom Suffix' +} +``` + +```md +# Hello +``` + +The title of the page will be `Hello | Custom Suffix`. + +To completely customize how the title should be rendered, you can use the `:title` symbol in `titleTemplate`: + +```ts +export default { + titleTemplate: ':title - Custom Suffix' +} +``` + +Here `:title` will be replaced with the text inferred from the page's first `

` header. The title of the previous example page will be `Hello - Custom Suffix`. + +The option can be set to `false` to disable title suffixes. + +### description + +- Type: `string` +- Default: `A VitePress site` +- Can be overridden per page via [frontmatter](./frontmatter-config#description) + +Description for the site. This will render as a `` tag in the page HTML. + +```ts +export default { + description: 'A VitePress site' +} +``` + +### head + +- Type: `HeadConfig[]` +- Default: `[]` +- Can be appended per page via [frontmatter](./frontmatter-config#head) + +Additional elements to render in the `` tag in the page HTML. The user-added tags are rendered before the closing `head` tag, after VitePress tags. + +```ts +type HeadConfig = + | [string, Record] + | [string, Record, string] +``` + +#### Example: Adding a favicon + +```ts +export default { + head: [['link', { rel: 'icon', href: '/favicon.ico' }]] +} // put favicon.ico in public directory, if base is set, use /base/favicon.ico + +/* Would render: + +*/ +``` + +#### 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' } + ] + ] +} + +/* Would render: + + + +*/ +``` + +#### Example: Registering a service worker + +```ts +export default { + head: [ + [ + 'script', + { id: 'register-sw' }, + `;(() => { + if ('serviceWorker' in navigator) { + navigator.serviceWorker.register('/sw.js') + } + })()` + ] + ] +} + +/* Would render: + +*/ +``` + +#### 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');` + ] + ] +} + +/* Would render: + + +*/ +``` + +### lang + +- Type: `string` +- Default: `en-US` + +The lang attribute for the site. This will render as a `` tag in the page HTML. + +```ts +export default { + lang: 'en-US' +} +``` + +### base + +- Type: `string` +- Default: `/` + +The base URL the site will be deployed at. You will need to set this if you plan to deploy your site under a sub path, for example, GitHub pages. If you plan to deploy your site to `https://foo.github.io/bar/`, then you should set base to `'/bar/'`. It should always start and end with a slash. + +The base is automatically prepended to all the URLs that start with / in other options, so you only need to specify it once. + +```ts +export default { + base: '/base/' +} +``` + +## Routing + +### cleanUrls + +- Type: `boolean` +- Default: `false` + +When set to `true`, VitePress will remove the trailing `.html` from URLs. Also see [Generating Clean URL](../guide/routing#generating-clean-url). + +::: warning Server Support Required +Enabling this may require additional configuration on your hosting platform. For it to work, your server must be able to serve `/foo.html` when visiting `/foo` **without a redirect**. +::: + +### rewrites + +- Type: `Record` + +Defines custom directory <-> URL mappings. See [Routing: Route Rewrites](../guide/routing#route-rewrites) for more details. + +```ts +export default { + rewrites: { + 'source/:page': 'destination/:page' + } +} +``` + +## Build + +### srcDir + +- Type: `string` +- Default: `.` + +The directory where your markdown pages are stored, relative to project root. Also see [Root and Source Directory](../guide/routing#root-and-source-directory). + +```ts +export default { + srcDir: './src' +} +``` + +### srcExclude + +- Type: `string[]` +- Default: `undefined` + +A [glob pattern](https://github.com/mrmlnc/fast-glob#pattern-syntax) for matching markdown files that should be excluded as source content. + +```ts +export default { + srcExclude: ['**/README.md', '**/TODO.md'] +} +``` + +### outDir + +- Type: `string` +- Default: `./.vitepress/dist` + +The build output location for the site, relative to [project root](../guide/routing#root-and-source-directory). + +```ts +export default { + outDir: '../public' +} +``` + +### assetsDir + +- Type: `string` +- Default: `assets` + +Specify the directory to nest generated assets under. The path should be inside [`outDir`](#outdir) and is resolved relative to it. + +```ts +export default { + assetsDir: 'static' +} +``` + +### cacheDir + +- Type: `string` +- Default: `./.vitepress/cache` + +The directory for cache files, relative to [project root](../guide/routing#root-and-source-directory). See also: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir). + +```ts +export default { + cacheDir: './.vitepress/.vite' +} +``` + +### ignoreDeadLinks + +- Type: `boolean | 'localhostLinks' | (string | RegExp | ((link: string, source: string) => boolean))[]` +- Default: `false` + +When set to `true`, VitePress will not fail builds due to dead links. + +When set to `'localhostLinks'`, the build will fail on dead links, but won't check `localhost` links. + +```ts +export default { + ignoreDeadLinks: true +} +``` + +It can also be an array of exact url string, regex patterns, or custom filter functions. + +```ts +export default { + ignoreDeadLinks: [ + // ignore exact url "/playground" + '/playground', + // ignore all localhost links + /^https?:\/\/localhost/, + // ignore all links include "/repl/"" + /\/repl\//, + // custom function, ignore all links include "ignore" + (url) => { + return url.toLowerCase().includes('ignore') + } + ] +} +``` + +### metaChunk + +- Type: `boolean` +- Default: `false` + +When set to `true`, extract pages metadata to a separate JavaScript chunk instead of inlining it in the initial HTML. This makes each page's HTML payload smaller and makes the pages metadata cacheable, thus reducing server bandwidth when you have many pages in the site. + +### mpa + +- Type: `boolean` +- Default: `false` + +When set to `true`, the production app will be built in [MPA Mode](../guide/mpa-mode). MPA mode ships 0kb JavaScript by default, at the cost of disabling client-side navigation and requires explicit opt-in for interactivity. + +## Theming + +### appearance + +- Type: `boolean | 'dark' | 'force-dark' | 'force-auto' | import('@vueuse/core').UseDarkOptions` +- Default: `true` + +Whether to enable dark mode (by adding the `.dark` class to the `` element). + +- If the option is set to `true`, the default theme will be determined by the user's preferred color scheme. +- If the option is set to `dark`, the theme will be dark by default, unless the user manually toggles it. +- If the option is set to `false`, users will not be able to toggle the theme. +- If the option is set to `'force-dark'`, the theme will always be dark and users will not be able to toggle it. +- If the option is set to `'force-auto'`, the theme will always be determined by the user's preferred color scheme and users will not be able to toggle it. + +This option injects an inline script that restores users settings from local storage using the `vitepress-theme-appearance` key. This ensures the `.dark` class is applied before the page is rendered to avoid flickering. + +`appearance.initialValue` can only be `'dark' | undefined`. Refs or getters are not supported. + +### lastUpdated + +- Type: `boolean` +- Default: `false` + +Whether to get the last updated timestamp for each page using Git. The timestamp will be included in each page's page data, accessible via [`useData`](./runtime-api#usedata). + +When using the default theme, enabling this option will display each page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext) option. + +## Customization + +### markdown + +- Type: `MarkdownOption` + +Configure Markdown parser options. VitePress uses [Markdown-it](https://github.com/markdown-it/markdown-it) as the parser, and [Shiki](https://github.com/shikijs/shiki) to highlight language syntax. Inside this option, you may pass various Markdown related options to fit your needs. + +```js +export default { + markdown: {...} +} +``` + +Check the [type declaration and jsdocs](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) for all the options available. + +### vite + +- Type: `import('vite').UserConfig` + +Pass raw [Vite Config](https://vitejs.dev/config/) to internal Vite dev server / bundler. + +```js +export default { + vite: { + // Vite config options + } +} +``` + +### vue + +- Type: `import('@vitejs/plugin-vue').Options` + +Pass raw [`@vitejs/plugin-vue` options](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options) to the internal plugin instance. + +```js +export default { + vue: { + // @vitejs/plugin-vue options + } +} +``` + +## Build Hooks + +VitePress build hooks allow you to add new functionality and behaviors to your website: + +- Sitemap +- Search Indexing +- PWA +- Teleports + +### buildEnd + +- Type: `(siteConfig: SiteConfig) => Awaitable` + +`buildEnd` is a build CLI hook, it will run after build (SSG) finish but before VitePress CLI process exits. + +```ts +export default { + async buildEnd(siteConfig) { + // ... + } +} +``` + +### postRender + +- Type: `(context: SSGContext) => Awaitable` + +`postRender` is a build hook, called when SSG rendering is done. It will allow you to handle the teleports content during SSG. + +```ts +export default { + async postRender(context) { + // ... + } +} +``` + +```ts +interface SSGContext { + content: string + teleports?: Record + [key: string]: any +} +``` + +### transformHead + +- Type: `(context: TransformContext) => Awaitable` + +`transformHead` is a build hook to transform the head before generating each page. It will allow you to add head entries that cannot be statically added to your VitePress config. You only need to return extra entries, they will be merged automatically with the existing ones. + +::: warning +Don't mutate anything inside the `context`. +::: + +```ts +export default { + async transformHead(context) { + // ... + } +} +``` + +```ts +interface TransformContext { + page: string // e.g. index.md (relative to srcDir) + assets: string[] // all non-js/css assets as fully resolved public URL + siteConfig: SiteConfig + siteData: SiteData + pageData: PageData + title: string + description: string + head: HeadConfig[] + content: string +} +``` + +Note that this hook is only called when generating the site statically. It is not called during dev. If you need to add dynamic head entries during dev, you can use the [`transformPageData`](#transformpagedata) hook instead: + +```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` + } + ]) + } +} +``` + +#### Example: Adding a canonical URL `` + +```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 + +- Type: `(code: string, id: string, context: TransformContext) => Awaitable` + +`transformHtml` is a build hook to transform the content of each page before saving to disk. + +::: warning +Don't mutate anything inside the `context`. Also, modifying the html content may cause hydration problems in runtime. +::: + +```ts +export default { + async transformHtml(code, id, context) { + // ... + } +} +``` + +### transformPageData + +- Type: `(pageData: PageData, context: TransformPageContext) => Awaitable | { [key: string]: any } | void>` + +`transformPageData` is a hook to transform the `pageData` of each page. You can directly mutate `pageData` or return changed values which will be merged into the page data. + +::: warning +Don't mutate anything inside the `context` and be careful that this might impact the performance of dev server, especially if you have some network requests or heavy computations (like generating images) in the hook. You can check for `process.env.NODE_ENV === 'production'` for conditional logic. +::: + +```ts +export default { + async transformPageData(pageData, { siteConfig }) { + pageData.contributors = await getPageContributors(pageData.relativePath) + } + + // or return data to be merged + 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", From 4582e3d9e413f98abc31562fa082c4e10e669ecb Mon Sep 17 00:00:00 2001 From: Kenzo-Wada Date: Thu, 2 Oct 2025 13:22:32 +0900 Subject: [PATCH 2/7] i18n(ja): add japanese reference pages --- docs/ja/reference/cli.md | 92 +-- docs/ja/reference/default-theme-badge.md | 86 +- docs/ja/reference/default-theme-carbon-ads.md | 34 +- docs/ja/reference/default-theme-config.md | 774 +++++++++--------- docs/ja/reference/default-theme-edit-link.md | 120 +-- docs/ja/reference/default-theme-footer.md | 20 +- docs/ja/reference/default-theme-home-page.md | 99 ++- .../reference/default-theme-last-updated.md | 22 +- docs/ja/reference/default-theme-layout.md | 42 +- docs/ja/reference/default-theme-nav.md | 63 +- .../default-theme-prev-next-links.md | 20 +- docs/ja/reference/default-theme-search.md | 66 +- docs/ja/reference/default-theme-sidebar.md | 34 +- docs/ja/reference/default-theme-team-page.md | 95 ++- docs/ja/reference/frontmatter-config.md | 110 +-- docs/ja/reference/runtime-api.md | 60 +- docs/ja/reference/site-config.md | 300 +++---- 17 files changed, 1014 insertions(+), 1023 deletions(-) diff --git a/docs/ja/reference/cli.md b/docs/ja/reference/cli.md index 9f2cadfa6f1f..e06ef569ec3f 100644 --- a/docs/ja/reference/cli.md +++ b/docs/ja/reference/cli.md @@ -1,73 +1,73 @@ -# Command Line Interface +# コマンドラインインターフェイス ## `vitepress dev` -Start VitePress dev server using designated directory as root. Defaults to current directory. The `dev` command can also be omitted when running in current directory. +指定したディレクトリをルートとして VitePress の開発サーバーを起動します。既定はカレントディレクトリです。カレントディレクトリで実行する場合、`dev` コマンドは省略できます。 -### Usage +### 使い方 -```sh -# start in current directory, omitting `dev` -vitepress + ```sh + # カレントディレクトリで起動（`dev` を省略） + vitepress -# start in sub directory -vitepress dev [root] -``` + # サブディレクトリで起動 + vitepress dev [root] + ``` -### Options +### オプション -| Option | Description | -| --------------- | ----------------------------------------------------------------- | -| `--open [path]` | Open browser on startup (`boolean \| string`) | -| `--port ` | Specify port (`number`) | -| `--base ` | Public base path (default: `/`) (`string`) | -| `--cors` | Enable CORS | -| `--strictPort` | Exit if specified port is already in use (`boolean`) | -| `--force` | Force the optimizer to ignore the cache and re-bundle (`boolean`) | +| オプション | 説明 | +| ------------------ | -------------------------------------------------------------------- | +| `--open [path]` | 起動時にブラウザを開く（`boolean \| string`） | +| `--port ` | ポート番号を指定（`number`） | +| `--base ` | 公開時のベースパス（既定: `/`）（`string`） | +| `--cors` | CORS を有効化 | +| `--strictPort` | 指定ポートが使用中なら終了（`boolean`） | +| `--force` | 最適化時にキャッシュを無視して再バンドル（`boolean`） | ## `vitepress build` -Build the VitePress site for production. +本番用に VitePress サイトをビルドします。 -### Usage +### 使い方 -```sh -vitepress build [root] -``` + ```sh + vitepress build [root] + ``` -### Options +### オプション -| Option | Description | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | -| `--mpa` (experimental) | Build in [MPA mode](../guide/mpa-mode) without client-side hydration (`boolean`) | -| `--base ` | Public base path (default: `/`) (`string`) | -| `--target ` | Transpile target (default: `"modules"`) (`string`) | -| `--outDir ` | Output directory relative to **cwd** (default: `/.vitepress/dist`) (`string`) | -| `--assetsInlineLimit ` | Static asset base64 inline threshold in bytes (default: `4096`) (`number`) | +| オプション | 説明 | +| ----------------------------- | -------------------------------------------------------------------------------------------------- | +| `--mpa`（実験的） | クライアント側ハイドレーションなしの [MPA モード](../guide/mpa-mode) でビルド（`boolean`） | +| `--base ` | 公開時のベースパス（既定: `/`）（`string`） | +| `--target ` | トランスパイルターゲット（既定: `"modules"`）（`string`） | +| `--outDir ` | 出力先ディレクトリ（**cwd** からの相対）（既定: `/.vitepress/dist`）（`string`） | +| `--assetsInlineLimit `| 静的アセットを base64 インライン化する閾値（バイト）（既定: `4096`）（`number`） | ## `vitepress preview` -Locally preview the production build. +本番ビルドをローカルでプレビューします。 -### Usage +### 使い方 -```sh -vitepress preview [root] -``` + ```sh + vitepress preview [root] + ``` -### Options +### オプション -| Option | Description | -| --------------- | ------------------------------------------ | -| `--base ` | Public base path (default: `/`) (`string`) | -| `--port ` | Specify port (`number`) | +| オプション | 説明 | +| ------------------ | ----------------------------------------- | +| `--base ` | 公開時のベースパス（既定: `/`）（`string`） | +| `--port ` | ポート番号を指定（`number`） | ## `vitepress init` -Start the [Setup Wizard](../guide/getting-started#setup-wizard) in current directory. +カレントディレクトリで [セットアップウィザード](../guide/getting-started#setup-wizard) を起動します。 -### Usage +### 使い方 -```sh -vitepress init -``` + ```sh + vitepress init + ``` diff --git a/docs/ja/reference/default-theme-badge.md b/docs/ja/reference/default-theme-badge.md index e23fde008c36..dbecd137d0e5 100644 --- a/docs/ja/reference/default-theme-badge.md +++ b/docs/ja/reference/default-theme-badge.md @@ -1,69 +1,69 @@ -# Badge +# バッジ -The badge lets you add status to your headers. For example, it could be useful to specify the section's type, or supported version. +バッジを使うと、見出しにステータスを追加できます。たとえば、そのセクションの種類や対応バージョンを示すのに便利です。 -## Usage +## 使い方 -You may use the `Badge` component which is globally available. +グローバルに利用可能な `Badge` コンポーネントを使用します。 -```html -### Title -### Title -### Title -### Title -``` + ```html + ### Title + ### Title + ### Title + ### Title + ``` -Code above renders like: +上記のコードは次のように表示されます： ### Title ### Title ### Title ### Title -## Custom Children +## 子要素のカスタマイズ -`` accept `children`, which will be displayed in the badge. +`` は子要素（`children`）を受け取り、バッジ内に表示できます。 -```html -### Title custom element -``` + ```html + ### Title custom element + ``` ### Title custom element -## Customize Type Color +## 種類ごとの色をカスタマイズ -You can customize the style of badges by overriding css variables. The following are the default values: +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); + ```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-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-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); -} -``` + --vp-badge-danger-border: transparent; + --vp-badge-danger-text: var(--vp-c-danger-1); + --vp-badge-danger-bg: var(--vp-c-danger-soft); + } + ``` ## `` -`` component accepts following props: +`` コンポーネントは次の props を受け取ります。 -```ts -interface Props { - // When `` is passed, this value gets ignored. - text?: string + ```ts + interface Props { + // `` が渡された場合、この値は無視されます。 + text?: string - // Defaults to `tip`. - type?: 'info' | 'tip' | 'warning' | 'danger' -} -``` + // 既定値は `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 index 1c0c170edda4..b84d51e5f6e8 100644 --- a/docs/ja/reference/default-theme-carbon-ads.md +++ b/docs/ja/reference/default-theme-carbon-ads.md @@ -1,22 +1,22 @@ -# Carbon Ads +# Carbon 広告 -VitePress has built in native support for [Carbon Ads](https://www.carbonads.net/). By defining the Carbon Ads credentials in config, VitePress will display ads on the page. +VitePress は [Carbon Ads](https://www.carbonads.net/) をネイティブにサポートしています。設定で Carbon Ads の認証情報を定義すると、ページ上に広告が表示されます。 -```js -export default { - themeConfig: { - carbonAds: { - code: 'your-carbon-code', - placement: 'your-carbon-placement' - } - } -} -``` + ```js + export default { + themeConfig: { + carbonAds: { + code: 'your-carbon-code', + placement: 'your-carbon-placement' + } + } + } + ``` -These values are used to call carbon CDN script as shown below. +これらの値は、次のように Carbon の CDN スクリプトを呼び出すために使用されます。 -```js -`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}` -``` + ```js + `//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}` + ``` -To learn more about Carbon Ads configuration, please visit [Carbon Ads website](https://www.carbonads.net/). +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 index 4868cda3216c..c7f14e5687a6 100644 --- a/docs/ja/reference/default-theme-config.md +++ b/docs/ja/reference/default-theme-config.md @@ -1,494 +1,494 @@ -# Default Theme Config +# デフォルトテーマの設定 -Theme config lets you customize your theme. You can define theme config via the `themeConfig` option in the config file: +テーマ設定では、テーマのカスタマイズができます。設定ファイルの `themeConfig` オプションで定義します。 -```ts -export default { - lang: 'en-US', - title: 'VitePress', - description: 'Vite & Vue powered static site generator.', + ```ts + export default { + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', - // Theme related configurations. - themeConfig: { - logo: '/logo.svg', - nav: [...], - sidebar: { ... } - } -} -``` + // テーマ関連の設定 + themeConfig: { + logo: '/logo.svg', + nav: [...], + sidebar: { ... } + } + } + ``` -**The options documented on this page only apply to the default theme.** Different themes expect different theme config. When using a custom theme, the theme config object will be passed to the theme so the theme can define conditional behavior based on it. +**このページで説明するオプションは、デフォルトテーマにのみ適用されます。** テーマによって期待する設定は異なります。カスタムテーマを使用する場合、ここで定義したテーマ設定オブジェクトはテーマへ渡され、テーマ側がそれに基づいて条件付きの挙動を定義できます。 ## i18nRouting -- Type: `boolean` +- 型: `boolean` -Changing locale to say `zh` will change the URL from `/foo` (or `/en/foo/`) to `/zh/foo`. You can disable this behavior by setting `themeConfig.i18nRouting` to `false`. +ロケールを `zh` のように切り替えると、URL は `/foo`（または `/en/foo/`）から `/zh/foo` に変わります。`themeConfig.i18nRouting` を `false` に設定すると、この挙動を無効化できます。 ## logo -- Type: `ThemeableImage` +- 型: `ThemeableImage` -Logo file to display in nav bar, right before the site title. Accepts a path string, or an object to set a different logo for light/dark mode. +サイトタイトルの直前に、ナビゲーションバーに表示されるロゴ。パス文字列、またはライト／ダークモードで異なるロゴを設定するオブジェクトを受け取ります。 -```ts -export default { - themeConfig: { - logo: '/logo.svg' - } -} -``` + ```ts + export default { + themeConfig: { + logo: '/logo.svg' + } + } + ``` -```ts -type ThemeableImage = - | string - | { src: string; alt?: string } - | { light: string; dark: string; alt?: string } -``` + ```ts + type ThemeableImage = + | string + | { src: string; alt?: string } + | { light: string; dark: string; alt?: string } + ``` ## siteTitle -- Type: `string | false` +- 型: `string | false` -You can customize this item to replace the default site title (`title` in app config) in nav. When set to `false`, title in nav will be disabled. Useful when you have `logo` that already contains the site title text. +ナビゲーション内の既定サイトタイトル（アプリ設定の `title`）を置き換えます。`false` の場合、ナビのタイトルを非表示にします。ロゴ自体にサイト名が含まれている場合に便利です。 -```ts -export default { - themeConfig: { - siteTitle: 'Hello World' - } -} -``` + ```ts + export default { + themeConfig: { + siteTitle: 'Hello World' + } + } + ``` ## nav -- Type: `NavItem` - -The configuration for the nav menu item. More details in [Default Theme: Nav](./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 -} -``` +- 型: `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 -- Type: `Sidebar` - -The configuration for the sidebar menu item. More details in [Default Theme: 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 = { - /** - * The text label of the item. - */ - text?: string - - /** - * The link of the item. - */ - link?: string - - /** - * The children of the item. - */ - items?: SidebarItem[] - - /** - * If not specified, group is not collapsible. - * - * If `true`, group is collapsible and collapsed by default - * - * If `false`, group is collapsible but expanded by default - */ - collapsed?: boolean - - /** - * Base path for the children items. - */ - base?: string - - /** - * Customize text that appears on the footer of previous/next page. - */ - docFooterText?: string - - rel?: string - target?: string -} -``` +- 型: `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 -- Type: `boolean | 'left'` -- Default: `true` -- Can be overridden per page via [frontmatter](./frontmatter-config#aside) +- 型: `boolean | 'left'` +- 既定値: `true` +- ページごとに [frontmatter](./frontmatter-config#aside) で上書き可能 -Setting this value to `false` prevents rendering of aside container.\ -Setting this value to `true` renders the aside to the right.\ -Setting this value to `left` renders the aside to the left. +`false` でサイドコンテナの描画を無効化。\ +`true` で右側に表示。\ +`left` で左側に表示。 -If you want to disable it for all viewports, you should use `outline: false` instead. +すべてのビューポートで無効にしたい場合は、代わりに `outline: false` を使用してください。 ## outline -- Type: `Outline | Outline['level'] | false` -- Level can be overridden per page via [frontmatter](./frontmatter-config#outline) - -Setting this value to `false` prevents rendering of outline container. Refer this interface for more details: - -```ts -interface Outline { - /** - * The levels of headings to be displayed in the outline. - * Single number means only headings of that level will be displayed. - * If a tuple is passed, the first number is the minimum level and the second number is the maximum level. - * `'deep'` is same as `[2, 6]`, which means all headings from `

` to `

` will be displayed. - * - * @default 2 - */ - level?: number | [number, number] | 'deep' - - /** - * The title to be displayed on the outline. - * - * @default 'On this page' - */ - label?: string -} -``` +- 型: `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 -- Type: `SocialLink[]` - -You may define this option to show your social account links with icons in nav. - -```ts -export default { - themeConfig: { - socialLinks: [ - // You can add any icon from simple-icons (https://simpleicons.org/): - { icon: 'github', link: 'https://github.com/vuejs/vitepress' }, - { icon: 'twitter', link: '...' }, - // You can also add custom icons by passing SVG as string: - { - icon: { - svg: 'Dribbble' - }, - link: '...', - // You can include a custom label for accessibility too (optional but recommended): - ariaLabel: 'cool link' - } - ] - } -} -``` - -```ts -interface SocialLink { - icon: string | { svg: string } - link: string - ariaLabel?: string -} -``` +- 型: `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 -- Type: `Footer` -- Can be overridden per page via [frontmatter](./frontmatter-config#footer) - -Footer configuration. You can add a message or copyright text on the footer, however, it will only be displayed when the page doesn't contain a sidebar. This is due to design concerns. - -```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 -} -``` +- 型: `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 -- Type: `EditLink` -- Can be overridden per page via [frontmatter](./frontmatter-config#editlink) - -Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. See [Default Theme: Edit Link](./default-theme-edit-link) for more details. - -```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 -} -``` +- 型: `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 -- Type: `LastUpdatedOptions` - -Allows customization for the last updated text and date format. - -```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 } -} -``` +- 型: `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 -- Type: `AlgoliaSearch` +- 型: `AlgoliaSearch` -An option to support searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Learn more in [Default Theme: Search](./default-theme-search) +[Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch) によるサイト内検索の設定。[デフォルトテーマ: 検索](./default-theme-search) を参照。 -```ts -export interface AlgoliaSearchOptions extends DocSearchProps { - locales?: Record> -} -``` + ```ts + export interface AlgoliaSearchOptions extends DocSearchProps { + locales?: Record> + } + ``` -View full options [here](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts). +完全なオプションは[こちら](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts)。 ## carbonAds {#carbon-ads} -- Type: `CarbonAdsOptions` +- 型: `CarbonAdsOptions` -An option to display [Carbon Ads](https://www.carbonads.net/). +[Carbon Ads](https://www.carbonads.net/) を表示します。 -```ts -export default { - themeConfig: { - carbonAds: { - code: 'your-carbon-code', - placement: 'your-carbon-placement' - } - } -} -``` + ```ts + export default { + themeConfig: { + carbonAds: { + code: 'your-carbon-code', + placement: 'your-carbon-placement' + } + } + } + ``` -```ts -export interface CarbonAdsOptions { - code: string - placement: string -} -``` + ```ts + export interface CarbonAdsOptions { + code: string + placement: string + } + ``` -Learn more in [Default Theme: Carbon Ads](./default-theme-carbon-ads) +詳細は [デフォルトテーマ: Carbon Ads](./default-theme-carbon-ads) を参照。 ## docFooter -- Type: `DocFooter` +- 型: `DocFooter` -Can be used to customize text appearing above previous and next links. Helpful if not writing docs in English. Also can be used to disable prev/next links globally. If you want to selectively enable/disable prev/next links, you can use [frontmatter](./default-theme-prev-next-links). +前／次リンクの上に表示される文言をカスタマイズします。英語以外のドキュメントで便利。前／次リンク自体をグローバルに無効化することも可能。ページごとに切り替えたい場合は [frontmatter](./default-theme-prev-next-links) を使用します。 -```ts -export default { - themeConfig: { - docFooter: { - prev: 'Pagina prior', - next: 'Proxima pagina' - } - } -} -``` + ```ts + export default { + themeConfig: { + docFooter: { + prev: 'Pagina prior', + next: 'Proxima pagina' + } + } + } + ``` -```ts -export interface DocFooter { - prev?: string | false - next?: string | false -} -``` + ```ts + export interface DocFooter { + prev?: string | false + next?: string | false + } + ``` ## darkModeSwitchLabel -- Type: `string` -- Default: `Appearance` +- 型: `string` +- 既定値: `Appearance` -Can be used to customize the dark mode switch label. This label is only displayed in the mobile view. +ダークモード切替スイッチのラベル（モバイル表示のみ）をカスタマイズします。 ## lightModeSwitchTitle -- Type: `string` -- Default: `Switch to light theme` +- 型: `string` +- 既定値: `Switch to light theme` -Can be used to customize the light mode switch title that appears on hovering. +ホバー時に表示されるライトモード切替のタイトルをカスタマイズします。 ## darkModeSwitchTitle -- Type: `string` -- Default: `Switch to dark theme` +- 型: `string` +- 既定値: `Switch to dark theme` -Can be used to customize the dark mode switch title that appears on hovering. +ホバー時に表示されるダークモード切替のタイトルをカスタマイズします。 ## sidebarMenuLabel -- Type: `string` -- Default: `Menu` +- 型: `string` +- 既定値: `Menu` -Can be used to customize the sidebar menu label. This label is only displayed in the mobile view. +サイドバーメニューのラベル（モバイル表示のみ）をカスタマイズします。 ## returnToTopLabel -- Type: `string` -- Default: `Return to top` +- 型: `string` +- 既定値: `Return to top` -Can be used to customize the label of the return to top button. This label is only displayed in the mobile view. +トップに戻るボタンのラベル（モバイル表示のみ）をカスタマイズします。 ## langMenuLabel -- Type: `string` -- Default: `Change language` +- 型: `string` +- 既定値: `Change language` -Can be used to customize the aria-label of the language toggle button in navbar. This is only used if you're using [i18n](../guide/i18n). +ナビバーの言語切替ボタンの aria-label をカスタマイズします。[i18n](../guide/i18n) を使う場合に有効です。 ## skipToContentLabel -- Type: `string` -- Default: `Skip to content` +- 型: `string` +- 既定値: `Skip to content` -Can be used to customize the label of the skip to content link. This link is shown when the user is navigating the site using a keyboard. +コンテンツへスキップリンクのラベルをカスタマイズします。キーボード操作時に表示されます。 ## externalLinkIcon -- Type: `boolean` -- Default: `false` +- 型: `boolean` +- 既定値: `false` -Whether to show an external link icon next to external links in markdown. +Markdown 内の外部リンクの横に外部リンクアイコンを表示するかどうか。 ## `useLayout` -Returns layout-related data. The returned object has the following type: +レイアウト関連のデータを返します。返り値の型は次のとおりです。 -```ts -interface { - isHome: ComputedRef + ```ts + interface { + isHome: ComputedRef - sidebar: Readonly> - sidebarGroups: ComputedRef - hasSidebar: ComputedRef - isSidebarEnabled: ComputedRef + sidebar: Readonly> + sidebarGroups: ComputedRef + hasSidebar: ComputedRef + isSidebarEnabled: ComputedRef - hasAside: ComputedRef - leftAside: ComputedRef + hasAside: ComputedRef + leftAside: ComputedRef - headers: Readonly> - hasLocalNav: ComputedRef -} -``` + headers: Readonly> + hasLocalNav: ComputedRef + } + ``` -**Example:** +**例:** -```vue - + const { hasSidebar } = useLayout() + - -``` + + ``` diff --git a/docs/ja/reference/default-theme-edit-link.md b/docs/ja/reference/default-theme-edit-link.md index ff049d59e3a9..05acf9a727ba 100644 --- a/docs/ja/reference/default-theme-edit-link.md +++ b/docs/ja/reference/default-theme-edit-link.md @@ -1,60 +1,60 @@ -# Edit Link - -## Site-Level Config - -Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. To enable it, add `themeConfig.editLink` options to your config. - -```js -export default { - themeConfig: { - editLink: { - pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path' - } - } -} -``` - -The `pattern` option defines the URL structure for the link, and `:path` is going to be replaced with the page path. - -You can also put a pure function that accepts [`PageData`](./runtime-api#usedata) as the argument and returns the URL string. - -```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}` - } - } - } - } -} -``` - -It should not have side-effects nor access anything outside of its scope since it will be serialized and executed in the browser. - -By default, this will add the link text "Edit this page" at the bottom of the doc page. You may customize this text by defining the `text` option. - -```js -export default { - themeConfig: { - editLink: { - pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path', - text: 'Edit this page on GitHub' - } - } -} -``` - -## Frontmatter Config - -This can be disabled per-page using the `editLink` option on frontmatter: - -```yaml ---- -editLink: false ---- -``` +# 編集リンク + +## サイトレベルの設定 + +編集リンクは、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 でこのページを編集' + } + } + } + ``` + +## フロントマターでの設定 + +ページごとに無効化するには、フロントマターで `editLink` オプションを使用します。 + + ```yaml + --- + editLink: false + --- + ``` diff --git a/docs/ja/reference/default-theme-footer.md b/docs/ja/reference/default-theme-footer.md index a58e8ac6b198..9a42fd906c17 100644 --- a/docs/ja/reference/default-theme-footer.md +++ b/docs/ja/reference/default-theme-footer.md @@ -1,6 +1,6 @@ -# Footer +# フッター -VitePress will display global footer at the bottom of the page when `themeConfig.footer` is present. +`themeConfig.footer` を設定すると、ページ下部にグローバルフッターが表示されます。 ```ts export default { @@ -15,15 +15,15 @@ export default { ```ts export interface Footer { - // The message shown right before copyright. + // 著作権表示の直前に表示されるメッセージ message?: string - // The actual copyright text. + // 実際の著作権表記 copyright?: string } ``` -The above configuration also supports HTML strings. So, for example, if you want to configure footer text to have some links, you can adjust the configuration as follows: +上記の設定は HTML 文字列にも対応しています。たとえば、フッター内のテキストにリンクを含めたい場合は、次のように設定できます。 ```ts export default { @@ -37,14 +37,16 @@ export default { ``` ::: warning -Only inline elements can be used in `message` and `copyright` as they are rendered inside a `

` element. If you want to add block elements, consider using [`layout-bottom`](../guide/extending-default-theme#layout-slots) slot instead. +`message` と `copyright` は `

` 要素内にレンダリングされるため、 +使用できるのはインライン要素のみです。ブロック要素を追加したい場合は、 +[`layout-bottom`](../guide/extending-default-theme#layout-slots) スロットの利用を検討してください。 ::: -Note that footer will not be displayed when the [SideBar](./default-theme-sidebar) is visible. +なお、[SideBar](./default-theme-sidebar) が表示されている場合はフッターは表示されません。 -## Frontmatter Config +## フロントマターでの設定 -This can be disabled per-page using the `footer` option on frontmatter: +ページ単位で無効化するには、フロントマターの `footer` オプションを使用します。 ```yaml --- diff --git a/docs/ja/reference/default-theme-home-page.md b/docs/ja/reference/default-theme-home-page.md index f7baecca0138..0b4d8d2adb16 100644 --- a/docs/ja/reference/default-theme-home-page.md +++ b/docs/ja/reference/default-theme-home-page.md @@ -1,6 +1,6 @@ -# Home Page +# ホームページ -VitePress default theme provides a homepage layout, which you can also see used on [the homepage of this site](../). You may use it on any of your pages by specifying `layout: home` in the [frontmatter](./frontmatter-config). +VitePress のデフォルトテーマにはホームページ用レイアウトが用意されています（[このサイトのトップページ](../) でも使われています）。[フロントマター](./frontmatter-config) に `layout: home` を指定すれば、任意のページで利用できます。 ```yaml --- @@ -8,11 +8,11 @@ layout: home --- ``` -However, this option alone wouldn't do much. You can add several different pre templated "sections" to the homepage by setting additional other options such as `hero` and `features`. +ただし、この指定だけでは多くのことは起きません。`hero` や `features` などの追加オプションを設定して、ホームページにあらかじめ用意された複数の「セクション」を配置できます。 -## Hero Section +## ヒーローセクション -The Hero section comes at the top of the homepage. Here's how you can configure the Hero section. +ヒーローセクションはホームページの最上部に表示されます。設定例は次のとおりです。 ```yaml --- @@ -21,37 +21,36 @@ layout: home hero: name: VitePress text: Vite & Vue powered static site generator. - tagline: Lorem ipsum... + tagline: 概要テキスト... image: src: /logo.png alt: VitePress actions: - theme: brand - text: Get Started + text: はじめる link: /guide/what-is-vitepress - theme: alt - text: View on GitHub + text: GitHub で見る link: https://github.com/vuejs/vitepress --- ``` ```ts interface Hero { - // The string shown top of `text`. Comes with brand color - // and expected to be short, such as product name. + // `text` の上に表示される短い文字列。ブランドカラーで表示。 + // 製品名のような短い文言を想定。 name?: string - // The main text for the hero section. This will be defined - // as `h1` tag. + // ヒーローセクションのメインテキスト。`h1` として出力。 text: string - // Tagline displayed below `text`. + // `text` の下に表示されるタグライン。 tagline?: string - // The image is displayed next to the text and tagline area. + // テキストとタグラインの横に表示する画像。 image?: ThemeableImage - // Action buttons to display in home hero section. + // ヒーローに表示するアクションボタン。 actions?: HeroAction[] } @@ -61,26 +60,26 @@ type ThemeableImage = | { light: string; dark: string; alt?: string } interface HeroAction { - // Color theme of the button. Defaults to `brand`. + // ボタンのカラーテーマ。既定は `brand`。 theme?: 'brand' | 'alt' - // Label of the button. + // ボタンのラベル。 text: string - // Destination link of the button. + // ボタンのリンク先。 link: string - // Link target attribute. + // a 要素の target 属性。 target?: string - // Link rel attribute. + // a 要素の rel 属性。 rel?: string } ``` -### Customizing the name color +### name の色をカスタマイズする -VitePress uses the brand color (`--vp-c-brand-1`) for the `name`. However, you may customize this color by overriding `--vp-home-hero-name-color` variable. +`name` にはブランドカラー（`--vp-c-brand-1`）が使われますが、`--vp-home-hero-name-color` 変数を上書きして色を変更できます。 ```css :root { @@ -88,7 +87,7 @@ VitePress uses the brand color (`--vp-c-brand-1`) for the `name`. However, you m } ``` -Also you may customize it further by combining `--vp-home-hero-name-background` to give the `name` gradient color. +さらに、`--vp-home-hero-name-background` を組み合わせると、`name` にグラデーションを適用できます。 ```css :root { @@ -97,11 +96,11 @@ Also you may customize it further by combining `--vp-home-hero-name-background` } ``` -## Features Section +## フィーチャーセクション -In Features section, you can list any number of features you would like to show right after the Hero section. To configure it, pass `features` option to the frontmatter. +フィーチャーセクションでは、ヒーロー直下に任意の数の機能説明を並べられます。フロントマターに `features` オプションを指定して設定します。 -You can provide an icon for each feature, which can be an emoji or any type of image. When the configured icon is an image (svg, png, jpeg...), you must provide the icon with the proper width and height; you can also provide the description, its intrinsic size as well as its variants for dark and light theme when required. +各フィーチャーにはアイコン（絵文字または画像）を指定できます。アイコンが画像（svg, png, jpeg など）の場合は、**適切な幅・高さ** を指定してください。必要に応じて説明テキストや実サイズ、ライト／ダーク用の差し替えも指定できます。 ```yaml --- @@ -109,49 +108,48 @@ layout: home features: - icon: 🛠️ - title: Simple and minimal, always - details: Lorem ipsum... + title: いつでもシンプル＆ミニマル + details: 概要テキスト... - icon: src: /cool-feature-icon.svg - title: Another cool feature - details: Lorem ipsum... + title: もうひとつの便利機能 + details: 概要テキスト... - icon: dark: /dark-feature-icon.svg light: /light-feature-icon.svg - title: Another cool feature - details: Lorem ipsum... + title: さらに別の機能 + details: 概要テキスト... --- ``` ```ts interface Feature { - // Show icon on each feature box. + // 各フィーチャーボックスに表示するアイコン。 icon?: FeatureIcon - // Title of the feature. + // フィーチャーのタイトル。 title: string - // Details of the feature. + // フィーチャーの詳細説明。 details: string - // Link when clicked on feature component. The link can - // be both internal or external. + // フィーチャーをクリックしたときのリンク（内部・外部どちらも可）。 // - // e.g. `guide/reference/default-theme-home-page` or `https://example.com` + // 例: `guide/reference/default-theme-home-page` や `https://example.com` link?: string - // Link text to be shown inside feature component. Best - // used with `link` option. + // フィーチャー内に表示するリンクテキスト。 + // `link` と併用するのが最適。 // - // e.g. `Learn more`, `Visit page`, etc. + // 例: `Learn more`, `Visit page` など linkText?: string - // Link rel attribute for the `link` option. + // `link` 用の rel 属性。 // - // e.g. `external` + // 例: `external` rel?: string - // Link target attribute for the `link` option. + // `link` 用の target 属性。 target?: string } @@ -167,9 +165,9 @@ type FeatureIcon = } ``` -## Markdown Content +## Markdown コンテンツ -You can add additional content to your site's homepage just by adding Markdown below the `---` frontmatter divider. +`---` で区切るフロントマターの下に Markdown を書くだけで、ホームページに追加コンテンツを表示できます。 ````md --- @@ -180,16 +178,11 @@ hero: text: Vite & Vue powered static site generator. --- -## Getting Started +## はじめに -You can get started using VitePress right away using `npx`! +`npx` を使えば、すぐに VitePress を始められます！ ```sh npm init npx vitepress init ``` -```` - -::: info -VitePress didn't always auto-style the extra content of the `layout: home` page. To revert to older behavior, you can add `markdownStyles: false` to the frontmatter. -::: diff --git a/docs/ja/reference/default-theme-last-updated.md b/docs/ja/reference/default-theme-last-updated.md index 55603269923f..10e1dd5ef825 100644 --- a/docs/ja/reference/default-theme-last-updated.md +++ b/docs/ja/reference/default-theme-last-updated.md @@ -1,13 +1,13 @@ -# Last Updated +# 最終更新日時 -The update time of the last content will be displayed in the lower right corner of the page. To enable it, add `lastUpdated` options to your config. +ページ右下に、コンテンツの最終更新時刻を表示できます。有効化するには、設定に `lastUpdated` オプションを追加します。 ::: info -VitePress displays the "last updated" time using the timestamp of the most recent Git commit for each file. To enable this, the Markdown file must be committed to Git. +VitePress は各ファイルの **直近の Git コミットのタイムスタンプ** を用いて「最終更新」を表示します。これを有効にするには、対象の Markdown ファイルが Git にコミットされている必要があります。 -Internally, VitePress runs `git log -1 --pretty="%ai"` on each file to retrieve its timestamp. If all pages show the same update time, it's likely due to shallow cloning (common in CI environments), which limits Git history. +内部的には、各ファイルに対して `git log -1 --pretty="%ai"` を実行してタイムスタンプを取得します。すべてのページで同じ更新時刻が表示される場合、（CI 環境でよくある）**浅いクローン（shallow clone）** により Git の履歴が取得できていない可能性があります。 -To fix this in **GitHub Actions**, use the following in your workflow: +**GitHub Actions** での修正例は次のとおりです。 ```yaml{4} - name: Checkout @@ -16,16 +16,16 @@ To fix this in **GitHub Actions**, use the following in your workflow: fetch-depth: 0 ``` -Other CI/CD platforms have similar settings. +他の CI/CD プラットフォームでも同様の設定が用意されています。 -If such options aren't available, you can prepend the `docs:build` command in your `package.json` with a manual fetch: +もしそのようなオプションが使えない場合は、`package.json` のビルドスクリプトで手動フェッチを前置してください。 ```json "docs:build": "git fetch --unshallow && vitepress build docs" ``` ::: -## Site-Level Config +## サイトレベルの設定 ```js export default { @@ -33,9 +33,9 @@ export default { } ``` -## Frontmatter Config +## フロントマターでの設定 -This can be disabled per-page using the `lastUpdated` option on frontmatter: +ページ単位で無効化するには、フロントマターで `lastUpdated` を指定します。 ```yaml --- @@ -43,4 +43,4 @@ lastUpdated: false --- ``` -Also refer [Default Theme: Last Updated](./default-theme-config#lastupdated) for more details. Any truthy value at theme-level will also enable the feature unless explicitly disabled at site or page level. +より詳しくは [デフォルトテーマ: 最終更新](./default-theme-config#lastupdated) を参照してください。テーマレベルで truthy な値を設定すると、サイトまたはページで明示的に無効化しない限り、この機能は有効になります。 diff --git a/docs/ja/reference/default-theme-layout.md b/docs/ja/reference/default-theme-layout.md index 246e20fa9f04..15b7491b6f07 100644 --- a/docs/ja/reference/default-theme-layout.md +++ b/docs/ja/reference/default-theme-layout.md @@ -1,6 +1,6 @@ -# Layout +# レイアウト -You may choose the page layout by setting `layout` option to the page [frontmatter](./frontmatter-config). There are 3 layout options, `doc`, `page`, and `home`. If nothing is specified, then the page is treated as `doc` page. +ページの [フロントマター](./frontmatter-config) の `layout` オプションでページのレイアウトを選択できます。利用可能なレイアウトは `doc`、`page`、`home` の 3 種類です。何も指定しない場合は `doc` として扱われます。 ```yaml --- @@ -8,38 +8,38 @@ layout: doc --- ``` -## Doc Layout +## Doc レイアウト -Option `doc` is the default layout and it styles the whole Markdown content into "documentation" look. It works by wrapping whole content within `vp-doc` css class, and applying styles to elements underneath it. +`doc` は既定のレイアウトで、Markdown 全体を「ドキュメント」風にスタイリングします。コンテンツ全体を `vp-doc` という CSS クラスでラップし、その配下の要素にスタイルを適用します。 -Almost all generic elements such as `p`, or `h2` get special styling. Therefore, keep in mind that if you add any custom HTML inside a Markdown content, those will get affected by those styles as well. +`p` や `h2` などほぼすべての汎用要素に特別なスタイルが当たります。そのため、Markdown 内にカスタム HTML を追加した場合も、これらのスタイルの影響を受ける点に注意してください。 -It also provides documentation specific features listed below. These features are only enabled in this layout. +また、以下のようなドキュメント特有の機能も提供します。これらはこのレイアウトでのみ有効になります。 -- Edit Link -- Prev Next Link -- Outline -- [Carbon Ads](./default-theme-carbon-ads) +- 編集リンク（Edit Link） +- 前後リンク（Prev / Next Link） +- アウトライン（Outline） +- [Carbon 広告](./default-theme-carbon-ads) -## Page Layout +## Page レイアウト -Option `page` is treated as "blank page". The Markdown will still be parsed, and all of the [Markdown Extensions](../guide/markdown) work as same as `doc` layout, but it wouldn't get any default stylings. +`page` は「ブランクページ」として扱われます。Markdown はパースされ、[Markdown 拡張](../guide/markdown) も `doc` と同様に機能しますが、既定のスタイルは適用されません。 -The page layout will let you style everything by you without VitePress theme affecting the markup. This is useful when you want to create your own custom page. +このレイアウトでは、VitePress テーマにマークアップを干渉させず、すべてを自分でスタイルできます。独自のカスタムページを作成したい場合に便利です。 -Note that even in this layout, sidebar will still show up if the page has a matching sidebar config. +なお、このレイアウトでも、ページがサイドバー設定に一致する場合はサイドバーが表示されます。 -## Home Layout +## Home レイアウト -Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Default Theme: Home Page](./default-theme-home-page) for more details. +`home` はテンプレート化された「ホームページ」を生成します。このレイアウトでは、`hero` や `features` などの追加オプションでコンテンツをさらにカスタマイズできます。詳しくは [デフォルトテーマ: ホームページ](./default-theme-home-page) を参照してください。 -## No Layout +## レイアウトなし -If you don't want any layout, you can pass `layout: false` through frontmatter. This option is helpful if you want a fully-customizable landing page (without any sidebar, navbar, or footer by default). +レイアウトを一切適用したくない場合は、フロントマターで `layout: false` を指定します。これは（既定でサイドバー／ナビバー／フッターなしの）完全にカスタマイズ可能なランディングページを作りたい場合に役立ちます。 -## Custom Layout +## カスタムレイアウト -You can also use a custom layout: +カスタムレイアウトを使用することもできます。 ```md --- @@ -47,7 +47,7 @@ layout: foo --- ``` -This will look for a component named `foo` registered in context. For example, you can register your component globally in `.vitepress/theme/index.ts`: +これは、コンテキストに登録された `foo` という名前のコンポーネントを探します。たとえば、`.vitepress/theme/index.ts` でグローバル登録できます。 ```ts import DefaultTheme from 'vitepress/theme' diff --git a/docs/ja/reference/default-theme-nav.md b/docs/ja/reference/default-theme-nav.md index f7be114dbacc..593b57f4eb99 100644 --- a/docs/ja/reference/default-theme-nav.md +++ b/docs/ja/reference/default-theme-nav.md @@ -1,10 +1,10 @@ -# Nav +# ナビゲーション -The Nav is the navigation bar displayed on top of the page. It contains the site title, global menu links, etc. +ナビはページ上部に表示されるナビゲーションバーです。サイトタイトル、グローバルメニューリンクなどを含みます。 -## Site Title and Logo +## サイトタイトルとロゴ -By default, nav shows the title of the site referencing [`config.title`](./site-config#title) value. If you would like to change what's displayed on nav, you may define custom text in `themeConfig.siteTitle` option. +既定では、ナビには [`config.title`](./site-config#title) の値が表示されます。ナビに表示する文字列を変更したい場合は、`themeConfig.siteTitle` にカスタム文字列を指定します。 ```js export default { @@ -14,7 +14,7 @@ export default { } ``` -If you have a logo for your site, you can display it by passing in the path to the image. You should place the logo within `public` directly, and define the absolute path to it. +サイトのロゴがある場合は、画像へのパスを渡すと表示できます。ロゴは `public` 直下に配置し、絶対パスで指定してください。 ```js export default { @@ -24,7 +24,7 @@ export default { } ``` -When adding a logo, it gets displayed along with the site title. If your logo is all you need and if you would like to hide the site title text, set `false` to the `siteTitle` option. +ロゴを追加すると、サイトタイトルと並んで表示されます。ロゴだけを表示したい場合は、`siteTitle` を `false` に設定してタイトル文字列を非表示にできます。 ```js export default { @@ -35,11 +35,11 @@ export default { } ``` -You can also pass an object as logo if you want to add `alt` attribute or customize it based on dark/light mode. Refer [`themeConfig.logo`](./default-theme-config#logo) for details. +ダーク／ライトモードでロゴを切り替えたり、`alt` 属性を付けたい場合は、ロゴにオブジェクトを渡すこともできます。詳細は [`themeConfig.logo`](./default-theme-config#logo) を参照してください。 -## Navigation Links +## ナビゲーションリンク -You may define `themeConfig.nav` option to add links to your nav. +`themeConfig.nav` オプションでナビにリンクを追加できます。 ```js export default { @@ -53,11 +53,11 @@ export default { } ``` -The `text` is the actual text displayed in nav, and the `link` is the link that will be navigated to when the text is clicked. For the link, set path to the actual file without `.md` prefix, and always start with `/`. +`text` はナビに表示される文字列、`link` はクリック時に遷移するリンクです。内部リンクは `.md` 拡張子を付けず、必ず `/` で始めるようにしてください。 -The `link` can also be a function that accepts [`PageData`](./runtime-api#usedata) as the argument and returns the path. +`link` には、[`PageData`](./runtime-api#usedata) を受け取ってパスを返す関数を指定することもできます。 -Nav links can also be dropdown menus. To do this, set `items` key on link option. +ナビリンクはドロップダウンメニューにもできます。リンクオプションに `items` を設定してください。 ```js export default { @@ -77,9 +77,9 @@ export default { } ``` -Note that dropdown menu title (`Dropdown Menu` in the above example) can not have `link` property since it becomes a button to open dropdown dialog. +なお、ドロップダウンのタイトル（上の例の `Dropdown Menu`）には `link` は設定できません。ドロップダウンを開くボタンになるためです。 -You may further add "sections" to the dropdown menu items as well by passing in more nested items. +さらに、ドロップダウン内を「セクション」に分けることもできます（入れ子の `items` を使います）。 ```js export default { @@ -90,7 +90,7 @@ export default { text: 'Dropdown Menu', items: [ { - // Title for the section. + // セクションのタイトル text: 'Section A Title', items: [ { text: 'Section A Item A', link: '...' }, @@ -103,7 +103,7 @@ export default { text: 'Dropdown Menu', items: [ { - // You may also omit the title. + // タイトルは省略することも可能 items: [ { text: 'Section A Item A', link: '...' }, { text: 'Section B Item B', link: '...' } @@ -116,16 +116,15 @@ export default { } ``` -### Customize link's "active" state +### リンクの「アクティブ」状態をカスタマイズ -Nav menu items will be highlighted when the current page is under the matching path. if you would like to customize the path to be matched, define `activeMatch` property and regex as a string value. +現在のページが特定のパス配下にあるとき、該当するナビ項目がハイライトされます。一致させるパスをカスタマイズしたい場合は、`activeMatch` に **正規表現文字列** を指定します。 ```js export default { themeConfig: { nav: [ - // This link gets active state when the user is - // on `/config/` path. + // ユーザーが `/config/` 配下にいるときにアクティブになる { text: 'Guide', link: '/guide', @@ -137,12 +136,12 @@ export default { ``` ::: warning -`activeMatch` is expected to be a regex string, but you must define it as a string. We can't use actual RegExp object here because it isn't serializable during the build time. +`activeMatch` は正規表現 **オブジェクト** ではなく、**文字列** で指定してください。ビルド時のシリアライズの都合で `RegExp` は使用できません。 ::: -### Customize link's "target" and "rel" attributes +### リンクの `target` と `rel` をカスタマイズ -By default, VitePress automatically determines `target` and `rel` attributes based on whether the link is an external link. But if you want, you can customize them too. +既定では、リンクが外部かどうかに応じて VitePress が `target` と `rel` を自動設定します。必要であれば明示的に指定することもできます。 ```js export default { @@ -159,13 +158,13 @@ export default { } ``` -## Social Links +## ソーシャルリンク -Refer [`socialLinks`](./default-theme-config#sociallinks). +[`socialLinks`](./default-theme-config#sociallinks) を参照してください。 -## Custom Components +## カスタムコンポーネント -You can include custom components in the navigation bar by using the `component` option. The `component` key should be the Vue component name, and must be registered globally using [Theme.enhanceApp](../guide/custom-theme#theme-interface). +`component` オプションを使って、ナビゲーションバーにカスタムコンポーネントを配置できます。`component` には Vue コンポーネント名を指定し、[Theme.enhanceApp](../guide/custom-theme#theme-interface) で **グローバル登録** しておく必要があります。 ```js [.vitepress/config.js] export default { @@ -176,7 +175,7 @@ export default { items: [ { component: 'MyCustomComponent', - // Optional props to pass to the component + // コンポーネントに渡す任意の props props: { title: 'My Custom Component' } @@ -191,7 +190,7 @@ export default { } ``` -Then, you need to register the component globally: +次に、コンポーネントをグローバル登録します。 ```js [.vitepress/theme/index.js] import DefaultTheme from 'vitepress/theme' @@ -209,8 +208,8 @@ export default { } ``` -Your component will be rendered in the navigation bar. VitePress will provide the following additional props to the component: +コンポーネントはナビゲーションバー内にレンダリングされます。VitePress は次の追加 props をコンポーネントに提供します。 -- `screenMenu`: an optional boolean indicating whether the component is inside mobile navigation menu +- `screenMenu`: モバイルのナビメニュー内にあるかどうかを示す任意の boolean -You can check an example in the e2e tests [here](https://github.com/vuejs/vitepress/tree/main/__tests__/e2e/.vitepress). +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 index 7befe179b5bc..659cc0e0f09d 100644 --- a/docs/ja/reference/default-theme-prev-next-links.md +++ b/docs/ja/reference/default-theme-prev-next-links.md @@ -1,18 +1,18 @@ -# Prev Next Links +# 前／次リンク -You can customize the text and link for the previous and next pages (shown at doc footer). This is helpful if you want a different text there than what you have on your sidebar. Additionally, you may find it useful to disable the footer or link to a page that is not included in your sidebar. +ドキュメントのフッターに表示される「前のページ」「次のページ」のテキストとリンクをカスタマイズできます。サイドバーに表示しているタイトルとは別の文言を使いたい場合や、フッターを無効化したり、サイドバーに含まれていないページへリンクしたい場合に便利です。 ## prev -- Type: `string | false | { text?: string; link?: string }` +- 型: `string | false | { text?: string; link?: string }` -- Details: +- 詳細: - Specifies the text/link to show on the link to the previous page. If you don't set this in frontmatter, the text/link will be inferred from the sidebar config. + 前のページへのリンクに表示するテキスト／リンクを指定します。フロントマターで設定しない場合は、サイドバー設定から自動推測されます。 -- Examples: +- 例: - - To customize only the text: + - テキストだけをカスタマイズ: ```yaml --- @@ -20,7 +20,7 @@ You can customize the text and link for the previous and next pages (shown at do --- ``` - - To customize both text and link: + - テキストとリンクの両方をカスタマイズ: ```yaml --- @@ -30,7 +30,7 @@ You can customize the text and link for the previous and next pages (shown at do --- ``` - - To hide previous page: + - 前のページを非表示にする: ```yaml --- @@ -40,4 +40,4 @@ You can customize the text and link for the previous and next pages (shown at do ## next -Same as `prev` but for the next page. +`prev` と同様ですが、次のページ用の設定です。 diff --git a/docs/ja/reference/default-theme-search.md b/docs/ja/reference/default-theme-search.md index 6bc2f4462cfd..b3a10bde079a 100644 --- a/docs/ja/reference/default-theme-search.md +++ b/docs/ja/reference/default-theme-search.md @@ -2,11 +2,11 @@ outline: deep --- -# Search +# 検索 -## Local Search +## ローカル検索 -VitePress supports fuzzy full-text search using an in-browser index thanks to [minisearch](https://github.com/lucaong/minisearch/). To enable this feature, simply set the `themeConfig.search.provider` option to `'local'` in your `.vitepress/config.ts` file: +VitePress は、[minisearch](https://github.com/lucaong/minisearch/) によるブラウザ内インデックスを使った曖昧一致の全文検索をサポートします。有効化するには、`.vitepress/config.ts` で `themeConfig.search.provider` を `'local'` に設定します。 ```ts import { defineConfig } from 'vitepress' @@ -20,11 +20,11 @@ export default defineConfig({ }) ``` -Example result: +表示例: ![screenshot of the search modal](/search.png) -Alternatively, you can use [Algolia DocSearch](#algolia-search) or some community plugins like: +代わりに [Algolia DocSearch](#algolia-search) や、次のコミュニティ製プラグインを使うこともできます。 - - @@ -32,7 +32,7 @@ Alternatively, you can use [Algolia DocSearch](#algolia-search) or some communit ### i18n {#local-search-i18n} -You can use a config like this to use multilingual search: +多言語検索を行う設定例です。 ```ts import { defineConfig } from 'vitepress' @@ -43,7 +43,7 @@ export default defineConfig({ provider: 'local', options: { locales: { - zh: { // make this `root` if you want to translate the default locale + zh: { // 既定ロケールの文言も翻訳したい場合はこれを `root` に translations: { button: { buttonText: '搜索', @@ -73,9 +73,9 @@ export default defineConfig({ }) ``` -### miniSearch options +### miniSearch のオプション -You can configure MiniSearch like this: +MiniSearch の設定例です。 ```ts import { defineConfig } from 'vitepress' @@ -107,11 +107,11 @@ export default defineConfig({ }) ``` -Learn more in [MiniSearch docs](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html). +詳しくは [MiniSearch のドキュメント](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html) を参照してください。 -### Custom content renderer +### コンテンツレンダラーのカスタマイズ -You can customize the function used to render the markdown content before indexing it: +インデックス前に Markdown コンテンツをレンダリングする関数をカスタマイズできます。 ```ts import { defineConfig } from 'vitepress' @@ -127,7 +127,7 @@ export default defineConfig({ * @param {import('markdown-it-async')} md */ async _render(src, env, md) { - // return html string + // HTML 文字列を返す } } } @@ -135,11 +135,11 @@ export default defineConfig({ }) ``` -This function will be stripped from client-side site data, so you can use Node.js APIs in it. +この関数はクライアント側のサイトデータからは除外されるため、Node.js の API を使用できます。 -#### Example: Excluding pages from search +#### 例: 検索対象からページを除外する -You can exclude pages from search by adding `search: false` to the frontmatter of the page. Alternatively: +フロントマターに `search: false` を追加すると、そのページを検索対象から除外できます。あるいは次のようにもできます。 ```ts import { defineConfig } from 'vitepress' @@ -161,11 +161,11 @@ export default defineConfig({ }) ``` -::: warning Note -In case a custom `_render` function is provided, you need to handle the `search: false` frontmatter yourself. Also, the `env` object won't be completely populated before `md.renderAsync` is called, so any checks on optional `env` properties like `frontmatter` should be done after that. +::: warning 注意 +カスタムの `_render` 関数を提供する場合、`search: false` の処理は自分で行う必要があります。また、`env` は `md.renderAsync` の呼び出し前には完全ではないため、`frontmatter` などの任意プロパティのチェックはその後に行ってください。 ::: -#### Example: Transforming content - adding anchors +#### 例: コンテンツの変換 — 見出しアンカーを追加 ```ts import { defineConfig } from 'vitepress' @@ -187,9 +187,9 @@ export default defineConfig({ }) ``` -## Algolia Search +## Algolia 検索 -VitePress supports searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Refer their getting started guide. In your `.vitepress/config.ts` you'll need to provide at least the following to make it work: +VitePress は [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch) によるサイト検索をサポートします。導入は公式のガイドを参照してください。`.vitepress/config.ts` では最低限次の設定が必要です。 ```ts import { defineConfig } from 'vitepress' @@ -210,7 +210,7 @@ export default defineConfig({ ### i18n {#algolia-search-i18n} -You can use a config like this to use multilingual search: +多言語検索の設定例です。 ```ts import { defineConfig } from 'vitepress' @@ -303,11 +303,11 @@ export default defineConfig({ }) ``` -[These options](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) can be overridden. Refer official Algolia docs to learn more about them. +[これらのオプション](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) は上書きできます。詳細は Algolia の公式ドキュメントを参照してください。 -### Algolia Ask AI Support {#ask-ai} +### Algolia Ask AI のサポート {#ask-ai} -If you would like to include **Ask AI**, pass the `askAi` option (or any of the partial fields) inside `options`: +**Ask AI** を有効にするには、`options` 内に `askAi` オプション（またはその一部）を指定します。 ```ts import { defineConfig } from 'vitepress' @@ -321,11 +321,11 @@ export default defineConfig({ apiKey: '...', indexName: '...', // askAi: "YOUR-ASSISTANT-ID" - // OR + // または askAi: { - // at minimum you must provide the assistantId you received from Algolia + // 少なくとも Algolia から受け取った assistantId を指定 assistantId: 'XXXYYY', - // optional overrides – if omitted, the top-level appId/apiKey/indexName values are reused + // 任意の上書き — 省略時は上位の appId/apiKey/indexName を再利用 // apiKey: '...', // appId: '...', // indexName: '...' @@ -336,15 +336,15 @@ export default defineConfig({ }) ``` -::: warning Note -If want to default to keyword search and do not want to use Ask AI, just omit the `askAi` property +::: warning 注意 +キーワード検索を既定にして Ask AI を使わない場合は、`askAi` を指定しないでください。 ::: -The translations for the Ask AI UI live under `options.translations.modal.askAiScreen` and `options.translations.resultsScreen` — see the [type definitions](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) for all keys. +Ask AI UI の翻訳は `options.translations.modal.askAiScreen` と `options.translations.resultsScreen` にあります。すべてのキーは[型定義](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts)を参照してください。 -### Crawler Config +### クローラー設定 -Here is an example config based on what this site uses: +このサイトで使用している設定を元にした例です。 ```ts new Crawler({ diff --git a/docs/ja/reference/default-theme-sidebar.md b/docs/ja/reference/default-theme-sidebar.md index 67893cf6edd8..91d620765cc2 100644 --- a/docs/ja/reference/default-theme-sidebar.md +++ b/docs/ja/reference/default-theme-sidebar.md @@ -1,6 +1,6 @@ -# Sidebar +# サイドバー -The sidebar is the main navigation block for your documentation. You can configure the sidebar menu in [`themeConfig.sidebar`](./default-theme-config#sidebar). +サイドバーはドキュメントの主要なナビゲーションブロックです。[`themeConfig.sidebar`](./default-theme-config#sidebar) でメニューを設定できます。 ```js export default { @@ -19,9 +19,9 @@ export default { } ``` -## The Basics +## 基本 -The simplest form of the sidebar menu is passing in a single array of links. The first level item defines the "section" for the sidebar. It should contain `text`, which is the title of the section, and `items` which are the actual navigation links. +最もシンプルな構成は、リンクの配列を 1 つ渡す方法です。第 1 階層のアイテムがサイドバーの「セクション」を表します。各セクションは `text`（セクションのタイトル）と、実際のナビゲーションリンクである `items` を持ちます。 ```js export default { @@ -48,7 +48,7 @@ export default { } ``` -Each `link` should specify the path to the actual file starting with `/`. If you add trailing slash to the end of link, it will show `index.md` of the corresponding directory. +各 `link` は `/` で始まる実ファイルへのパスを指定します。リンクの末尾を `/` で終わらせると、対応するディレクトリの `index.md` が表示されます。 ```js export default { @@ -57,7 +57,7 @@ export default { { text: 'Guide', items: [ - // This shows `/guide/index.md` page. + // `/guide/index.md` を表示 { text: 'Introduction', link: '/guide/' } ] } @@ -66,7 +66,7 @@ export default { } ``` -You may further nest the sidebar items up to 6 level deep counting up from the root level. Note that deeper than 6 level of nested items gets ignored and will not be displayed on the sidebar. +サイドバーのアイテムは、ルートから数えて最大 6 階層まで入れ子にできます。7 階層以上は無視され、表示されません。 ```js export default { @@ -93,11 +93,11 @@ export default { } ``` -## Multiple Sidebars +## 複数のサイドバー -You may show different sidebar depending on the page path. For example, as shown on this site, you might want to create a separate sections of content in your documentation like "Guide" page and "Config" page. +ページのパスに応じて異なるサイドバーを表示できます。たとえば、このサイトのように「Guide」セクションと「Config」セクションでナビゲーションを分けたい場合に便利です。 -To do so, first organize your pages into directories for each desired section: +まず、対象のセクションごとにディレクトリを分けてページを配置します。 ``` . @@ -111,14 +111,13 @@ To do so, first organize your pages into directories for each desired section: └─ four.md ``` -Then, update your configuration to define your sidebar for each section. This time, you should pass an object instead of an array. +次に、各セクション用のサイドバーを設定します。この場合、配列ではなくオブジェクトを渡します。 ```js export default { themeConfig: { sidebar: { - // This sidebar gets displayed when a user - // is on `guide` directory. + // ユーザーが `guide` ディレクトリ配下にいるときに表示 '/guide/': [ { text: 'Guide', @@ -130,8 +129,7 @@ export default { } ], - // This sidebar gets displayed when a user - // is on `config` directory. + // ユーザーが `config` ディレクトリ配下にいるときに表示 '/config/': [ { text: 'Config', @@ -147,9 +145,9 @@ export default { } ``` -## Collapsible Sidebar Groups +## 折りたたみ可能なサイドバーグループ -By adding `collapsed` option to the sidebar group, it shows a toggle button to hide/show each section. +サイドバーグループに `collapsed` オプションを追加すると、各セクションの開閉トグルが表示されます。 ```js export default { @@ -165,7 +163,7 @@ export default { } ``` -All sections are "open" by default. If you would like them to be "closed" on initial page load, set `collapsed` option to `true`. +既定ではすべてのセクションが「開いた」状態です。初回表示時に「閉じた」状態にしたい場合は、`collapsed` を `true` に設定します。 ```js export default { diff --git a/docs/ja/reference/default-theme-team-page.md b/docs/ja/reference/default-theme-team-page.md index 6c37c6a752d8..3dc76623b74b 100644 --- a/docs/ja/reference/default-theme-team-page.md +++ b/docs/ja/reference/default-theme-team-page.md @@ -23,13 +23,13 @@ const members = [ ] -# Team Page +# チームページ -If you would like to introduce your team, you may use Team components to construct the Team Page. There are two ways of using these components. One is to embed it in doc page, and another is to create a full Team Page. +チームを紹介したい場合は、Team コンポーネント群を使ってチームページを構成できます。使い方は 2 通りあり、ドキュメントページに埋め込む方法と、専用のチームページを作成する方法があります。 -## Show team members in a page +## ページ内にメンバー一覧を表示する -You may use `` component exposed from `vitepress/theme` to display a list of team members on any page. +任意のページでチームメンバーの一覧を表示するには、`vitepress/theme` からエクスポートされている `` コンポーネントを使用します。 ```html -# Our Team +# 私たちのチーム -Say hello to our awesome team. +私たちの素晴らしいチームを紹介します。 ``` -The above will display a team member in card looking element. It should display something similar to below. +上記のように、カード風の要素でメンバーが表示されます。下図のような見た目になります。 -`` component comes in 2 different sizes, `small` and `medium`. While it boils down to your preference, usually `small` size should fit better when used in doc page. Also, you may add more properties to each member such as adding "description" or "sponsor" button. Learn more about it in [``](#vpteammembers). +`` コンポーネントには `small` と `medium` の 2 種類のサイズがあります。好みによりますが、ドキュメントページ内で使う場合は `small` が馴染みやすいことが多いでしょう。各メンバーに「説明文」や「スポンサー」ボタンなど、追加のプロパティを付けることもできます。詳細は [``](#vpteammembers) を参照してください。 -Embedding team members in doc page is good for small size team where having dedicated full team page might be too much, or introducing partial members as a reference to documentation context. +小規模なチームで専用ページまでは不要な場合や、文脈上の参考として一部のメンバーのみを紹介したい場合は、ドキュメントページへ埋め込む方法が適しています。 -If you have large number of members, or simply would like to have more space to show team members, consider [creating a full team page](#create-a-full-team-page). +メンバーが多い場合や、より広いスペースで紹介したい場合は、[専用のチームページを作成する](#専用のチームページを作成する) ことを検討してください。 -## Create a full Team Page +## 専用のチームページを作成する -Instead of adding team members to doc page, you may also create a full Team Page, similar to how you can create a custom [Home Page](./default-theme-home-page). +ドキュメントページにメンバーを追加する代わりに、カスタムの [ホームページ](./default-theme-home-page) と同様、専用のチームページを作成することもできます。 -To create a team page, first, create a new md file. The file name doesn't matter, but here lets call it `team.md`. In this file, set frontmatter option `layout: page`, and then you may compose your page structure using `TeamPage` components. +まず新しい md ファイルを作成します。ファイル名は任意ですが、ここでは `team.md` とします。このファイルでフロントマターに `layout: page` を設定し、その後 `TeamPage` コンポーネント群を使ってページを構成します。 ```html --- @@ -100,28 +100,28 @@ const members = [ ``` -When creating a full team page, remember to wrap all components with `` component. This component will ensure all nested team related components get the proper layout structure like spacings. +専用のチームページを作る際は、必ずすべてのチーム関連コンポーネントを `` でラップしてください。レイアウトや余白などが適切に適用されます。 -`` component adds the page title section. The title being `

` heading. Use `#title` and `#lead` slot to document about your team. +`` はページタイトルのセクションを追加します。タイトルは `

` 見出しになります。`#title` と `#lead` スロットでチームについて説明を書きましょう。 -`` works as same as when used in a doc page. It will display list of members. +`` はドキュメントページで使う場合と同様に、メンバー一覧を表示します。 -### Add sections to divide team members +### セクションを追加してメンバーを分ける -You may add "sections" to the team page. For example, you may have different types of team members such as Core Team Members and Community Partners. You can divide these members into sections to better explain the roles of each group. +チームページに「セクション」を追加できます。たとえば、コアメンバーとコミュニティパートナーなど、役割ごとにメンバーを分けて説明しやすくできます。 -To do so, add `` component to the `team.md` file we created previously. +そのためには、先ほど作成した `team.md` に `` コンポーネントを追加します。 ```html --- @@ -141,12 +141,12 @@ const partners = [...] - + - +