---
title: "页面与布局"
description: "除文档页外，Layer 会根据 content 目录中的文件自动生成首页、版本发布页与案例页，你也可以在 app/pages 中编写任意 Vue 页面。本页说明各内置路由的生成条件与内容格式、自定义页面的页头页脚开关，以及内置布局。"
canonical_url: "https://docs.mhaibaraai.cn/docs/guide/pages"
---
# 页面与布局

> 除文档页外，Layer 会根据 content 目录中的文件自动生成首页、版本发布页与案例页，你也可以在 app/pages 中编写任意 Vue 页面。本页说明各内置路由的生成条件与内容格式、自定义页面的页头页脚开关，以及内置布局。

## 内置路由

| 路由 | 生成条件 | 内容来源 |
| --- | --- | --- |
| `/` | 项目中**没有** `app/pages/index.vue` | `content/index.md` |
| `/docs/**` | 始终生成 | `content/docs/**` |
| `/releases`、`/releases/:tag` | 存在 `content/releases.yml` 或 `content/releases.md` | GitHub Releases |
| `/templates` | 存在 `content/templates.yml` 或 `content/templates.md` | 文件中的 `items` |

启用国际化后，其他语言的对应文件放在 `content/{locale}/` 下（如 `content/en/releases.yml`），缺少某个语言的文件时该语言的路由返回 404。路由在构建期根据文件是否存在决定，新增或删除这些文件后需要重启开发服务器。

## 首页

没有 `app/pages/index.vue` 时，首页渲染 `content/index.md`，可以用 MDC 语法组合 Nuxt UI 的页面组件：

```md [content/index.md]
---
title: My Docs
description: 一句话介绍你的项目。
---

::u-page-hero
#title
My Docs

#description
一句话介绍你的项目。

#links
  :::u-button{to="/docs/getting-started" size="xl" trailing-icon="i-lucide-arrow-right"}
  快速开始
  :::
::
```

需要完全由代码控制首页时，创建 `app/pages/index.vue`，Layer 便不再注入首页路由，也不再注册 `landing` 内容集合。

## 版本发布页

`/releases` 展示最新版本，`/releases/v3.0.0` 等路径展示指定版本，数据来自 `app.config` 中 `github.owner` / `github.name` 对应仓库的 GitHub Releases：

- 左侧为按主版本分组的版本导航，右侧为说明正文的目录，底部可切换到相邻版本
- 页面在服务端渲染，可预渲染与被搜索引擎收录；说明中的 `@用户名` 自动链接到 GitHub 主页
- 存在版本发布页时，`CommitChangelog` 中的版本号会链接到站内对应版本

::u-color-mode-image{alt="版本发布页" class="rounded-md border border-default" dark="/screenshots/releases-page-dark.png" light="/screenshots/releases-page-light.png"}
::

```yaml [content/releases.yml]
title: 版本发布
description: 查看 My Docs 的版本更新、功能增强与问题修复。
navigation: false
# 可选：在版本导航中列出预发布版本，默认 false
prerelease: false
# 可选：版本导航只列出 tag 匹配该正则的版本
include: '^v3\.'
```

> [!NOTE]
> 
> GitHub 数据在服务端缓存 1 小时。生产环境请配置 
> 
> NUXT_GITHUB_TOKEN
> 
>  以避免匿名请求的频率限制；GitHub 不可达时页面显示提示，不会让构建失败。被 
> 
> prerelease
> 
>  或 
> 
> include
> 
>  筛掉的版本不会出现在导航中，但仍可通过 tag 路径直接访问。

## 案例页

`/templates` 以卡片形式展示模板或使用该主题的真实站点：

::u-color-mode-image{alt="案例页" class="rounded-md border border-default" dark="/screenshots/templates-page-dark.png" light="/screenshots/templates-page-light.png"}
::

```yaml [content/templates.yml]
title: 案例
description: 这些站点均由 My Docs 主题构建。
navigation: false
hero:
  title: 案例
  description: 这些站点均由 My Docs 主题构建。
items:
  - title: '@my/core'
    description: Vue 工具函数库的文档站。
    features:
      - title: API 参考
        icon: i-lucide-book-open
      - title: 组件示例
        icon: i-lucide-shapes
    links:
      - label: 访问站点
        to: https://core.example.com
        target: _blank
        icon: i-lucide-link
```

| 字段 | 说明 |
| --- | --- |
| `hero` | 页面顶部的标题区，可带 `links` 按钮 |
| `items[].title` | 卡片标题，同时用于推导截图文件名 |
| `items[].description` | 卡片描述 |
| `items[].features` | 带图标的特性列表 |
| `items[].links` | 卡片底部的按钮，字段与 Nuxt UI 的 `UButton` 一致 |

每张卡片的截图按约定从 `public/assets/templates/` 加载：`{slug}-light.png` 与 `{slug}-dark.png`。`slug` 由 `title` 转小写、把非字母数字的连续字符替换为 `-` 并去掉首尾的 `-` 得到，例如 `@my/core` 对应 `my-core-light.png` 与 `my-core-dark.png`。

两类页面都不会自动出现在页头，请在 `header.nav` 中添加链接，见[导航与分类](https://docs.mhaibaraai.cn/docs/guide/navigation#%E9%A1%B5%E5%A4%B4%E5%AF%BC%E8%88%AA)。

## 自定义页面

在 `app/pages/` 中创建 Vue 文件即可添加页面，路由规则与普通 Nuxt 项目相同：

```vue [app/pages/showcase.vue]
<script setup lang="ts">
definePageMeta({
  // 不渲染全局页头与页脚
  header: false,
  footer: false
})

useSeoMeta({
  title: '展示',
  description: '自定义页面示例'
})
</script>

<template>
  <UContainer class="py-16">
    <h1 class="font-display text-4xl font-bold">
      展示
    </h1>
  </UContainer>
</template>
```

| 页面 meta | 默认值 | 说明 |
| --- | --- | --- |
| `header` | `true` | 设为 `false` 时不渲染 `Header` |
| `footer` | `true` | 设为 `false` 时不渲染 `Footer` |
| `layout` | `'default'` | 页面使用的布局 |

路径以 `/examples` 开头的页面同样不渲染页头与页脚，这一前缀留给组件示例的独立预览页使用。

## 布局

| 布局 | 用途 |
| --- | --- |
| `default` | 首页、版本发布页、案例页与自定义页面，只提供 `<main>` 容器 |
| `docs` | 文档页，包含左侧栏（导航过滤框与文档导航） |

在 `app/layouts/` 中创建同名文件可以覆盖内置布局，或新建布局供自定义页面使用：

```vue [app/layouts/wide.vue]
<template>
  <UMain>
    <UContainer class="max-w-screen-2xl">
      <slot />
    </UContainer>
  </UMain>
</template>
```

```vue [app/pages/playground.vue]
<script setup lang="ts">
definePageMeta({
  layout: 'wide'
})
</script>
```

> [!WARNING]
> 
> 覆盖 
> 
> docs
> 
>  布局时需要保留 
> 
> provide('docsFilterSearch', ...)
> 
>  与 
> 
> DocsAsideLeftTop
> 
>  / 
> 
> DocsAsideLeftBody
> 
>  的挂载，否则侧栏过滤与导航会失效。参考 
> 
> docs.vue 源码
> 
> 。


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
