页面与布局

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

内置路由

路由生成条件内容来源
/项目中没有 app/pages/index.vuecontent/index.md
/docs/**始终生成content/docs/**
/releases、/releases/:tag存在 content/releases.yml 或 content/releases.mdGitHub 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 的页面组件:

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 中的版本号会链接到站内对应版本
版本发布页
content/releases.yml
title: 版本发布
description: 查看 My Docs 的版本更新、功能增强与问题修复。
navigation: false
# 可选:在版本导航中列出预发布版本,默认 false
prerelease: false
# 可选:版本导航只列出 tag 匹配该正则的版本
include: '^v3\.'
GitHub 数据在服务端缓存 1 小时。生产环境请配置 NUXT_GITHUB_TOKEN 以避免匿名请求的频率限制;GitHub 不可达时页面显示提示,不会让构建失败。被 prerelease 或 include 筛掉的版本不会出现在导航中,但仍可通过 tag 路径直接访问。

案例页

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

案例页
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 中添加链接,见导航与分类。

自定义页面

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

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默认值说明
headertrue设为 false 时不渲染 Header
footertrue设为 false 时不渲染 Footer
layout'default'页面使用的布局

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

布局

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

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

app/layouts/wide.vue
<template>
  <UMain>
    <UContainer class="max-w-screen-2xl">
      <slot />
    </UContainer>
  </UMain>
</template>
app/pages/playground.vue
<script setup lang="ts">
definePageMeta({
  layout: 'wide'
})
</script>
覆盖 docs 布局时需要保留 provide('docsFilterSearch', ...) 与 DocsAsideLeftTop / DocsAsideLeftBody 的挂载,否则侧栏过滤与导航会失效。参考 docs.vue 源码。
Copyright © 2024 - 2026