布局

你可以选择页面布局。有 3 个布局选项：doc、page 和 home。如果未指定任何内容，则页面被视为 doc 页面。

---
layout: doc
---

Doc 布局

选项 doc 是默认布局，它将整个 Markdown 内容样式化为"文档"外观。它的工作原理是将整个内容包装在 vp-doc css 类中，并将样式应用于其下的元素。

几乎所有通用元素（如 p 或 h2）都获得特殊样式。因此，请记住，如果你在 Markdown 内容中添加任何自定义 HTML，这些也将受到这些样式的影响。

它还提供文档特定功能，如：

• 编辑链接
• 上一页下一页链接
• Outline
• Carbon Ads

Page 布局

选项 page 被视为"空白页面"。Markdown 仍将被解析，所有 Markdown 扩展 的工作方式与 doc 布局相同，但它不会获得任何默认样式。

页面布局将让你样式化所有内容而不受 VitePress 主题影响。当你想创建自己的自定义页面时，这很有用。

请注意，即使在此布局中，如果页面具有匹配的侧边栏配置，侧边栏仍将显示。

Home 布局

选项 home 将生成模板化的"主页"。在此布局中，你可以设置额外的选项，如 hero 和 features 以进一步自定义内容。请访问默认主题：主页了解更多详细信息。

无布局

如果你不想要任何布局，你可以通过 frontmatter 传递 layout: false。如果你想要一个完全自定义的着陆页，这个选项很有帮助（没有侧边栏、导航栏或页脚的默认样式）。

自定义布局

你也可以使用自定义布局：

---
layout: foo
---

这将寻找名为 foo 的注册组件。例如，如果你的组件位于 .vitepress/theme/layouts/foo.vue，你需要将其注册到你的主题中：

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import Foo from './layouts/foo.vue'

export default {
  extends: DefaultTheme,
  Layout: Foo // <- 这里
}

或者你可以混合使用：

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import Foo from './layouts/foo.vue'

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      // https://vitepress.dev/guide/extending-default-theme#layout-slots
    })
  },
  enhanceApp({ app }) {
    app.component('foo', Foo)
  }
}

布局插槽

VitePress 的默认主题的 Layout 组件有一些插槽，可用于在页面的某些位置注入内容。以下是可用插槽的示例：

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'

export default {
  extends: DefaultTheme,
  Layout: MyLayout
}

<!--.vitepress/theme/MyLayout.vue-->
<script setup>
import DefaultTheme from 'vitepress/theme'

const { Layout } = DefaultTheme
</script>

<template>
  <Layout>
    <template #aside-outline-before>
      My custom sidebar top content
    </template>
  </Layout>
</template>

或者你可以使用渲染函数。

// .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)
    })
  }
}

VitePress 默认主题布局的完整插槽列表：

当 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-before
• home-hero-actions-after
• home-hero-image
• home-hero-after
• home-features-before
• home-features-after

当 layout: 'page' 时：

• page-top
• page-bottom

总是：

• 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

条件插槽

某些插槽可能会根据页面大小有条件地呈现。

目前有 4 个断点：

• mobile：768px
• tablet：960px
• laptop：1280px
• desktop：1440px

每个断点键可以作为插槽名称的后缀（用 - 分隔）。

这里有一个例子，只在桌面视口大小上呈现组件：

// .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-after-desktop': () => h(MyComponent)
    })
  }
}