目录概览
以 default 模板为例:
my-docs/
├── app/
│ ├── app.config.ts # 运行时 UI 配置(可选)
│ ├── components/ # 同名组件覆盖 Layer 默认实现(可选)
│ └── composables/ # 同名 composable 覆盖(可选)
├── content/
│ ├── index.md # 站点首页
│ ├── releases.yml # 版本发布页(可选)
│ ├── templates.yml # 案例页(可选)
│ └── docs/ # 文档页面,必需
├── public/ # 静态资源,按根路径提供
├── skills/ # Agent Skills(可选)
├── nuxt.config.ts # 模块级配置
├── .env.example # 环境变量示例
└── package.json
内容目录 content/
文档 content/docs/
文档固定放在 content/docs/ 下,路由前缀固定为 /docs。目录与文件名的数字前缀只控制排序,不出现在路由中:
content/docs/
├── 1.getting-started/
│ ├── .navigation.yml # 分区标题与图标
│ ├── 1.index.md # /docs/getting-started
│ └── 2.installation.md # /docs/getting-started/installation
└── 2.guide/
├── .navigation.yml
└── 1.configuration.md # /docs/guide/configuration
- 第一级目录是一个分区,页头下方的栏目条与侧栏按分区切换
.navigation.yml设置分区在导航中的title与icon- 分区内的页面可以再按
category分组,见 导航与分类
启用国际化后,默认语言的内容保持在 content/docs/,其他语言放在 content/{locale}/docs/,见 国际化。
首页 content/index.md
站点根路径 / 由 content/index.md 渲染,可以使用任意 MDC 组件。如果更想用 Vue 写首页,创建 app/pages/index.vue,Layer 将不再注册内置首页。
版本发布与案例
Layer 在构建期检测以下文件,存在时自动注册对应路由:
| 文件 | 路由 | 用途 |
|---|---|---|
content/releases.yml 或 releases.md | /releases | 从 GitHub Releases 生成的版本发布时间线 |
content/templates.yml 或 templates.md | /templates | 案例展示卡片 |
两者的字段格式见 页面与布局。
公共资源 public/
文件按根路径直接提供,例如 public/logo.svg 对应 /logo.svg。案例页的截图按约定放在 public/assets/templates/。
nuxt.config.ts 与 app.config.ts
两份配置文件各管一层:
nuxt.config.ts | app/app.config.ts | |
|---|---|---|
| 生效时机 | 构建期 | 运行时 |
| 典型内容 | 功能开关 movkNuxtDocs.*、aiChat.model、mcp、llms、i18n、site.url | 页头导航、侧栏分类、页脚、主题、SEO 默认值、GitHub 仓库 |
| 参考 | nuxt.config 选项 | app.config 参考 |
一个典型的组合:
export default defineNuxtConfig({
extends: ['@movk/nuxt-docs'],
site: {
url: 'https://docs.example.com',
name: 'My Docs'
},
movkNuxtDocs: {
mermaid: true
}
})
export default defineAppConfig({
header: {
title: 'My Docs',
nav: [
{ label: '文档', to: '/docs/getting-started', activeMatch: '/docs' }
]
},
github: {
owner: 'my-org',
name: 'my-docs'
}
})
app.config.ts 不是必需的,未配置的字段都有默认值。两者的分工与常用写法见 配置总览。
覆盖组件与 composable
在 app/components/ 中创建与 Layer 同名的组件即可替换默认实现,例如 app/components/HeaderLogo.vue。可覆盖的组件与挂载位置以 自定义 页的覆盖契约表为准。