页面与布局
内置路由
| 路由 | 生成条件 | 内容来源 |
|---|---|---|
/ | 项目中没有 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 的页面组件:
---
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中的版本号会链接到站内对应版本


title: 版本发布
description: 查看 My Docs 的版本更新、功能增强与问题修复。
navigation: false
# 可选:在版本导航中列出预发布版本,默认 false
prerelease: false
# 可选:版本导航只列出 tag 匹配该正则的版本
include: '^v3\.'
NUXT_GITHUB_TOKEN 以避免匿名请求的频率限制;GitHub 不可达时页面显示提示,不会让构建失败。被 prerelease 或 include 筛掉的版本不会出现在导航中,但仍可通过 tag 路径直接访问。案例页
/templates 以卡片形式展示模板或使用该主题的真实站点:


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 中添加链接,见导航与分类。
自定义页面
在 app/pages/ 中创建 Vue 文件即可添加页面,路由规则与普通 Nuxt 项目相同:
<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/ 中创建同名文件可以覆盖内置布局,或新建布局供自定义页面使用:
<template>
<UMain>
<UContainer class="max-w-screen-2xl">
<slot />
</UContainer>
</UMain>
</template>
<script setup lang="ts">
definePageMeta({
layout: 'wide'
})
</script>
docs 布局时需要保留 provide('docsFilterSearch', ...) 与 DocsAsideLeftTop / DocsAsideLeftBody 的挂载,否则侧栏过滤与导航会失效。参考 docs.vue 源码。