主題首頁（Home Page）布局完整配置指南：Hero、Features 與自定義內(nèi)容)
VitePress 默認(rèn)主題首頁Home Page布局完整配置指南Hero、Features 與自定義內(nèi)容【免費下載鏈接】vitepressVite Vue powered static site generator.項目地址: https://gitcode.com/gh_mirrors/vi/vitepressVitePress 默認(rèn)主題內(nèi)置了一套開箱即用的首頁Home Page布局通過layout: home即可在任意頁面啟用再配合hero、features等前置元數(shù)據(jù)frontmatter選項就能搭建出包含品牌主視覺、行動按鈕、特性卡片與自由 Markdown 內(nèi)容的落地頁。本文以docs/en/reference/default-theme-home-page.md為骨架結(jié)合倉庫源碼與類型定義系統(tǒng)講解首頁布局的每一個配置項、渲染鏈路與樣式定制技巧讀完即可在項目中直接落地一套完整的首頁。啟用首頁布局layout: homeVitePress 默認(rèn)主題將首頁布局應(yīng)用在本站首頁上見 docs/en/index.md。你可以在任何頁面的 frontmatter 配置 中通過layout: home啟用它--- layout: home ---不過僅此一項并不會產(chǎn)生太多效果。要讓首頁真正豐富起來還需要通過hero、features等選項為頁面添加多個預(yù)制區(qū)塊。從源碼看這些區(qū)塊最終由 VPHome.vue 按固定順序組裝home-hero-before 插槽 └─ VPHomeHero Hero 區(qū)塊品牌名、標(biāo)語、圖片、行動按鈕 home-hero-after 插槽 home-features-before 插槽 └─ VPHomeFeatures Features 區(qū)塊特性卡片網(wǎng)格 home-features-after 插槽 └─ VPHomeContent 前置元數(shù)據(jù)分隔線---以下的 Markdown 內(nèi)容其中VPHomeHero、VPHomeFeatures組件會分別讀取frontmatter.hero與frontmatter.features只要前置元數(shù)據(jù)中不存在對應(yīng)鍵相應(yīng)區(qū)塊就不會渲染VPHomeHero.vue、VPHomeFeatures.vue 中均以v-iffm.hero/v-iffm.features守衛(wèi)。Hero 區(qū)塊品牌首屏視覺Hero 區(qū)塊位于首頁頂部是訪客最先看到的品牌區(qū)域。下面是一個完整的 Hero 配置示例--- 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://example.com ---對應(yīng)的 TypeScript 類型定義如下該定義同時體現(xiàn)在 VPHero.vue 的 props 上interface Hero { // 顯示在 text 上方的字符串自帶品牌色期望較短如產(chǎn)品名。 name?: string // Hero 區(qū)塊的主文本會被渲染為 h1 標(biāo)簽。 text: string // 顯示在 text 下方的標(biāo)語。 tagline?: string // 顯示在文本與標(biāo)語區(qū)域旁邊的圖片。 image?: ThemeableImage // 首頁 Hero 區(qū)塊中展示的操作按鈕。 actions?: HeroAction[] } type ThemeableImage | string | { src: string; alt?: string } | { light: string; dark: string; alt?: string } interface HeroAction { // 按鈕配色主題默認(rèn) brand。 theme?: brand | alt // 按鈕上的文字。 text: string // 按鈕的跳轉(zhuǎn)地址。 link: string // 鏈接的 target 屬性。 target?: string // 鏈接的 rel 屬性。 rel?: string }各字段的要點說明字段必填說明name否顯示在text上方的品牌名默認(rèn)使用品牌色渲染通常較短如產(chǎn)品名text是Hero 主標(biāo)題渲染為h1標(biāo)簽tagline否主標(biāo)題下方的標(biāo)語/副文案image否與文本并排展示的圖片支持字符串路徑、{ src, alt }或{ light, dark, alt }三種形態(tài)actions否操作按鈕數(shù)組每個按鈕可配置themebrand/alt、text、link、target、relHero 圖片的淺色/深色適配ThemeableImage的第三種形態(tài){ light, dark }允許你為淺色與深色主題分別提供圖片。該邏輯由 VPImage.vue 實現(xiàn)它會同時渲染兩張圖再通過 CSS 規(guī)則html:not(.dark) .VPImage.dark { display: none }與html.dark .VPImage.light { display: none }按當(dāng)前主題顯示其中一張。圖片路徑統(tǒng)一經(jīng)withBase處理后指向站點根目錄即public目錄下的靜態(tài)資源因此示例中的/logo.png實際對應(yīng)public/logo.png。源碼視角Hero 的渲染鏈路從組件調(diào)用鏈看Hero 區(qū)塊的渲染路徑為VPHome.vue→VPHomeHero.vue→ VPHero.vue。在 VPHero.vue 中可以看到幾個關(guān)鍵實現(xiàn)細(xì)節(jié)name、text、tagline均通過v-html渲染并以dirauto自動適配文字方向RTL 站點也可正常顯示name使用span.clip包裹配合-webkit-background-clip: text實現(xiàn)漸變文字效果每個action渲染為一個 VPButton.vuetheme決定按鈕配色組件支持home-hero-info-before、home-hero-image等具名插槽便于自定義主題時擴展。此外Hero 圖片背景還暴露了兩個樣式變量--vp-home-hero-image-background-image與--vp-home-hero-image-filter定義于 vars.css默認(rèn)分別為none可在全局樣式中覆寫為漸變或濾鏡為圖片添加圓形光暈等裝飾效果。自定義 name 顏色與漸變效果VitePress 默認(rèn)使用品牌色--vp-c-brand-1渲染name該值定義于 vars.css:root { --vp-home-hero-name-color: var(--vp-c-brand-1); --vp-home-hero-name-background: transparent; }你可以通過覆寫--vp-home-hero-name-color變量來改變品牌名的顏色:root { --vp-home-hero-name-color: blue; }更進一步可以組合--vp-home-hero-name-background給name添加漸變效果。實現(xiàn)原理是將文字顏色設(shè)為透明再以背景漸變配合background-clip: text將漸變裁剪進文字筆畫內(nèi)對應(yīng) VPHero.vue 中.clip類的樣式:root { --vp-home-hero-name-color: transparent; --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff); }VitePress 官網(wǎng)首頁的品牌名漸變即由此實現(xiàn)。需要注意的是漸變方向參數(shù)如120deg與顏色可以任意調(diào)整但務(wù)必同時設(shè)置--vp-home-hero-name-color: transparent否則漸變會被不透明的文字顏色蓋住。Features 區(qū)塊特性卡片網(wǎng)格在 Hero 區(qū)塊之后可以通過features選項展示任意數(shù)量的特性卡片。每個特性可以配置一個圖標(biāo)圖標(biāo)既可以是 emoji也可以是任意類型的圖片svg、png、jpeg 等。使用圖片作為圖標(biāo)時必須提供合適的寬高需要適配深淺主題時還可以分別提供dark/light變體--- 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... ---對應(yīng)的類型定義如下interface Feature { // 在特性卡片上顯示的圖標(biāo)。 icon?: FeatureIcon // 特性的標(biāo)題。 title: string // 特性的詳細(xì)描述。 details: string // 點擊特性卡片時跳轉(zhuǎn)的鏈接支持站內(nèi)與站外地址。 // // e.g. guide/reference/default-theme-home-page 或 https://example.com link?: string // 特性卡片內(nèi)展示的鏈接文字通常配合 link 使用。 // // e.g. Learn more、Visit page 等 linkText?: string // 配合 link 使用的 rel 屬性。 // // e.g. external rel?: string // 配合 link 使用的 target 屬性。 target?: string } type FeatureIcon | string | { src: string; alt?: string; width?: string; height: string } | { light: string dark: string alt?: string width?: string height: string }各字段的要點說明字段必填說明icon否特性圖標(biāo)。字符串時直接作為 emoji/文字渲染對象形式需提供src或light/dark與heightwidth、alt可選title是特性標(biāo)題details是特性描述文字link否整張卡片變?yōu)殒溄又С终緝?nèi)與站外地址linkText否卡片內(nèi)的鏈接文字如 Learn more右側(cè)會自動帶一個箭頭圖標(biāo)rel/target否配合link使用的鏈接屬性源碼視角圖標(biāo)渲染與卡片細(xì)節(jié)在 VPFeature.vue 中可以看到三個值得注意的實現(xiàn)點圖標(biāo)形態(tài)分發(fā)字符串圖標(biāo)通過v-html直接渲染emoji 天然支持對象形態(tài)的圖標(biāo)交給VPImage渲染默認(rèn)寬高均為48可通過width/height覆寫對象還支持wrap布爾屬性為true時圖標(biāo)會被包裹進帶背景的.icon容器中details支持?jǐn)?shù)組details除了字符串還可以是字符串?dāng)?shù)組此時會渲染為無序列表ul適合展示特性要點卡片鏈接交互配置link后卡片整體變?yōu)榭牲c擊鏈接a標(biāo)簽懸停時邊框會過渡為品牌色--vp-c-brand-1配置linkText時卡片底部會顯示品牌色鏈接文字與vpi-arrow-right箭頭圖標(biāo)。源碼視角網(wǎng)格自適應(yīng)規(guī)則卡片網(wǎng)格的列數(shù)由 VPFeatures.vue 根據(jù)特性數(shù)量自動計算特性數(shù)量網(wǎng)格類名桌面端布局2 個grid-2兩列3 個grid-3三列3 的倍數(shù)6、9…grid-6六列大于 3 且非 3 的倍數(shù)4、5、7…grid-4四列1 個無整行單列對應(yīng)的 CSS 響應(yīng)式斷點如下grid-2/grid-4/grid-6在 ≥40rem 視口下每行 2 個grid-3/grid-6在 ≥48rem 視口下每行 3 個grid-4在 ≥60rem 視口下每行 4 個。也就是說想排 2 列就配置 2 或 4 個特性想排 3 列就配置 3 個或 3 的倍數(shù)規(guī)則直觀且會自動適配移動端。在首頁追加 Markdown 內(nèi)容除了 Hero 與 Features 兩個預(yù)制區(qū)塊你還可以直接在 frontmatter 結(jié)束標(biāo)記---下方編寫 Markdown作為首頁的附加內(nèi)容例如快速上手指引、團隊成員介紹、贊助商區(qū)塊等--- 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 這段 Markdown 會被渲染在 Features 區(qū)塊之后。從源碼看VPHome.vue 會根據(jù)markdownStyles決定附加內(nèi)容的渲染方式VPHomeContent v-iffrontmatter.markdownStyles ! false Content / /VPHomeContent Content v-else /::: info VitePress 并非從一開始就自動為layout: home頁面的附加內(nèi)容套用文檔樣式。如果你希望回退到舊行為不套用文檔排版樣式可以在 frontmatter 中添加markdownStyles: false。 :::默認(rèn)情況下附加內(nèi)容會被包裹在帶vp-doc類的 VPHomeContent.vue 容器中因此標(biāo)題、列表、代碼塊等都會獲得與正文一致的排版樣式設(shè)置markdownStyles: false后則原樣輸出Content /不套用任何文檔樣式適合嵌入完全自定義的組件內(nèi)容。同時 VPHomeContent.vue 還針對VPHomeSponsors、VPTeamPage等全寬組件做了視口拉伸處理讓首頁附加內(nèi)容可以容納全寬區(qū)塊。實戰(zhàn)組裝一個完整首頁綜合以上所有內(nèi)容一個完整的首頁示例可保存為站點根目錄的index.md如下--- layout: home hero: name: My Docs text: A modern documentation site. tagline: Built with VitePress, powered by Vite Vue. image: src: /logo.png alt: My Docs logo actions: - theme: brand text: Get Started link: /guide/getting-started - theme: alt text: View on GitHub link: https://example.com target: _blank rel: external features: - icon: ?? title: Blazing Fast details: Vite-powered development experience with instant HMR. - icon: src: /cool-feature-icon.svg width: 48 height: 48 title: Customizable details: Fully configurable via frontmatter and theme options. link: /guide/custom-theme linkText: Learn more - icon: dark: /dark-feature-icon.svg light: /light-feature-icon.svg width: 48 height: 48 title: Theme Aware details: Automatically switches between light and dark icons. --- ## Quick Start sh npm init npx vitepress init在撰寫時請注意以下幾點圖片資源image與icon中的/xxx.png、/xxx.svg路徑均以站點根目錄為基準(zhǔn)實際文件應(yīng)放在項目根目錄的public/文件夾下倉庫示例見__tests__/base/fixture/public/樣式定制顏色與漸變覆寫建議寫入主題的全局樣式如docs/.vitepress/theme/index.ts引入的 CSS或自定義樣式表中相關(guān)變量定義可參考 vars.css類型依據(jù)ThemeableImage與FeatureIcon的完整類型定義見 types/default-theme.d.ts編寫自定義主題時可直接復(fù)用這些類型以保證兼容性。小結(jié)本文圍繞 VitePress 默認(rèn)主題的首頁布局完整梳理了從layout: home啟用、Hero 區(qū)塊配置、name 漸變定制、Features 卡片網(wǎng)格到附加 Markdown 內(nèi)容的全部要點并結(jié)合 VPHome.vue、VPHero.vue、VPFeatures.vue、VPFeature.vue 等源碼揭示了其內(nèi)部渲染鏈路與響應(yīng)式規(guī)則。掌握這些配置與實現(xiàn)細(xì)節(jié)后你可以用純 Markdown 前置元數(shù)據(jù)構(gòu)建出風(fēng)格統(tǒng)一、深淺色自適應(yīng)的產(chǎn)品首頁如需進一步定制可繼續(xù)閱讀 默認(rèn)主題布局參考 與 frontmatter 配置參考深入理解首頁布局與整個默認(rèn)主題體系的關(guān)系。【免費下載鏈接】vitepressVite Vue powered static site generator.項目地址: https://gitcode.com/gh_mirrors/vi/vitepress創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 VitePress 默認(rèn)主題首頁（Home Page）布局完整配置指南：Hero、Features 與自定義內(nèi)容
VitePress 默認(rèn)主題首頁Home Page布局完整配置指南Hero、Features 與自定義內(nèi)容【免費下載鏈接】vitepressVite Vue powered static site generator.項目地址: https://gitcode.com/gh_mirrors/vi/vitepressVitePress 默認(rèn)主題內(nèi)置了一套開箱即用的首頁Home Page布局通過layout: home即可在任意頁面啟用再配合hero、features等前置元數(shù)據(jù)frontmatter選項就能搭建出包含品牌主視覺、行動按鈕、特性卡片與自由 Markdown 內(nèi)容的落地頁。本文以docs/en/reference/default-theme-home-page.md為骨架結(jié)合倉庫源碼與類型定義系統(tǒng)講解首頁布局的每一個配置項、渲染鏈路與樣式定制技巧讀完即可在項目中直接落地一套完整的首頁。啟用首頁布局layout: homeVitePress 默認(rèn)主題將首頁布局應(yīng)用在本站首頁上見 docs/en/index.md。你可以在任何頁面的 frontmatter 配置 中通過layout: home啟用它--- layout: home ---不過僅此一項并不會產(chǎn)生太多效果。要讓首頁真正豐富起來還需要通過hero、features等選項為頁面添加多個預(yù)制區(qū)塊。從源碼看這些區(qū)塊最終由 VPHome.vue 按固定順序組裝home-hero-before 插槽 └─ VPHomeHero Hero 區(qū)塊品牌名、標(biāo)語、圖片、行動按鈕 home-hero-after 插槽 home-features-before 插槽 └─ VPHomeFeatures Features 區(qū)塊特性卡片網(wǎng)格 home-features-after 插槽 └─ VPHomeContent 前置元數(shù)據(jù)分隔線---以下的 Markdown 內(nèi)容其中VPHomeHero、VPHomeFeatures組件會分別讀取frontmatter.hero與frontmatter.features只要前置元數(shù)據(jù)中不存在對應(yīng)鍵相應(yīng)區(qū)塊就不會渲染VPHomeHero.vue、VPHomeFeatures.vue 中均以v-iffm.hero/v-iffm.features守衛(wèi)。Hero 區(qū)塊品牌首屏視覺Hero 區(qū)塊位于首頁頂部是訪客最先看到的品牌區(qū)域。下面是一個完整的 Hero 配置示例--- 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://example.com ---對應(yīng)的 TypeScript 類型定義如下該定義同時體現(xiàn)在 VPHero.vue 的 props 上interface Hero { // 顯示在 text 上方的字符串自帶品牌色期望較短如產(chǎn)品名。 name?: string // Hero 區(qū)塊的主文本會被渲染為 h1 標(biāo)簽。 text: string // 顯示在 text 下方的標(biāo)語。 tagline?: string // 顯示在文本與標(biāo)語區(qū)域旁邊的圖片。 image?: ThemeableImage // 首頁 Hero 區(qū)塊中展示的操作按鈕。 actions?: HeroAction[] } type ThemeableImage | string | { src: string; alt?: string } | { light: string; dark: string; alt?: string } interface HeroAction { // 按鈕配色主題默認(rèn) brand。 theme?: brand | alt // 按鈕上的文字。 text: string // 按鈕的跳轉(zhuǎn)地址。 link: string // 鏈接的 target 屬性。 target?: string // 鏈接的 rel 屬性。 rel?: string }各字段的要點說明字段必填說明name否顯示在text上方的品牌名默認(rèn)使用品牌色渲染通常較短如產(chǎn)品名text是Hero 主標(biāo)題渲染為h1標(biāo)簽tagline否主標(biāo)題下方的標(biāo)語/副文案image否與文本并排展示的圖片支持字符串路徑、{ src, alt }或{ light, dark, alt }三種形態(tài)actions否操作按鈕數(shù)組每個按鈕可配置themebrand/alt、text、link、target、relHero 圖片的淺色/深色適配ThemeableImage的第三種形態(tài){ light, dark }允許你為淺色與深色主題分別提供圖片。該邏輯由 VPImage.vue 實現(xiàn)它會同時渲染兩張圖再通過 CSS 規(guī)則html:not(.dark) .VPImage.dark { display: none }與html.dark .VPImage.light { display: none }按當(dāng)前主題顯示其中一張。圖片路徑統(tǒng)一經(jīng)withBase處理后指向站點根目錄即public目錄下的靜態(tài)資源因此示例中的/logo.png實際對應(yīng)public/logo.png。源碼視角Hero 的渲染鏈路從組件調(diào)用鏈看Hero 區(qū)塊的渲染路徑為VPHome.vue→VPHomeHero.vue→ VPHero.vue。在 VPHero.vue 中可以看到幾個關(guān)鍵實現(xiàn)細(xì)節(jié)name、text、tagline均通過v-html渲染并以dirauto自動適配文字方向RTL 站點也可正常顯示name使用span.clip包裹配合-webkit-background-clip: text實現(xiàn)漸變文字效果每個action渲染為一個 VPButton.vuetheme決定按鈕配色組件支持home-hero-info-before、home-hero-image等具名插槽便于自定義主題時擴展。此外Hero 圖片背景還暴露了兩個樣式變量--vp-home-hero-image-background-image與--vp-home-hero-image-filter定義于 vars.css默認(rèn)分別為none可在全局樣式中覆寫為漸變或濾鏡為圖片添加圓形光暈等裝飾效果。自定義 name 顏色與漸變效果VitePress 默認(rèn)使用品牌色--vp-c-brand-1渲染name該值定義于 vars.css:root { --vp-home-hero-name-color: var(--vp-c-brand-1); --vp-home-hero-name-background: transparent; }你可以通過覆寫--vp-home-hero-name-color變量來改變品牌名的顏色:root { --vp-home-hero-name-color: blue; }更進一步可以組合--vp-home-hero-name-background給name添加漸變效果。實現(xiàn)原理是將文字顏色設(shè)為透明再以背景漸變配合background-clip: text將漸變裁剪進文字筆畫內(nèi)對應(yīng) VPHero.vue 中.clip類的樣式:root { --vp-home-hero-name-color: transparent; --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff); }VitePress 官網(wǎng)首頁的品牌名漸變即由此實現(xiàn)。需要注意的是漸變方向參數(shù)如120deg與顏色可以任意調(diào)整但務(wù)必同時設(shè)置--vp-home-hero-name-color: transparent否則漸變會被不透明的文字顏色蓋住。Features 區(qū)塊特性卡片網(wǎng)格在 Hero 區(qū)塊之后可以通過features選項展示任意數(shù)量的特性卡片。每個特性可以配置一個圖標(biāo)圖標(biāo)既可以是 emoji也可以是任意類型的圖片svg、png、jpeg 等。使用圖片作為圖標(biāo)時必須提供合適的寬高需要適配深淺主題時還可以分別提供dark/light變體--- 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... ---對應(yīng)的類型定義如下interface Feature { // 在特性卡片上顯示的圖標(biāo)。 icon?: FeatureIcon // 特性的標(biāo)題。 title: string // 特性的詳細(xì)描述。 details: string // 點擊特性卡片時跳轉(zhuǎn)的鏈接支持站內(nèi)與站外地址。 // // e.g. guide/reference/default-theme-home-page 或 https://example.com link?: string // 特性卡片內(nèi)展示的鏈接文字通常配合 link 使用。 // // e.g. Learn more、Visit page 等 linkText?: string // 配合 link 使用的 rel 屬性。 // // e.g. external rel?: string // 配合 link 使用的 target 屬性。 target?: string } type FeatureIcon | string | { src: string; alt?: string; width?: string; height: string } | { light: string dark: string alt?: string width?: string height: string }各字段的要點說明字段必填說明icon否特性圖標(biāo)。字符串時直接作為 emoji/文字渲染對象形式需提供src或light/dark與heightwidth、alt可選title是特性標(biāo)題details是特性描述文字link否整張卡片變?yōu)殒溄又С终緝?nèi)與站外地址linkText否卡片內(nèi)的鏈接文字如 Learn more右側(cè)會自動帶一個箭頭圖標(biāo)rel/target否配合link使用的鏈接屬性源碼視角圖標(biāo)渲染與卡片細(xì)節(jié)在 VPFeature.vue 中可以看到三個值得注意的實現(xiàn)點圖標(biāo)形態(tài)分發(fā)字符串圖標(biāo)通過v-html直接渲染emoji 天然支持對象形態(tài)的圖標(biāo)交給VPImage渲染默認(rèn)寬高均為48可通過width/height覆寫對象還支持wrap布爾屬性為true時圖標(biāo)會被包裹進帶背景的.icon容器中details支持?jǐn)?shù)組details除了字符串還可以是字符串?dāng)?shù)組此時會渲染為無序列表ul適合展示特性要點卡片鏈接交互配置link后卡片整體變?yōu)榭牲c擊鏈接a標(biāo)簽懸停時邊框會過渡為品牌色--vp-c-brand-1配置linkText時卡片底部會顯示品牌色鏈接文字與vpi-arrow-right箭頭圖標(biāo)。源碼視角網(wǎng)格自適應(yīng)規(guī)則卡片網(wǎng)格的列數(shù)由 VPFeatures.vue 根據(jù)特性數(shù)量自動計算特性數(shù)量網(wǎng)格類名桌面端布局2 個grid-2兩列3 個grid-3三列3 的倍數(shù)6、9…grid-6六列大于 3 且非 3 的倍數(shù)4、5、7…grid-4四列1 個無整行單列對應(yīng)的 CSS 響應(yīng)式斷點如下grid-2/grid-4/grid-6在 ≥40rem 視口下每行 2 個grid-3/grid-6在 ≥48rem 視口下每行 3 個grid-4在 ≥60rem 視口下每行 4 個。也就是說想排 2 列就配置 2 或 4 個特性想排 3 列就配置 3 個或 3 的倍數(shù)規(guī)則直觀且會自動適配移動端。在首頁追加 Markdown 內(nèi)容除了 Hero 與 Features 兩個預(yù)制區(qū)塊你還可以直接在 frontmatter 結(jié)束標(biāo)記---下方編寫 Markdown作為首頁的附加內(nèi)容例如快速上手指引、團隊成員介紹、贊助商區(qū)塊等--- 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 這段 Markdown 會被渲染在 Features 區(qū)塊之后。從源碼看VPHome.vue 會根據(jù)markdownStyles決定附加內(nèi)容的渲染方式VPHomeContent v-iffrontmatter.markdownStyles ! false Content / /VPHomeContent Content v-else /::: info VitePress 并非從一開始就自動為layout: home頁面的附加內(nèi)容套用文檔樣式。如果你希望回退到舊行為不套用文檔排版樣式可以在 frontmatter 中添加markdownStyles: false。 :::默認(rèn)情況下附加內(nèi)容會被包裹在帶vp-doc類的 VPHomeContent.vue 容器中因此標(biāo)題、列表、代碼塊等都會獲得與正文一致的排版樣式設(shè)置markdownStyles: false后則原樣輸出Content /不套用任何文檔樣式適合嵌入完全自定義的組件內(nèi)容。同時 VPHomeContent.vue 還針對VPHomeSponsors、VPTeamPage等全寬組件做了視口拉伸處理讓首頁附加內(nèi)容可以容納全寬區(qū)塊。實戰(zhàn)組裝一個完整首頁綜合以上所有內(nèi)容一個完整的首頁示例可保存為站點根目錄的index.md如下--- layout: home hero: name: My Docs text: A modern documentation site. tagline: Built with VitePress, powered by Vite Vue. image: src: /logo.png alt: My Docs logo actions: - theme: brand text: Get Started link: /guide/getting-started - theme: alt text: View on GitHub link: https://example.com target: _blank rel: external features: - icon: ?? title: Blazing Fast details: Vite-powered development experience with instant HMR. - icon: src: /cool-feature-icon.svg width: 48 height: 48 title: Customizable details: Fully configurable via frontmatter and theme options. link: /guide/custom-theme linkText: Learn more - icon: dark: /dark-feature-icon.svg light: /light-feature-icon.svg width: 48 height: 48 title: Theme Aware details: Automatically switches between light and dark icons. --- ## Quick Start sh npm init npx vitepress init在撰寫時請注意以下幾點圖片資源image與icon中的/xxx.png、/xxx.svg路徑均以站點根目錄為基準(zhǔn)實際文件應(yīng)放在項目根目錄的public/文件夾下倉庫示例見__tests__/base/fixture/public/樣式定制顏色與漸變覆寫建議寫入主題的全局樣式如docs/.vitepress/theme/index.ts引入的 CSS或自定義樣式表中相關(guān)變量定義可參考 vars.css類型依據(jù)ThemeableImage與FeatureIcon的完整類型定義見 types/default-theme.d.ts編寫自定義主題時可直接復(fù)用這些類型以保證兼容性。小結(jié)本文圍繞 VitePress 默認(rèn)主題的首頁布局完整梳理了從layout: home啟用、Hero 區(qū)塊配置、name 漸變定制、Features 卡片網(wǎng)格到附加 Markdown 內(nèi)容的全部要點并結(jié)合 VPHome.vue、VPHero.vue、VPFeatures.vue、VPFeature.vue 等源碼揭示了其內(nèi)部渲染鏈路與響應(yīng)式規(guī)則。掌握這些配置與實現(xiàn)細(xì)節(jié)后你可以用純 Markdown 前置元數(shù)據(jù)構(gòu)建出風(fēng)格統(tǒng)一、深淺色自適應(yīng)的產(chǎn)品首頁如需進一步定制可繼續(xù)閱讀 默認(rèn)主題布局參考 與 frontmatter 配置參考深入理解首頁布局與整個默認(rèn)主題體系的關(guān)系。【免費下載鏈接】vitepressVite Vue powered static site generator.項目地址: https://gitcode.com/gh_mirrors/vi/vitepress創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考