项目结构

说明使用 Movk Nuxt Docs 的项目中各目录与文件的职责:内容放在哪里、路由如何生成、哪些文件会被自动识别为版本发布页与案例页,以及两份配置文件分别管什么。
查看源码

目录概览

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

app.config.ts 不是必需的,未配置的字段都有默认值。两者的分工与常用写法见 配置总览。

覆盖组件与 composable

在 app/components/ 中创建与 Layer 同名的组件即可替换默认实现,例如 app/components/HeaderLogo.vue。可覆盖的组件与挂载位置以 自定义 页的覆盖契约表为准。

Copyright © 2024 - 2026