mirror of https://github.com/vuejs/vitepress
nilennoct
1 month ago
committed by
GitHub
commit
fc2baec39e
@ -0,0 +1,77 @@
|
||||
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
|
||||
|
||||
exports[`node/postcss/isolateStyles > transforms selectors and skips keyframes 1`] = `
|
||||
"
|
||||
/* simple classes */
|
||||
.example:not(:where(.vp-raw, .vp-raw *)) { color: red; }
|
||||
.class-a:not(:where(.vp-raw, .vp-raw *)) { color: coral; }
|
||||
.class-b:not(:where(.vp-raw, .vp-raw *)) { color: deepskyblue; }
|
||||
|
||||
/* escaped colon in class */
|
||||
.baz\\:not\\(.bar\\):not(:where(.vp-raw, .vp-raw *)) { display: block; }
|
||||
.disabled\\:opacity-50:not(:where(.vp-raw, .vp-raw *)):disabled { opacity: .5; }
|
||||
|
||||
/* pseudos (class + element) */
|
||||
.button:not(:where(.vp-raw, .vp-raw *)):hover { color: pink; }
|
||||
.button:not(:where(.vp-raw, .vp-raw *)):focus:hover { color: hotpink; }
|
||||
.item:not(:where(.vp-raw, .vp-raw *))::before { content: '•'; }
|
||||
:not(:where(.vp-raw, .vp-raw *))::first-letter { color: pink; }
|
||||
:not(:where(.vp-raw, .vp-raw *))::before { content: ''; }
|
||||
|
||||
/* universal + :not */
|
||||
*:not(:where(.vp-raw, .vp-raw *)) { background-color: red; }
|
||||
*:not(:where(.vp-raw, .vp-raw *)):not(.b) { text-transform: uppercase; }
|
||||
|
||||
/* combinators */
|
||||
.foo:hover .bar:not(:where(.vp-raw, .vp-raw *)) { background: blue; }
|
||||
ul > li.active:not(:where(.vp-raw, .vp-raw *)) { color: green; }
|
||||
a + b ~ c:not(:where(.vp-raw, .vp-raw *)) { color: orange; }
|
||||
|
||||
/* ids + attribute selectors */
|
||||
#wow:not(:where(.vp-raw, .vp-raw *)) { color: yellow; }
|
||||
[data-world] .d:not(:where(.vp-raw, .vp-raw *)) { padding: 10px 20px; }
|
||||
|
||||
/* :root and chained tags */
|
||||
:not(:where(.vp-raw, .vp-raw *)):root { --bs-blue: #0d6efd; }
|
||||
:root .a:not(:where(.vp-raw, .vp-raw *)) { --bs-green: #bada55; }
|
||||
html:not(:where(.vp-raw, .vp-raw *)) { margin: 0; }
|
||||
body:not(:where(.vp-raw, .vp-raw *)) { padding: 0; }
|
||||
html body div:not(:where(.vp-raw, .vp-raw *)) { color: blue; }
|
||||
|
||||
/* grouping with commas */
|
||||
.a:not(:where(.vp-raw, .vp-raw *)), .b:not(:where(.vp-raw, .vp-raw *)) { color: red; }
|
||||
|
||||
/* multiple repeated groups to ensure stability */
|
||||
.a:not(:where(.vp-raw, .vp-raw *)), .b:not(:where(.vp-raw, .vp-raw *)) { color: coral; }
|
||||
.a:not(:where(.vp-raw, .vp-raw *)) { animation: glow 1s linear infinite alternate; }
|
||||
|
||||
/* nested blocks */
|
||||
.foo:not(:where(.vp-raw, .vp-raw *)) {
|
||||
svg:not(:where(.vp-raw, .vp-raw *)) { display: none; }
|
||||
.bar:not(:where(.vp-raw, .vp-raw *)) { display: inline; }
|
||||
}
|
||||
|
||||
/* standalone pseudos */
|
||||
:not(:where(.vp-raw, .vp-raw *)):first-child { color: pink; }
|
||||
:not(:where(.vp-raw, .vp-raw *)):hover { color: blue; }
|
||||
:not(:where(.vp-raw, .vp-raw *)):active { color: red; }
|
||||
|
||||
/* keyframes (should be ignored) */
|
||||
@keyframes fade {
|
||||
from { opacity: 0; }
|
||||
to { opacity: 1; }
|
||||
}
|
||||
@-webkit-keyframes glow {
|
||||
from { color: coral; }
|
||||
to { color: red; }
|
||||
}
|
||||
@-moz-keyframes glow {
|
||||
from { color: coral; }
|
||||
to { color: red; }
|
||||
}
|
||||
@-o-keyframes glow {
|
||||
from { color: coral; }
|
||||
to { color: red; }
|
||||
}
|
||||
"
|
||||
`;
|
||||
@ -0,0 +1,93 @@
|
||||
import { postcssIsolateStyles } from 'node/postcss/isolateStyles'
|
||||
import postcss from 'postcss'
|
||||
|
||||
const INPUT_CSS = `
|
||||
/* simple classes */
|
||||
.example { color: red; }
|
||||
.class-a { color: coral; }
|
||||
.class-b { color: deepskyblue; }
|
||||
|
||||
/* escaped colon in class */
|
||||
.baz\\:not\\(.bar\\) { display: block; }
|
||||
.disabled\\:opacity-50:disabled { opacity: .5; }
|
||||
|
||||
/* pseudos (class + element) */
|
||||
.button:hover { color: pink; }
|
||||
.button:focus:hover { color: hotpink; }
|
||||
.item::before { content: '•'; }
|
||||
::first-letter { color: pink; }
|
||||
::before { content: ''; }
|
||||
|
||||
/* universal + :not */
|
||||
* { background-color: red; }
|
||||
*:not(.b) { text-transform: uppercase; }
|
||||
|
||||
/* combinators */
|
||||
.foo:hover .bar { background: blue; }
|
||||
ul > li.active { color: green; }
|
||||
a + b ~ c { color: orange; }
|
||||
|
||||
/* ids + attribute selectors */
|
||||
#wow { color: yellow; }
|
||||
[data-world] .d { padding: 10px 20px; }
|
||||
|
||||
/* :root and chained tags */
|
||||
:root { --bs-blue: #0d6efd; }
|
||||
:root .a { --bs-green: #bada55; }
|
||||
html { margin: 0; }
|
||||
body { padding: 0; }
|
||||
html body div { color: blue; }
|
||||
|
||||
/* grouping with commas */
|
||||
.a, .b { color: red; }
|
||||
|
||||
/* multiple repeated groups to ensure stability */
|
||||
.a, .b { color: coral; }
|
||||
.a { animation: glow 1s linear infinite alternate; }
|
||||
|
||||
/* nested blocks */
|
||||
.foo {
|
||||
svg { display: none; }
|
||||
.bar { display: inline; }
|
||||
}
|
||||
|
||||
/* standalone pseudos */
|
||||
:first-child { color: pink; }
|
||||
:hover { color: blue; }
|
||||
:active { color: red; }
|
||||
|
||||
/* keyframes (should be ignored) */
|
||||
@keyframes fade {
|
||||
from { opacity: 0; }
|
||||
to { opacity: 1; }
|
||||
}
|
||||
@-webkit-keyframes glow {
|
||||
from { color: coral; }
|
||||
to { color: red; }
|
||||
}
|
||||
@-moz-keyframes glow {
|
||||
from { color: coral; }
|
||||
to { color: red; }
|
||||
}
|
||||
@-o-keyframes glow {
|
||||
from { color: coral; }
|
||||
to { color: red; }
|
||||
}
|
||||
`
|
||||
|
||||
describe('node/postcss/isolateStyles', () => {
|
||||
test('transforms selectors and skips keyframes', () => {
|
||||
const out = run(INPUT_CSS)
|
||||
expect(out.css).toMatchSnapshot()
|
||||
})
|
||||
|
||||
test('idempotent (running twice produces identical CSS)', () => {
|
||||
const first = run(INPUT_CSS).css
|
||||
const second = run(first).css
|
||||
expect(second).toBe(first)
|
||||
})
|
||||
})
|
||||
|
||||
function run(css: string, from = 'src/styles/vp-doc.css') {
|
||||
return postcss([postcssIsolateStyles()]).process(css, { from })
|
||||
}
|
||||
@ -1,2 +1,16 @@
|
||||
#!/usr/bin/env node
|
||||
// @ts-check
|
||||
|
||||
import module from 'node:module'
|
||||
|
||||
// https://github.com/vitejs/vite/blob/6c8a5a27e645a182f5b03a4ed6aa726eab85993f/packages/vite/bin/vite.js#L48-L63
|
||||
try {
|
||||
module.enableCompileCache?.()
|
||||
setTimeout(() => {
|
||||
try {
|
||||
module.flushCompileCache?.()
|
||||
} catch {}
|
||||
}, 10 * 1000).unref()
|
||||
} catch {}
|
||||
|
||||
import('../dist/node/cli.js')
|
||||
|
||||
@ -1,22 +0,0 @@
|
||||
import { defineConfig } from 'vitepress'
|
||||
import { shared } from './shared'
|
||||
import { en } from './en'
|
||||
import { zh } from './zh'
|
||||
import { pt } from './pt'
|
||||
import { ru } from './ru'
|
||||
import { es } from './es'
|
||||
import { ko } from './ko'
|
||||
import { fa } from './fa'
|
||||
|
||||
export default defineConfig({
|
||||
...shared,
|
||||
locales: {
|
||||
root: { label: 'English', ...en },
|
||||
zh: { label: '简体中文', ...zh },
|
||||
pt: { label: 'Português', ...pt },
|
||||
ru: { label: 'Русский', ...ru },
|
||||
es: { label: 'Español', ...es },
|
||||
ko: { label: '한국어', ...ko },
|
||||
fa: { label: 'فارسی', ...fa }
|
||||
}
|
||||
})
|
||||
@ -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<DefaultTheme.AlgoliaSearchOptions> {
|
||||
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: '提供: '
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,66 @@
|
||||
# アセットの取り扱い {#asset-handling}
|
||||
|
||||
## 静的アセットの参照 {#referencing-static-assets}
|
||||
|
||||
すべての Markdown ファイルは Vue コンポーネントにコンパイルされ、[Vite](https://vitejs.dev/guide/assets.html) によって処理されます。Markdown 内では、相対 URL を使ってアセットを参照することが **推奨されます**。
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
Markdown ファイル内、テーマの `*.vue` コンポーネント内、スタイルや通常の `.css` ファイル内でも、アセットはプロジェクトルートを基準とした絶対パス、またはファイルシステムを基準とした相対パスで参照できます。後者は Vite、Vue CLI、あるいは webpack の `file-loader` を使ったことがある場合に慣れ親しんだ挙動です。
|
||||
|
||||
一般的な画像、メディア、フォントファイルタイプは自動的にアセットとして検出され、含まれます。
|
||||
|
||||
::: tip リンクされたファイルはアセットとして扱われません
|
||||
Markdown ファイル内のリンクで参照された PDF やその他のドキュメントは、自動的にアセットとして扱われません。これらのリンクファイルにアクセスできるようにするには、手動でプロジェクトの [`public`](#the-public-directory) ディレクトリに配置する必要があります。
|
||||
:::
|
||||
|
||||
絶対パスを含むすべての参照されたアセットは、プロダクションビルド時にハッシュ化されたファイル名で出力ディレクトリにコピーされます。参照されないアセットはコピーされません。4kb 未満の画像アセットは base64 としてインライン化されます（これは [`vite`](../reference/site-config#vite) 設定オプションで変更可能です）。
|
||||
|
||||
すべての **静的な** パス参照（絶対パスを含む）は、作業ディレクトリの構造を基準にする必要があります。
|
||||
|
||||
## Public ディレクトリ {#the-public-directory}
|
||||
|
||||
Markdown やテーマコンポーネントで直接参照されない静的アセットを提供する必要がある場合や、特定のファイルをオリジナルのファイル名のまま提供したい場合があります。
|
||||
例えば `robots.txt`、favicon、PWA 用アイコンなどです。
|
||||
|
||||
これらのファイルは [ソースディレクトリ](./routing#source-directory) 配下の `public` ディレクトリに配置できます。たとえばプロジェクトルートが `./docs` で、デフォルトのソースディレクトリを使用している場合、`public` ディレクトリは `./docs/public` になります。
|
||||
|
||||
`public` に配置されたアセットは、出力ディレクトリのルートにそのままコピーされます。
|
||||
|
||||
なお、`public` 内のファイルはルート絶対パスで参照する必要があります。例えば `public/icon.png` は常に `/icon.png` として参照しなければなりません。
|
||||
|
||||
## ベース URL {#base-url}
|
||||
|
||||
サイトをルート以外の URL にデプロイする場合、`.vitepress/config.js` で `base` オプションを設定する必要があります。
|
||||
例えば `https://foo.github.io/bar/` にデプロイする場合、`base` は `'/bar/'` と設定します（必ずスラッシュで開始・終了する必要があります）。
|
||||
|
||||
すべての静的アセットパスは `base` 設定値に応じて自動的に調整されます。
|
||||
例えば Markdown 内で `public` 配下のアセットを絶対参照した場合：
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
この場合は `base` の設定値を変更しても、参照を修正する必要はありません。
|
||||
|
||||
ただし、テーマコンポーネントで動的にアセットをリンクする場合（例：テーマ設定値に基づいた画像の `src`）は注意が必要です。
|
||||
|
||||
```vue
|
||||
<img :src="theme.logoPath" />
|
||||
```
|
||||
|
||||
この場合は、VitePress が提供する [`withBase` ヘルパー](../reference/runtime-api#withbase) でパスをラップすることを推奨します。
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { withBase, useData } from 'vitepress'
|
||||
|
||||
const { theme } = useData()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<img :src="withBase(theme.logoPath)" />
|
||||
</template>
|
||||
```
|
||||
@ -0,0 +1,213 @@
|
||||
# カスタムテーマを使う {#using-a-custom-theme}
|
||||
|
||||
## テーマの解決 {#theme-resolving}
|
||||
|
||||
カスタムテーマを有効にするには、`.vitepress/theme/index.js` または `.vitepress/theme/index.ts` ファイル（「テーマエントリファイル」）を作成します。
|
||||
|
||||
```
|
||||
.
|
||||
├─ docs # プロジェクトルート
|
||||
│ ├─ .vitepress
|
||||
│ │ ├─ theme
|
||||
│ │ │ └─ index.js # テーマエントリ
|
||||
│ │ └─ config.js # 設定ファイル
|
||||
│ └─ index.md
|
||||
└─ package.json
|
||||
```
|
||||
|
||||
VitePress はテーマエントリファイルを検出すると、常にデフォルトテーマではなくカスタムテーマを使用します。ただし、[デフォルトテーマを拡張](./extending-default-theme) してその上で高度なカスタマイズを行うことも可能です。
|
||||
|
||||
## テーマインターフェース {#theme-interface}
|
||||
|
||||
VitePress のカスタムテーマは次のインターフェースを持つオブジェクトとして定義されます。
|
||||
|
||||
```ts
|
||||
interface Theme {
|
||||
/**
|
||||
* すべてのページに適用されるルートレイアウトコンポーネント
|
||||
* @required
|
||||
*/
|
||||
Layout: Component
|
||||
/**
|
||||
* Vue アプリインスタンスを拡張
|
||||
* @optional
|
||||
*/
|
||||
enhanceApp?: (ctx: EnhanceAppContext) => Awaitable<void>
|
||||
/**
|
||||
* 別のテーマを拡張し、そのテーマの `enhanceApp` を先に実行
|
||||
* @optional
|
||||
*/
|
||||
extends?: Theme
|
||||
}
|
||||
|
||||
interface EnhanceAppContext {
|
||||
app: App // Vue アプリインスタンス
|
||||
router: Router // VitePress のルーターインスタンス
|
||||
siteData: Ref<SiteData> // サイト全体のメタデータ
|
||||
}
|
||||
```
|
||||
|
||||
テーマエントリファイルでは、このテーマをデフォルトエクスポートとして公開します。
|
||||
|
||||
```js [.vitepress/theme/index.js]
|
||||
|
||||
// テーマエントリでは Vue ファイルを直接インポートできます
|
||||
// VitePress は @vitejs/plugin-vue をあらかじめ設定済みです
|
||||
import Layout from './Layout.vue'
|
||||
|
||||
export default {
|
||||
Layout,
|
||||
enhanceApp({ app, router, siteData }) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
デフォルトエクスポートはカスタムテーマにおける唯一の契約であり、必須なのは `Layout` プロパティだけです。つまり、VitePress のテーマは単一の Vue コンポーネントでも成り立ちます。
|
||||
|
||||
レイアウトコンポーネントの内部は通常の Vite + Vue 3 アプリケーションと同じように動作します。なお、テーマは [SSR 対応](./ssr-compat) である必要があります。
|
||||
|
||||
## レイアウトの構築 {#building-a-layout}
|
||||
|
||||
最も基本的なレイアウトコンポーネントには [`<Content />`](../reference/runtime-api#content) コンポーネントを含める必要があります。
|
||||
|
||||
```vue [.vitepress/theme/Layout.vue]
|
||||
<template>
|
||||
<h1>Custom Layout!</h1>
|
||||
|
||||
<!-- この部分に markdown コンテンツが描画されます -->
|
||||
<Content />
|
||||
</template>
|
||||
```
|
||||
|
||||
上記のレイアウトは、すべてのページの Markdown を単純に HTML として描画します。最初の改善点として 404 エラー処理を追加できます。
|
||||
|
||||
```vue{1-4,9-12}
|
||||
<script setup>
|
||||
import { useData } from 'vitepress'
|
||||
const { page } = useData()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<h1>Custom Layout!</h1>
|
||||
|
||||
<div v-if="page.isNotFound">
|
||||
Custom 404 page!
|
||||
</div>
|
||||
<Content v-else />
|
||||
</template>
|
||||
```
|
||||
|
||||
[`useData()`](../reference/runtime-api#usedata) ヘルパーを使うと、条件によってレイアウトを切り替えるために必要なすべてのランタイムデータを取得できます。アクセスできるデータのひとつにフロントマターがあります。これを利用すると、ページごとにレイアウトを制御できます。例えば、ユーザーが特別なホームページレイアウトを使いたい場合は以下のように記述します。
|
||||
|
||||
```md
|
||||
---
|
||||
layout: home
|
||||
---
|
||||
```
|
||||
|
||||
テーマ側を次のように調整します。
|
||||
|
||||
```vue{3,12-14}
|
||||
<script setup>
|
||||
import { useData } from 'vitepress'
|
||||
const { page, frontmatter } = useData()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<h1>Custom Layout!</h1>
|
||||
|
||||
<div v-if="page.isNotFound">
|
||||
Custom 404 page!
|
||||
</div>
|
||||
<div v-if="frontmatter.layout === 'home'">
|
||||
Custom home page!
|
||||
</div>
|
||||
<Content v-else />
|
||||
</template>
|
||||
```
|
||||
|
||||
もちろんレイアウトをさらにコンポーネントに分割することもできます。
|
||||
|
||||
```vue{3-5,12-15}
|
||||
<script setup>
|
||||
import { useData } from 'vitepress'
|
||||
import NotFound from './NotFound.vue'
|
||||
import Home from './Home.vue'
|
||||
import Page from './Page.vue'
|
||||
|
||||
const { page, frontmatter } = useData()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<h1>Custom Layout!</h1>
|
||||
|
||||
<NotFound v-if="page.isNotFound" />
|
||||
<Home v-if="frontmatter.layout === 'home'" />
|
||||
<Page v-else /> <!-- <Page /> が <Content /> を描画 -->
|
||||
</template>
|
||||
```
|
||||
|
||||
利用可能なすべての機能は [Runtime API リファレンス](../reference/runtime-api) を参照してください。さらに [ビルド時データ読み込み](./data-loading) を活用すれば、ブログ記事一覧ページのようなデータ駆動型のレイアウトも実現できます。
|
||||
|
||||
## カスタムテーマの配布 {#distributing-a-custom-theme}
|
||||
|
||||
最も簡単な配布方法は [GitHub のテンプレートリポジトリ](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository) として提供することです。
|
||||
|
||||
npm パッケージとして配布する場合は、次の手順を踏みます。
|
||||
|
||||
1. パッケージエントリでテーマオブジェクトをデフォルトエクスポートとして公開する。
|
||||
2. 必要であればテーマ設定の型定義を `ThemeConfig` として公開する。
|
||||
3. テーマが VitePress 設定の調整を必要とする場合は、パッケージのサブパス（例：`my-theme/config`）としてその設定を公開し、ユーザーが拡張できるようにする。
|
||||
4. 設定ファイルやフロントマターを通じて、テーマ設定オプションを文書化する。
|
||||
5. テーマの利用方法を明確に説明する（以下を参照）。
|
||||
|
||||
## カスタムテーマの利用 {#consuming-a-custom-theme}
|
||||
|
||||
|
||||
外部テーマを利用するには、カスタムテーマエントリからインポートして再エクスポートします。
|
||||
|
||||
```js [.vitepress/theme/index.js]
|
||||
import Theme from 'awesome-vitepress-theme'
|
||||
|
||||
export default Theme
|
||||
```
|
||||
|
||||
テーマを拡張する必要がある場合:
|
||||
|
||||
```js [.vitepress/theme/index.js]
|
||||
import Theme from 'awesome-vitepress-theme'
|
||||
|
||||
export default {
|
||||
extends: Theme,
|
||||
enhanceApp(ctx) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
テーマが特別な VitePress 設定を必要とする場合は、設定ファイルも拡張する必要があります。
|
||||
|
||||
```ts [.vitepress/config.ts]
|
||||
import baseConfig from 'awesome-vitepress-theme/config'
|
||||
|
||||
export default {
|
||||
// 必要に応じてテーマの基本設定を拡張
|
||||
extends: baseConfig
|
||||
}
|
||||
```
|
||||
|
||||
テーマがテーマ設定用の型を提供している場合:
|
||||
|
||||
```ts [.vitepress/config.ts]
|
||||
import baseConfig from 'awesome-vitepress-theme/config'
|
||||
import { defineConfigWithTheme } from 'vitepress'
|
||||
import type { ThemeConfig } from 'awesome-vitepress-theme'
|
||||
|
||||
export default defineConfigWithTheme<ThemeConfig>({
|
||||
extends: baseConfig,
|
||||
themeConfig: {
|
||||
// 型は `ThemeConfig`
|
||||
}
|
||||
})
|
||||
```
|
||||
@ -0,0 +1,48 @@
|
||||
# フロントマター {#frontmatter}
|
||||
|
||||
## 使い方 {#usage}
|
||||
|
||||
VitePress はすべての Markdown ファイルで YAML フロントマターをサポートしており、[gray-matter](https://github.com/jonschlinkert/gray-matter) で解析します。フロントマターは Markdown ファイルの先頭（`<script>` タグを含むあらゆる要素より前）に配置し、三本のハイフンで囲まれた **有効な YAML** 形式で記述します。例:
|
||||
|
||||
```md
|
||||
---
|
||||
title: Docs with VitePress
|
||||
editLink: true
|
||||
---
|
||||
```
|
||||
|
||||
サイトやデフォルトテーマの多くの設定オプションには、フロントマター上で対応するオプションがあります。フロントマターを使うことで、**そのページに限って** 特定の振る舞いを上書きできます。詳細は [Frontmatter Config Reference](../reference/frontmatter-config) を参照してください。
|
||||
|
||||
また、独自のカスタムフロントマターデータを定義し、ページ上の動的な Vue 式で利用することもできます。
|
||||
|
||||
## フロントマターデータへのアクセス {#accessing-frontmatter-data}
|
||||
|
||||
フロントマターデータは特別なグローバル変数 `$frontmatter` で参照できます。
|
||||
|
||||
Markdown ファイル内での使用例:
|
||||
|
||||
```md
|
||||
---
|
||||
title: Docs with VitePress
|
||||
editLink: true
|
||||
---
|
||||
|
||||
# {{ $frontmatter.title }}
|
||||
|
||||
Guide content
|
||||
```
|
||||
|
||||
[`useData()`](../reference/runtime-api#usedata) ヘルパーを使えば、`<script setup>` 内からも現在のページのフロントマターデータにアクセスできます。
|
||||
|
||||
## 代替フロントマター形式 {#alternative-frontmatter-formats}
|
||||
|
||||
VitePress は JSON フロントマター構文もサポートしています。中括弧で開始・終了する形式です。
|
||||
|
||||
```json
|
||||
---
|
||||
{
|
||||
"title": "Blogging Like a Hacker",
|
||||
"editLink": true
|
||||
}
|
||||
---
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,58 @@
|
||||
# サイトマップ生成 {#sitemap-generation}
|
||||
|
||||
VitePress には、サイト用の `sitemap.xml` を生成する機能が標準で用意されています。有効化するには、`.vitepress/config.js` に次を追加します。
|
||||
|
||||
```ts
|
||||
export default {
|
||||
sitemap: {
|
||||
hostname: 'https://example.com'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`siteamp.xml` に `<lastmod>` タグを含めるには、[`lastUpdated`](../reference/default-theme-last-updated) オプションを有効にします。
|
||||
|
||||
## オプション {#options}
|
||||
|
||||
サイトマップ生成は [`sitemap`](https://www.npmjs.com/package/sitemap) モジュールで行われます。設定ファイルの `sitemap` に、このモジュールがサポートする任意のオプションを渡せます。指定した値はそのまま `SitemapStream` コンストラクタに渡されます。詳しくは [`sitemap` のドキュメント](https://www.npmjs.com/package/sitemap#options-you-can-pass) を参照してください。例：
|
||||
|
||||
```ts
|
||||
export default {
|
||||
sitemap: {
|
||||
hostname: 'https://example.com',
|
||||
lastmodDateOnly: false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
設定で `base` を使っている場合は、`hostname` にもそれを付与してください：
|
||||
|
||||
```ts
|
||||
export default {
|
||||
base: '/my-site/',
|
||||
sitemap: {
|
||||
hostname: 'https://example.com/my-site/'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## `transformItems` フック {#transformitems-hook}
|
||||
|
||||
`siteamp.xml` に書き出す直前にサイトマップ項目を加工するには、`sitemap.transformItems` フックを使います。このフックはサイトマップ項目の配列を受け取り、配列を返す必要があります。例：
|
||||
|
||||
```ts
|
||||
export default {
|
||||
sitemap: {
|
||||
hostname: 'https://example.com',
|
||||
transformItems: (items) => {
|
||||
// 既存項目の追加・変更・フィルタリングが可能
|
||||
items.push({
|
||||
url: '/extra-page',
|
||||
changefreq: 'monthly',
|
||||
priority: 0.8
|
||||
})
|
||||
return items
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -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: <svg xmlns="http://www.w3.org/2000/svg" width="30" viewBox="0 0 256 256.32"><defs><linearGradient id="a" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"/><stop offset="100%" stop-color="#BD34FE"/></linearGradient><linearGradient id="b" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"/><stop offset="8.333%" stop-color="#FFDD35"/><stop offset="100%" stop-color="#FFA800"/></linearGradient></defs><path fill="url(#a)" d="M255.153 37.938 134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"/><path fill="url(#b)" d="M185.432.063 96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028 72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"/></svg>
|
||||
title: Vite の開発体験を享受
|
||||
details: 即時サーバー起動、超高速ホットリロード、そして Vite エコシステムのプラグイン活用。
|
||||
- icon: <svg xmlns="http://www.w3.org/2000/svg" width="30" viewBox="0 0 256 220.8"><path fill="#41B883" d="M204.8 0H256L128 220.8 0 0h97.92L128 51.2 157.44 0h47.36Z"/><path fill="#41B883" d="m0 0 128 220.8L256 0h-51.2L128 132.48 50.56 0H0Z"/><path fill="#35495E" d="M50.56 0 128 133.12 204.8 0h-47.36L128 51.2 97.92 0H50.56Z"/></svg>
|
||||
title: Vue でカスタマイズ
|
||||
details: Markdown 内で直接 Vue 構文やコンポーネントを利用したり、Vue で独自テーマを構築できます。
|
||||
- icon: 🚀
|
||||
title: 高速サイトを公開
|
||||
details: 静的 HTML による高速初期ロードと、クライアントサイドルーティングによる快適なページ遷移。
|
||||
---
|
||||
@ -0,0 +1,69 @@
|
||||
# バッジ {#badge}
|
||||
|
||||
バッジを使うと、見出しにステータスを追加できます。たとえば、そのセクションの種類や対応バージョンを示すのに便利です。
|
||||
|
||||
## 使い方 {#usage}
|
||||
|
||||
グローバルに利用可能な `Badge` コンポーネントを使用します。
|
||||
|
||||
```html
|
||||
### Title <Badge type="info" text="default" />
|
||||
### Title <Badge type="tip" text="^1.9.0" />
|
||||
### Title <Badge type="warning" text="beta" />
|
||||
### Title <Badge type="danger" text="caution" />
|
||||
```
|
||||
|
||||
上記のコードは次のように表示されます：
|
||||
|
||||
### Title <Badge type="info" text="default" />
|
||||
### Title <Badge type="tip" text="^1.9.0" />
|
||||
### Title <Badge type="warning" text="beta" />
|
||||
### Title <Badge type="danger" text="caution" />
|
||||
|
||||
## 子要素のカスタマイズ {#custom-children}
|
||||
|
||||
`<Badge>` は子要素（`children`）を受け取り、バッジ内に表示できます。
|
||||
|
||||
```html
|
||||
### Title <Badge type="info">custom element</Badge>
|
||||
```
|
||||
|
||||
### Title <Badge type="info">custom element</Badge>
|
||||
|
||||
## 種類ごとの色をカスタマイズ {#customize-type-color}
|
||||
|
||||
CSS 変数を上書きすることで、バッジのスタイルをカスタマイズできます。以下はデフォルト値です：
|
||||
|
||||
```css
|
||||
:root {
|
||||
--vp-badge-info-border: transparent;
|
||||
--vp-badge-info-text: var(--vp-c-text-2);
|
||||
--vp-badge-info-bg: var(--vp-c-default-soft);
|
||||
|
||||
--vp-badge-tip-border: transparent;
|
||||
--vp-badge-tip-text: var(--vp-c-brand-1);
|
||||
--vp-badge-tip-bg: var(--vp-c-brand-soft);
|
||||
|
||||
--vp-badge-warning-border: transparent;
|
||||
--vp-badge-warning-text: var(--vp-c-warning-1);
|
||||
--vp-badge-warning-bg: var(--vp-c-warning-soft);
|
||||
|
||||
--vp-badge-danger-border: transparent;
|
||||
--vp-badge-danger-text: var(--vp-c-danger-1);
|
||||
--vp-badge-danger-bg: var(--vp-c-danger-soft);
|
||||
}
|
||||
```
|
||||
|
||||
## `<Badge>`
|
||||
|
||||
`<Badge>` コンポーネントは次の props を受け取ります。
|
||||
|
||||
```ts
|
||||
interface Props {
|
||||
// `<slot>` が渡された場合、この値は無視されます。
|
||||
text?: string
|
||||
|
||||
// 既定値は `tip`。
|
||||
type?: 'info' | 'tip' | 'warning' | 'danger'
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,22 @@
|
||||
# Carbon 広告 {#carbon-ads}
|
||||
|
||||
VitePress は [Carbon Ads](https://www.carbonads.net/) をネイティブにサポートしています。設定で Carbon Ads の認証情報を定義すると、ページ上に広告が表示されます。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
carbonAds: {
|
||||
code: 'your-carbon-code',
|
||||
placement: 'your-carbon-placement'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
これらの値は、次のように Carbon の CDN スクリプトを呼び出すために使用されます。
|
||||
|
||||
```js
|
||||
`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}`
|
||||
```
|
||||
|
||||
Carbon Ads の設定について詳しくは、[Carbon Ads のウェブサイト](https://www.carbonads.net/)を参照してください。
|
||||
@ -0,0 +1,60 @@
|
||||
# 編集リンク {#edit-link}
|
||||
|
||||
## サイトレベルの設定 {#site-level-config}
|
||||
|
||||
編集リンクは、GitHub や GitLab などの Git 管理サービスでそのページを編集できるリンクを表示します。有効化するには、設定に `themeConfig.editLink` オプションを追加します。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
editLink: {
|
||||
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`pattern` オプションはリンクの URL 構造を定義します。`:path` はページパスに置き換えられます。
|
||||
|
||||
また、引数に [`PageData`](./runtime-api#usedata) を受け取り、URL 文字列を返す純粋関数を指定することもできます。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
editLink: {
|
||||
pattern: ({ filePath }) => {
|
||||
if (filePath.startsWith('packages/')) {
|
||||
return `https://github.com/acme/monorepo/edit/main/${filePath}`
|
||||
} else {
|
||||
return `https://github.com/acme/monorepo/edit/main/docs/${filePath}`
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
この関数はブラウザでシリアライズされ実行されるため、副作用を持たず、スコープ外のものへアクセスしないでください。
|
||||
|
||||
既定では、ドキュメント下部に「Edit this page」というリンクテキストが表示されます。`text` オプションでこの文言をカスタマイズできます。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
editLink: {
|
||||
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
|
||||
text: 'GitHub でこのページを編集'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## フロントマターでの設定 {#frontmatter-config}
|
||||
|
||||
ページごとに無効化するには、フロントマターで `editLink` オプションを使用します。
|
||||
|
||||
```yaml
|
||||
---
|
||||
editLink: false
|
||||
---
|
||||
```
|
||||
@ -0,0 +1,55 @@
|
||||
# フッター {#footer}
|
||||
|
||||
`themeConfig.footer` を設定すると、ページ下部にグローバルフッターが表示されます。
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
footer: {
|
||||
message: 'Released under the MIT License.',
|
||||
copyright: 'Copyright © 2019-present Evan You'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface Footer {
|
||||
// 著作権表示の直前に表示されるメッセージ
|
||||
message?: string
|
||||
|
||||
// 実際の著作権表記
|
||||
copyright?: string
|
||||
}
|
||||
```
|
||||
|
||||
上記の設定は HTML 文字列にも対応しています。たとえば、フッター内のテキストにリンクを含めたい場合は、次のように設定できます。
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
footer: {
|
||||
message: 'Released under the <a href="https://github.com/vuejs/vitepress/blob/main/LICENSE">MIT License</a>.',
|
||||
copyright: 'Copyright © 2019-present <a href="https://github.com/yyx990803">Evan You</a>'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: warning
|
||||
`message` と `copyright` は `<p>` 要素内にレンダリングされるため、
|
||||
使用できるのはインライン要素のみです。ブロック要素を追加したい場合は、
|
||||
[`layout-bottom`](../guide/extending-default-theme#layout-slots) スロットの利用を検討してください。
|
||||
:::
|
||||
|
||||
なお、[SideBar](./default-theme-sidebar) が表示されている場合はフッターは表示されません。
|
||||
|
||||
## フロントマターでの設定 {#frontmatter-config}
|
||||
|
||||
ページ単位で無効化するには、フロントマターの `footer` オプションを使用します。
|
||||
|
||||
```yaml
|
||||
---
|
||||
footer: false
|
||||
---
|
||||
```
|
||||
@ -0,0 +1,43 @@
|
||||
# 前／次リンク {#prev-next-links}
|
||||
|
||||
ドキュメントのフッターに表示される「前のページ」「次のページ」のテキストとリンクをカスタマイズできます。サイドバーに表示しているタイトルとは別の文言を使いたい場合や、フッターを無効化したり、サイドバーに含まれていないページへリンクしたい場合に便利です。
|
||||
|
||||
## prev
|
||||
|
||||
- 型: `string | false | { text?: string; link?: string }`
|
||||
|
||||
- 詳細:
|
||||
|
||||
前のページへのリンクに表示するテキスト／リンクを指定します。フロントマターで設定しない場合は、サイドバー設定から自動推測されます。
|
||||
|
||||
- 例:
|
||||
|
||||
- テキストだけをカスタマイズ:
|
||||
|
||||
```yaml
|
||||
---
|
||||
prev: 'Get Started | Markdown'
|
||||
---
|
||||
```
|
||||
|
||||
- テキストとリンクの両方をカスタマイズ:
|
||||
|
||||
```yaml
|
||||
---
|
||||
prev:
|
||||
text: 'Markdown'
|
||||
link: '/guide/markdown'
|
||||
---
|
||||
```
|
||||
|
||||
- 前のページを非表示にする:
|
||||
|
||||
```yaml
|
||||
---
|
||||
prev: false
|
||||
---
|
||||
```
|
||||
|
||||
## next
|
||||
|
||||
`prev` と同様ですが、次のページ用の設定です。
|
||||
@ -0,0 +1,451 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# 検索 {#search}
|
||||
|
||||
## ローカル検索 {#local-search}
|
||||
|
||||
VitePress は、[minisearch](https://github.com/lucaong/minisearch/) によるブラウザ内インデックスを使った曖昧一致の全文検索をサポートします。有効化するには、`.vitepress/config.ts` で `themeConfig.search.provider` を `'local'` に設定します。
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local'
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
表示例:
|
||||
|
||||
|
||||
|
||||
代わりに [Algolia DocSearch](#algolia-search) や、次のコミュニティ製プラグインを使うこともできます。
|
||||
|
||||
- <https://www.npmjs.com/package/vitepress-plugin-search>
|
||||
- <https://www.npmjs.com/package/vitepress-plugin-pagefind>
|
||||
- <https://www.npmjs.com/package/@orama/plugin-vitepress>
|
||||
|
||||
### i18n {#local-search-i18n}
|
||||
|
||||
多言語検索を行う設定例です。
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
locales: {
|
||||
zh: { // 既定ロケールの文言も翻訳したい場合はこれを `root` に
|
||||
translations: {
|
||||
button: {
|
||||
buttonText: '搜索',
|
||||
buttonAriaLabel: '搜索'
|
||||
},
|
||||
modal: {
|
||||
displayDetails: '显示详细列表',
|
||||
resetButtonTitle: '重置搜索',
|
||||
backButtonTitle: '关闭搜索',
|
||||
noResultsText: '没有结果',
|
||||
footer: {
|
||||
selectText: '选择',
|
||||
selectKeyAriaLabel: '输入',
|
||||
navigateText: '导航',
|
||||
navigateUpKeyAriaLabel: '上箭头',
|
||||
navigateDownKeyAriaLabel: '下箭头',
|
||||
closeText: '关闭',
|
||||
closeKeyAriaLabel: 'esc'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### miniSearch のオプション {#mini-search-options}
|
||||
|
||||
MiniSearch の設定例です。
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
miniSearch: {
|
||||
/**
|
||||
* @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
|
||||
*/
|
||||
options: {
|
||||
/* ... */
|
||||
},
|
||||
/**
|
||||
* @type {import('minisearch').SearchOptions}
|
||||
* @default
|
||||
* { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
|
||||
*/
|
||||
searchOptions: {
|
||||
/* ... */
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
詳しくは [MiniSearch のドキュメント](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html) を参照してください。
|
||||
|
||||
### コンテンツレンダラーのカスタマイズ {#custom-content-renderer}
|
||||
|
||||
インデックス前に Markdown コンテンツをレンダリングする関数をカスタマイズできます。
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
/**
|
||||
* @param {string} src
|
||||
* @param {import('vitepress').MarkdownEnv} env
|
||||
* @param {import('markdown-it-async')} md
|
||||
*/
|
||||
async _render(src, env, md) {
|
||||
// HTML 文字列を返す
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
この関数はクライアント側のサイトデータからは除外されるため、Node.js の API を使用できます。
|
||||
|
||||
#### 例: 検索対象からページを除外する {#example-excluding-pages-from-search}
|
||||
|
||||
フロントマターに `search: false` を追加すると、そのページを検索対象から除外できます。あるいは次のようにもできます。
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
async _render(src, env, md) {
|
||||
const html = await md.renderAsync(src, env)
|
||||
if (env.frontmatter?.search === false) return ''
|
||||
if (env.relativePath.startsWith('some/path')) return ''
|
||||
return html
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::: warning 注意
|
||||
カスタムの `_render` 関数を提供する場合、`search: false` の処理は自分で行う必要があります。また、`env` は `md.renderAsync` の呼び出し前には完全ではないため、`frontmatter` などの任意プロパティのチェックはその後に行ってください。
|
||||
:::
|
||||
|
||||
#### 例: コンテンツの変換 — 見出しアンカーを追加 {#example-transforming-content-adding-anchors}
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
async _render(src, env, md) {
|
||||
const html = await md.renderAsync(src, env)
|
||||
if (env.frontmatter?.title)
|
||||
return await md.renderAsync(`# ${env.frontmatter.title}`) + html
|
||||
return html
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Algolia 検索 {#algolia-search}
|
||||
|
||||
VitePress は [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch) によるサイト検索をサポートします。導入は公式のガイドを参照してください。`.vitepress/config.ts` では最低限次の設定が必要です。
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'algolia',
|
||||
options: {
|
||||
appId: '...',
|
||||
apiKey: '...',
|
||||
indexName: '...'
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### i18n {#algolia-search-i18n}
|
||||
|
||||
多言語検索の設定例です。
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'algolia',
|
||||
options: {
|
||||
appId: '...',
|
||||
apiKey: '...',
|
||||
indexName: '...',
|
||||
locales: {
|
||||
zh: {
|
||||
placeholder: '搜索文档',
|
||||
translations: {
|
||||
button: {
|
||||
buttonText: '搜索文档',
|
||||
buttonAriaLabel: '搜索文档'
|
||||
},
|
||||
modal: {
|
||||
searchBox: {
|
||||
clearButtonTitle: '清除查询条件',
|
||||
clearButtonAriaLabel: '清除查询条件',
|
||||
closeButtonText: '关闭',
|
||||
closeButtonAriaLabel: '关闭',
|
||||
placeholderText: '搜索文档',
|
||||
placeholderTextAskAi: '向 AI 提问：',
|
||||
placeholderTextAskAiStreaming: '回答中...',
|
||||
searchInputLabel: '搜索',
|
||||
backToKeywordSearchButtonText: '返回关键字搜索',
|
||||
backToKeywordSearchButtonAriaLabel: '返回关键字搜索'
|
||||
},
|
||||
startScreen: {
|
||||
recentSearchesTitle: '搜索历史',
|
||||
noRecentSearchesText: '没有搜索历史',
|
||||
saveRecentSearchButtonTitle: '保存至搜索历史',
|
||||
removeRecentSearchButtonTitle: '从搜索历史中移除',
|
||||
favoriteSearchesTitle: '收藏',
|
||||
removeFavoriteSearchButtonTitle: '从收藏中移除',
|
||||
recentConversationsTitle: '最近的对话',
|
||||
removeRecentConversationButtonTitle: '从历史记录中删除对话'
|
||||
},
|
||||
errorScreen: {
|
||||
titleText: '无法获取结果',
|
||||
helpText: '你可能需要检查你的网络连接'
|
||||
},
|
||||
noResultsScreen: {
|
||||
noResultsText: '无法找到相关结果',
|
||||
suggestedQueryText: '你可以尝试查询',
|
||||
reportMissingResultsText: '你认为该查询应该有结果？',
|
||||
reportMissingResultsLinkText: '点击反馈'
|
||||
},
|
||||
resultsScreen: {
|
||||
askAiPlaceholder: '向 AI 提问： '
|
||||
},
|
||||
askAiScreen: {
|
||||
disclaimerText: '答案由 AI 生成，可能不准确，请自行验证。',
|
||||
relatedSourcesText: '相关来源',
|
||||
thinkingText: '思考中...',
|
||||
copyButtonText: '复制',
|
||||
copyButtonCopiedText: '已复制！',
|
||||
copyButtonTitle: '复制',
|
||||
likeButtonTitle: '赞',
|
||||
dislikeButtonTitle: '踩',
|
||||
thanksForFeedbackText: '感谢你的反馈！',
|
||||
preToolCallText: '搜索中...',
|
||||
duringToolCallText: '搜索 ',
|
||||
afterToolCallText: '已搜索'
|
||||
},
|
||||
footer: {
|
||||
selectText: '选择',
|
||||
submitQuestionText: '提交问题',
|
||||
selectKeyAriaLabel: 'Enter 键',
|
||||
navigateText: '切换',
|
||||
navigateUpKeyAriaLabel: '向上箭头',
|
||||
navigateDownKeyAriaLabel: '向下箭头',
|
||||
closeText: '关闭',
|
||||
backToSearchText: '返回搜索',
|
||||
closeKeyAriaLabel: 'Esc 键',
|
||||
poweredByText: '搜索提供者'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
[これらのオプション](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) は上書きできます。詳細は Algolia の公式ドキュメントを参照してください。
|
||||
|
||||
### Algolia Ask AI のサポート {#ask-ai}
|
||||
|
||||
**Ask AI** を有効にするには、`options` 内に `askAi` オプション（またはその一部）を指定します。
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'algolia',
|
||||
options: {
|
||||
appId: '...',
|
||||
apiKey: '...',
|
||||
indexName: '...',
|
||||
// askAi: "YOUR-ASSISTANT-ID"
|
||||
// または
|
||||
askAi: {
|
||||
// 少なくとも Algolia から受け取った assistantId を指定
|
||||
assistantId: 'XXXYYY',
|
||||
// 任意の上書き — 省略時は上位の appId/apiKey/indexName を再利用
|
||||
// apiKey: '...',
|
||||
// appId: '...',
|
||||
// indexName: '...'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::: warning 注意
|
||||
キーワード検索を既定にして Ask AI を使わない場合は、`askAi` を指定しないでください。
|
||||
:::
|
||||
|
||||
Ask AI UI の翻訳は `options.translations.modal.askAiScreen` と `options.translations.resultsScreen` にあります。すべてのキーは[型定義](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts)を参照してください。
|
||||
|
||||
### クローラー設定 {#crawler-config}
|
||||
|
||||
このサイトで使用している設定を元にした例です。
|
||||
|
||||
```ts
|
||||
new Crawler({
|
||||
appId: '...',
|
||||
apiKey: '...',
|
||||
rateLimit: 8,
|
||||
startUrls: ['https://vitepress.dev/'],
|
||||
renderJavaScript: false,
|
||||
sitemaps: [],
|
||||
exclusionPatterns: [],
|
||||
ignoreCanonicalTo: false,
|
||||
discoveryPatterns: ['https://vitepress.dev/**'],
|
||||
schedule: 'at 05:10 on Saturday',
|
||||
actions: [
|
||||
{
|
||||
indexName: 'vitepress',
|
||||
pathsToMatch: ['https://vitepress.dev/**'],
|
||||
recordExtractor: ({ $, helpers }) => {
|
||||
return helpers.docsearch({
|
||||
recordProps: {
|
||||
lvl1: '.content h1',
|
||||
content: '.content p, .content li',
|
||||
lvl0: {
|
||||
selectors: 'section.has-active div h2',
|
||||
defaultValue: 'Documentation'
|
||||
},
|
||||
lvl2: '.content h2',
|
||||
lvl3: '.content h3',
|
||||
lvl4: '.content h4',
|
||||
lvl5: '.content h5'
|
||||
},
|
||||
indexHeadings: true
|
||||
})
|
||||
}
|
||||
}
|
||||
],
|
||||
initialIndexSettings: {
|
||||
vitepress: {
|
||||
attributesForFaceting: ['type', 'lang'],
|
||||
attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
|
||||
attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'],
|
||||
attributesToSnippet: ['content:10'],
|
||||
camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'],
|
||||
searchableAttributes: [
|
||||
'unordered(hierarchy_radio_camel.lvl0)',
|
||||
'unordered(hierarchy_radio.lvl0)',
|
||||
'unordered(hierarchy_radio_camel.lvl1)',
|
||||
'unordered(hierarchy_radio.lvl1)',
|
||||
'unordered(hierarchy_radio_camel.lvl2)',
|
||||
'unordered(hierarchy_radio.lvl2)',
|
||||
'unordered(hierarchy_radio_camel.lvl3)',
|
||||
'unordered(hierarchy_radio.lvl3)',
|
||||
'unordered(hierarchy_radio_camel.lvl4)',
|
||||
'unordered(hierarchy_radio.lvl4)',
|
||||
'unordered(hierarchy_radio_camel.lvl5)',
|
||||
'unordered(hierarchy_radio.lvl5)',
|
||||
'unordered(hierarchy_radio_camel.lvl6)',
|
||||
'unordered(hierarchy_radio.lvl6)',
|
||||
'unordered(hierarchy_camel.lvl0)',
|
||||
'unordered(hierarchy.lvl0)',
|
||||
'unordered(hierarchy_camel.lvl1)',
|
||||
'unordered(hierarchy.lvl1)',
|
||||
'unordered(hierarchy_camel.lvl2)',
|
||||
'unordered(hierarchy.lvl2)',
|
||||
'unordered(hierarchy_camel.lvl3)',
|
||||
'unordered(hierarchy.lvl3)',
|
||||
'unordered(hierarchy_camel.lvl4)',
|
||||
'unordered(hierarchy.lvl4)',
|
||||
'unordered(hierarchy_camel.lvl5)',
|
||||
'unordered(hierarchy.lvl5)',
|
||||
'unordered(hierarchy_camel.lvl6)',
|
||||
'unordered(hierarchy.lvl6)',
|
||||
'content'
|
||||
],
|
||||
distinct: true,
|
||||
attributeForDistinct: 'url',
|
||||
customRanking: [
|
||||
'desc(weight.pageRank)',
|
||||
'desc(weight.level)',
|
||||
'asc(weight.position)'
|
||||
],
|
||||
ranking: [
|
||||
'words',
|
||||
'filters',
|
||||
'typo',
|
||||
'attribute',
|
||||
'proximity',
|
||||
'exact',
|
||||
'custom'
|
||||
],
|
||||
highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">',
|
||||
highlightPostTag: '</span>',
|
||||
minWordSizefor1Typo: 3,
|
||||
minWordSizefor2Typos: 7,
|
||||
allowTyposOnNumericTokens: false,
|
||||
minProximity: 1,
|
||||
ignorePlurals: true,
|
||||
advancedSyntax: true,
|
||||
attributeCriteriaComputedByMinProximity: true,
|
||||
removeWordsIfNoResults: 'allOptional'
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
@ -0,0 +1,180 @@
|
||||
# サイドバー {#sidebar}
|
||||
|
||||
サイドバーはドキュメントの主要なナビゲーションブロックです。[`themeConfig.sidebar`](./default-theme-config#sidebar) でメニューを設定できます。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Guide',
|
||||
items: [
|
||||
{ text: 'Introduction', link: '/introduction' },
|
||||
{ text: 'Getting Started', link: '/getting-started' },
|
||||
...
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 基本 {#the-basics}
|
||||
|
||||
最もシンプルな構成は、リンクの配列を 1 つ渡す方法です。第 1 階層のアイテムがサイドバーの「セクション」を表します。各セクションは `text`（セクションのタイトル）と、実際のナビゲーションリンクである `items` を持ちます。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Section Title A',
|
||||
items: [
|
||||
{ text: 'Item A', link: '/item-a' },
|
||||
{ text: 'Item B', link: '/item-b' },
|
||||
...
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Section Title B',
|
||||
items: [
|
||||
{ text: 'Item C', link: '/item-c' },
|
||||
{ text: 'Item D', link: '/item-d' },
|
||||
...
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
各 `link` は `/` で始まる実ファイルへのパスを指定します。リンクの末尾を `/` で終わらせると、対応するディレクトリの `index.md` が表示されます。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Guide',
|
||||
items: [
|
||||
// `/guide/index.md` を表示
|
||||
{ text: 'Introduction', link: '/guide/' }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
サイドバーのアイテムは、ルートから数えて最大 6 階層まで入れ子にできます。7 階層以上は無視され、表示されません。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Level 1',
|
||||
items: [
|
||||
{
|
||||
text: 'Level 2',
|
||||
items: [
|
||||
{
|
||||
text: 'Level 3',
|
||||
items: [
|
||||
...
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 複数のサイドバー {#multiple-sidebars}
|
||||
|
||||
ページのパスに応じて異なるサイドバーを表示できます。たとえば、このサイトのように「Guide」セクションと「Config」セクションでナビゲーションを分けたい場合に便利です。
|
||||
|
||||
まず、対象のセクションごとにディレクトリを分けてページを配置します。
|
||||
|
||||
```
|
||||
.
|
||||
├─ guide/
|
||||
│ ├─ index.md
|
||||
│ ├─ one.md
|
||||
│ └─ two.md
|
||||
└─ config/
|
||||
├─ index.md
|
||||
├─ three.md
|
||||
└─ four.md
|
||||
```
|
||||
|
||||
次に、各セクション用のサイドバーを設定します。この場合、配列ではなくオブジェクトを渡します。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: {
|
||||
// ユーザーが `guide` ディレクトリ配下にいるときに表示
|
||||
'/guide/': [
|
||||
{
|
||||
text: 'Guide',
|
||||
items: [
|
||||
{ text: 'Index', link: '/guide/' },
|
||||
{ text: 'One', link: '/guide/one' },
|
||||
{ text: 'Two', link: '/guide/two' }
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
// ユーザーが `config` ディレクトリ配下にいるときに表示
|
||||
'/config/': [
|
||||
{
|
||||
text: 'Config',
|
||||
items: [
|
||||
{ text: 'Index', link: '/config/' },
|
||||
{ text: 'Three', link: '/config/three' },
|
||||
{ text: 'Four', link: '/config/four' }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 折りたたみ可能なサイドバーグループ {#collapsible-sidebar-groups}
|
||||
|
||||
サイドバーグループに `collapsed` オプションを追加すると、各セクションの開閉トグルが表示されます。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Section Title A',
|
||||
collapsed: false,
|
||||
items: [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
既定ではすべてのセクションが「開いた」状態です。初回表示時に「閉じた」状態にしたい場合は、`collapsed` を `true` に設定します。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Section Title A',
|
||||
collapsed: true,
|
||||
items: [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,255 @@
|
||||
<script setup>
|
||||
import { VPTeamMembers } from 'vitepress/theme'
|
||||
|
||||
const members = [
|
||||
{
|
||||
avatar: 'https://github.com/yyx990803.png',
|
||||
name: 'Evan You',
|
||||
title: 'Creator',
|
||||
links: [
|
||||
{ icon: 'github', link: 'https://github.com/yyx990803' },
|
||||
{ icon: 'twitter', link: 'https://twitter.com/youyuxi' }
|
||||
]
|
||||
},
|
||||
{
|
||||
avatar: 'https://github.com/kiaking.png',
|
||||
name: 'Kia King Ishii',
|
||||
title: 'Developer',
|
||||
links: [
|
||||
{ icon: 'github', link: 'https://github.com/kiaking' },
|
||||
{ icon: 'twitter', link: 'https://twitter.com/KiaKing85' }
|
||||
]
|
||||
}
|
||||
]
|
||||
</script>
|
||||
|
||||
# チームページ {#team-page}
|
||||
|
||||
チームを紹介したい場合は、Team コンポーネント群を使ってチームページを構成できます。使い方は 2 通りあり、ドキュメントページに埋め込む方法と、専用のチームページを作成する方法があります。
|
||||
|
||||
## ページ内にメンバー一覧を表示する {#show-team-members-in-a-page}
|
||||
|
||||
任意のページでチームメンバーの一覧を表示するには、`vitepress/theme` からエクスポートされている `<VPTeamMembers>` コンポーネントを使用します。
|
||||
|
||||
```html
|
||||
<script setup>
|
||||
import { VPTeamMembers } from 'vitepress/theme'
|
||||
|
||||
const members = [
|
||||
{
|
||||
avatar: 'https://www.github.com/yyx990803.png',
|
||||
name: 'Evan You',
|
||||
title: 'Creator',
|
||||
links: [
|
||||
{ icon: 'github', link: 'https://github.com/yyx990803' },
|
||||
{ icon: 'twitter', link: 'https://twitter.com/youyuxi' }
|
||||
]
|
||||
},
|
||||
...
|
||||
]
|
||||
</script>
|
||||
|
||||
# 私たちのチーム
|
||||
|
||||
私たちの素晴らしいチームを紹介します。
|
||||
|
||||
<VPTeamMembers size="small" :members />
|
||||
```
|
||||
|
||||
上記のように、カード風の要素でメンバーが表示されます。下図のような見た目になります。
|
||||
|
||||
<VPTeamMembers size="small" :members />
|
||||
|
||||
`<VPTeamMembers>` コンポーネントには `small` と `medium` の 2 種類のサイズがあります。好みによりますが、ドキュメントページ内で使う場合は `small` が馴染みやすいことが多いでしょう。各メンバーに「説明文」や「スポンサー」ボタンなど、追加のプロパティを付けることもできます。詳細は [`<VPTeamMembers>`](#vpteammembers) を参照してください。
|
||||
|
||||
小規模なチームで専用ページまでは不要な場合や、文脈上の参考として一部のメンバーのみを紹介したい場合は、ドキュメントページへ埋め込む方法が適しています。
|
||||
|
||||
メンバーが多い場合や、より広いスペースで紹介したい場合は、[専用のチームページを作成する](#専用のチームページを作成する) ことを検討してください。
|
||||
|
||||
## 専用のチームページを作成する {#create-a-full-team-page}
|
||||
|
||||
ドキュメントページにメンバーを追加する代わりに、カスタムの [ホームページ](./default-theme-home-page) と同様、専用のチームページを作成することもできます。
|
||||
|
||||
まず新しい md ファイルを作成します。ファイル名は任意ですが、ここでは `team.md` とします。このファイルでフロントマターに `layout: page` を設定し、その後 `TeamPage` コンポーネント群を使ってページを構成します。
|
||||
|
||||
```html
|
||||
---
|
||||
layout: page
|
||||
---
|
||||
<script setup>
|
||||
import {
|
||||
VPTeamPage,
|
||||
VPTeamPageTitle,
|
||||
VPTeamMembers
|
||||
} from 'vitepress/theme'
|
||||
|
||||
const members = [
|
||||
{
|
||||
avatar: 'https://www.github.com/yyx990803.png',
|
||||
name: 'Evan You',
|
||||
title: 'Creator',
|
||||
links: [
|
||||
{ icon: 'github', link: 'https://github.com/yyx990803' },
|
||||
{ icon: 'twitter', link: 'https://twitter.com/youyuxi' }
|
||||
]
|
||||
},
|
||||
...
|
||||
]
|
||||
</script>
|
||||
|
||||
<VPTeamPage>
|
||||
<VPTeamPageTitle>
|
||||
<template #title>
|
||||
私たちのチーム
|
||||
</template>
|
||||
<template #lead>
|
||||
VitePress の開発は国際的なチームによって主導されています。
|
||||
その一部を以下に紹介します。
|
||||
</template>
|
||||
</VPTeamPageTitle>
|
||||
<VPTeamMembers :members />
|
||||
</VPTeamPage>
|
||||
```
|
||||
|
||||
専用のチームページを作る際は、必ずすべてのチーム関連コンポーネントを `<VPTeamPage>` でラップしてください。レイアウトや余白などが適切に適用されます。
|
||||
|
||||
`<VPPageTitle>` はページタイトルのセクションを追加します。タイトルは `<h1>` 見出しになります。`#title` と `#lead` スロットでチームについて説明を書きましょう。
|
||||
|
||||
`<VPMembers>` はドキュメントページで使う場合と同様に、メンバー一覧を表示します。
|
||||
|
||||
### セクションを追加してメンバーを分ける {#add-sections-to-divide-team-members}
|
||||
|
||||
チームページに「セクション」を追加できます。たとえば、コアメンバーとコミュニティパートナーなど、役割ごとにメンバーを分けて説明しやすくできます。
|
||||
|
||||
そのためには、先ほど作成した `team.md` に `<VPTeamPageSection>` コンポーネントを追加します。
|
||||
|
||||
```html
|
||||
---
|
||||
layout: page
|
||||
---
|
||||
<script setup>
|
||||
import {
|
||||
VPTeamPage,
|
||||
VPTeamPageTitle,
|
||||
VPTeamMembers,
|
||||
VPTeamPageSection
|
||||
} from 'vitepress/theme'
|
||||
|
||||
const coreMembers = [...]
|
||||
const partners = [...]
|
||||
</script>
|
||||
|
||||
<VPTeamPage>
|
||||
<VPTeamPageTitle>
|
||||
<template #title>私たちのチーム</template>
|
||||
<template #lead>...</template>
|
||||
</VPTeamPageTitle>
|
||||
<VPTeamMembers size="medium" :members="coreMembers" />
|
||||
<VPTeamPageSection>
|
||||
<template #title>パートナー</template>
|
||||
<template #lead>...</template>
|
||||
<template #members>
|
||||
<VPTeamMembers size="small" :members="partners" />
|
||||
</template>
|
||||
</VPTeamPageSection>
|
||||
</VPTeamPage>
|
||||
```
|
||||
|
||||
`<VPTeamPageSection>` は `VPTeamPageTitle` と同様に `#title` と `#lead` のスロットを持ち、さらにメンバー表示用の `#members` スロットを備えます。
|
||||
|
||||
`#members` スロット内に `<VPTeamMembers>` を配置するのを忘れないでください。
|
||||
|
||||
## `<VPTeamMembers>`
|
||||
|
||||
`<VPTeamMembers>` コンポーネントは、与えられたメンバー配列を表示します。
|
||||
|
||||
```html
|
||||
<VPTeamMembers
|
||||
size="medium"
|
||||
:members="[
|
||||
{ avatar: '...', name: '...' },
|
||||
{ avatar: '...', name: '...' },
|
||||
...
|
||||
]"
|
||||
/>
|
||||
```
|
||||
|
||||
```ts
|
||||
interface Props {
|
||||
// 各メンバーカードのサイズ。既定は `medium`。
|
||||
size?: 'small' | 'medium'
|
||||
|
||||
// 表示するメンバー一覧。
|
||||
members: TeamMember[]
|
||||
}
|
||||
|
||||
interface TeamMember {
|
||||
// メンバーのアバター画像
|
||||
avatar: string
|
||||
|
||||
// メンバー名
|
||||
name: string
|
||||
|
||||
// 名前の下に表示する肩書き（例: Developer, Software Engineer など）
|
||||
title?: string
|
||||
|
||||
// 所属組織名
|
||||
org?: string
|
||||
|
||||
// 所属組織への URL
|
||||
orgLink?: string
|
||||
|
||||
// メンバーの説明
|
||||
desc?: string
|
||||
|
||||
// ソーシャルリンク（例: GitHub, Twitter など）
|
||||
// Social Links オブジェクトを渡せます。
|
||||
// 参照: https://vitepress.dev/reference/default-theme-config.html#sociallinks
|
||||
links?: SocialLink[]
|
||||
|
||||
// メンバーのスポンサー用 URL
|
||||
sponsor?: string
|
||||
|
||||
// スポンサーボタンのテキスト。既定は 'Sponsor'
|
||||
actionText?: string
|
||||
}
|
||||
```
|
||||
|
||||
## `<VPTeamPage>`
|
||||
|
||||
専用のチームページを作成する際のルートコンポーネントです。単一のスロットのみを受け取り、渡されたチーム関連コンポーネント全体に適切なスタイルを適用します。
|
||||
|
||||
## `<VPTeamPageTitle>`
|
||||
|
||||
ページの「タイトル」セクションを追加します。`<VPTeamPage>` の直下に置くのが最適です。`#title` と `#lead` のスロットを受け取ります。
|
||||
|
||||
```html
|
||||
<VPTeamPage>
|
||||
<VPTeamPageTitle>
|
||||
<template #title>
|
||||
私たちのチーム
|
||||
</template>
|
||||
<template #lead>
|
||||
VitePress の開発は国際的なチームによって主導されています。
|
||||
その一部を以下に紹介します。
|
||||
</template>
|
||||
</VPTeamPageTitle>
|
||||
</VPTeamPage>
|
||||
```
|
||||
|
||||
## `<VPTeamPageSection>`
|
||||
|
||||
チームページ内に「セクション」を作成します。`#title`、`#lead`、`#members` の各スロットを受け取ります。`<VPTeamPage>` の中に必要な数だけ追加できます。
|
||||
|
||||
```html
|
||||
<VPTeamPage>
|
||||
...
|
||||
<VPTeamPageSection>
|
||||
<template #title>パートナー</template>
|
||||
<template #lead>Lorem ipsum...</template>
|
||||
<template #members>
|
||||
<VPTeamMembers :members="data" />
|
||||
</template>
|
||||
</VPTeamPageSection>
|
||||
</VPTeamPage>
|
||||
```
|
||||
@ -0,0 +1,240 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# フロントマター設定 {#frontmatter-config}
|
||||
|
||||
フロントマターはページ単位の設定を可能にします。各 Markdown ファイルで、サイト全体やテーマレベルの設定を上書きできます。フロントマターでしか定義できない項目もあります。
|
||||
|
||||
使用例:
|
||||
|
||||
```md
|
||||
---
|
||||
title: Docs with VitePress
|
||||
editLink: true
|
||||
---
|
||||
```
|
||||
|
||||
Vue の式内では、グローバル `$frontmatter` を介してフロントマターデータにアクセスできます。
|
||||
|
||||
```md
|
||||
{{ $frontmatter.title }}
|
||||
```
|
||||
|
||||
## title
|
||||
|
||||
- 型: `string`
|
||||
|
||||
ページのタイトルです。[config.title](./site-config#title) と同じ意味で、サイトレベルの設定を上書きします。
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: VitePress
|
||||
---
|
||||
```
|
||||
|
||||
## titleTemplate
|
||||
|
||||
- 型: `string | boolean`
|
||||
|
||||
タイトルのサフィックスです。[config.titleTemplate](./site-config#titletemplate) と同じ意味で、サイトレベルの設定を上書きします。
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: VitePress
|
||||
titleTemplate: Vite & Vue powered static site generator
|
||||
---
|
||||
```
|
||||
|
||||
## description
|
||||
|
||||
- 型: `string`
|
||||
|
||||
ページの説明です。[config.description](./site-config#description) と同じ意味で、サイトレベルの設定を上書きします。
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: VitePress
|
||||
---
|
||||
```
|
||||
|
||||
## head
|
||||
|
||||
- 型: `HeadConfig[]`
|
||||
|
||||
現在のページに追加で挿入する `<head>` タグを指定します。サイトレベル設定で挿入されたタグの後に追加されます。
|
||||
|
||||
```yaml
|
||||
---
|
||||
head:
|
||||
- - meta
|
||||
- name: description
|
||||
content: hello
|
||||
- - meta
|
||||
- name: keywords
|
||||
content: super duper SEO
|
||||
---
|
||||
```
|
||||
|
||||
```ts
|
||||
type HeadConfig =
|
||||
| [string, Record<string, string>]
|
||||
| [string, Record<string, string>, string]
|
||||
```
|
||||
|
||||
## デフォルトテーマ専用 {#default-theme-only}
|
||||
|
||||
以下のフロントマター項目は、デフォルトテーマ使用時にのみ適用されます。
|
||||
|
||||
### layout
|
||||
|
||||
- 型: `doc | home | page`
|
||||
- 既定値: `doc`
|
||||
|
||||
ページのレイアウトを決めます。
|
||||
|
||||
- `doc` — Markdown コンテンツにドキュメント向けの既定スタイルを適用します。
|
||||
- `home` — 「ホームページ」用の特別なレイアウト。`hero` や `features` を追加指定して、ランディングページを素早く構築できます。
|
||||
- `page` — `doc` と似ていますが、コンテンツにスタイルを適用しません。完全にカスタムなページを作りたい場合に便利です。
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: doc
|
||||
---
|
||||
```
|
||||
|
||||
### hero <Badge type="info" text="home ページ専用" />
|
||||
|
||||
`layout: home` のときのヒーローセクションの内容を定義します。詳しくは [デフォルトテーマ: ホームページ](./default-theme-home-page) を参照。
|
||||
|
||||
### features <Badge type="info" text="home ページ専用" />
|
||||
|
||||
`layout: home` のときのフィーチャーセクションに表示する項目を定義します。詳しくは [デフォルトテーマ: ホームページ](./default-theme-home-page) を参照。
|
||||
|
||||
### navbar
|
||||
|
||||
- 型: `boolean`
|
||||
- 既定値: `true`
|
||||
|
||||
[ナビゲーションバー](./default-theme-nav) を表示するかどうか。
|
||||
|
||||
```yaml
|
||||
---
|
||||
navbar: false
|
||||
---
|
||||
```
|
||||
|
||||
### sidebar
|
||||
|
||||
- 型: `boolean`
|
||||
- 既定値: `true`
|
||||
|
||||
[サイドバー](./default-theme-sidebar) を表示するかどうか。
|
||||
|
||||
```yaml
|
||||
---
|
||||
sidebar: false
|
||||
---
|
||||
```
|
||||
|
||||
### aside
|
||||
|
||||
- 型: `boolean | 'left'`
|
||||
- 既定値: `true`
|
||||
|
||||
`doc` レイアウトでの aside コンポーネントの位置を定義します。
|
||||
|
||||
この値を `false` にすると aside コンテナを表示しません。\
|
||||
`true` にすると右側に表示します。\
|
||||
`'left'` にすると左側に表示します。
|
||||
|
||||
```yaml
|
||||
---
|
||||
aside: false
|
||||
---
|
||||
```
|
||||
|
||||
### outline
|
||||
|
||||
- 型: `number | [number, number] | 'deep' | false`
|
||||
- 既定値: `2`
|
||||
|
||||
ページのアウトラインに表示する見出しレベルです。[config.themeConfig.outline.level](./default-theme-config#outline) と同じ意味で、サイトレベルの設定を上書きします。
|
||||
|
||||
```yaml
|
||||
---
|
||||
outline: [2, 4]
|
||||
---
|
||||
```
|
||||
|
||||
### lastUpdated
|
||||
|
||||
- 型: `boolean | Date`
|
||||
- 既定値: `true`
|
||||
|
||||
現在のページのフッターに[最終更新](./default-theme-last-updated)を表示するかどうか。日時を指定した場合は、その日時が Git の最終更新時刻の代わりに表示されます。
|
||||
|
||||
```yaml
|
||||
---
|
||||
lastUpdated: false
|
||||
---
|
||||
```
|
||||
|
||||
### editLink
|
||||
|
||||
- 型: `boolean`
|
||||
- 既定値: `true`
|
||||
|
||||
現在のページのフッターに[編集リンク](./default-theme-edit-link)を表示するかどうか。
|
||||
|
||||
```yaml
|
||||
---
|
||||
editLink: false
|
||||
---
|
||||
```
|
||||
|
||||
### footer
|
||||
|
||||
- 型: `boolean`
|
||||
- 既定値: `true`
|
||||
|
||||
[フッター](./default-theme-footer) を表示するかどうか。
|
||||
|
||||
```yaml
|
||||
---
|
||||
footer: false
|
||||
---
|
||||
```
|
||||
|
||||
### pageClass
|
||||
|
||||
- 型: `string`
|
||||
|
||||
特定のページに追加のクラス名を付与します。
|
||||
|
||||
```yaml
|
||||
---
|
||||
pageClass: custom-page-class
|
||||
---
|
||||
```
|
||||
|
||||
その後、`.vitepress/theme/custom.css` でこのページ専用のスタイルを記述できます。
|
||||
|
||||
```css
|
||||
.custom-page-class {
|
||||
/* ページ固有のスタイル */
|
||||
}
|
||||
```
|
||||
|
||||
### isHome
|
||||
|
||||
- 型: `boolean`
|
||||
|
||||
デフォルトテーマは通常、`frontmatter.layout === 'home'` のチェックに基づいてホームページかどうかを判断します。\
|
||||
カスタムレイアウトでホームページ用の要素を強制的に表示したい場合に便利です。
|
||||
|
||||
```yaml
|
||||
---
|
||||
isHome: true
|
||||
---
|
||||
```
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue