配置

hello 的用户侧配置只有一份 vdoc.config.ts。除 title 外全部可选，只写与默认值的差异。

接入三步

npm i -D @hello/vdoc

pnpm add -D @hello/vdoc

yarn add -D @hello/vdoc

在项目根新建 docs/ 放入 Markdown，再新建 vdoc.config.ts：

import { defineConfig } from '@hello/vdoc'

export default defineConfig({
  title: '我的文档',
  description: '一句话站点简介',
  nav: [
    { text: '首页', link: '/' },
    { text: '配置', link: '/post/配置' },
  ],
})

配置字段

title

站点标题，唯一必填项；缺失会直接报错终止构建

description

站点描述，默认空

keywords

站点关键词，默认空

siteUrl

站点绝对地址，默认空；留空时不产 sitemap，也不下发 canonical

ogImage

社交分享封面，默认 /og-cover.png，须为 png/jpg

ogImageAlt

封面替代文本，默认空

copyright

页脚版权文案，默认空

docsDir

内容目录，相对项目根，默认 docs

maxDepth

扫盘最大层级，默认 6

nav

顶栏导航 { text, link }[]，默认空

homeCards

首页分类卡片 { text, link, desc }[]，默认空（见下方注意）

repo

仓库外链 { url, branch, docsDir }；url 留空则文章页隐藏「编辑 / 历史」入口

docs/ 目录约定

• 目录层级 = 侧栏分组，同级按文件名自然序
• 文件名即文章标题（不写 frontmatter，全部编译期推导）
• 路由 = /post/<相对 docs/ 的路径去掉 .md>
• 项目根可放 home.md 覆盖首页正文，缺省用引擎内置模板

命令

• --config <path> 指定配置文件（相对项目根），默认探测 vdoc.config.ts
• --port <number> dev / preview 端口
• --base <path> 部署基础路径，默认 /
• --outDir <dir> build 产物目录，默认 dist
• -h, --help 显示帮助

vdoc <command> [root] 的 root 缺省为当前工作目录。

生成物与忽略

• 引擎中间产物写在 <项目根>/.vdoc/（缓存、配置快照、静态资源）
• 构建产物默认写在 <项目根>/dist/
• 两者都建议加入 .gitignore

.vdoc/
dist/

常见问题