ContiNew

切换日光/暗黑模式

AGENTS.md ​

最后更新: 7 小时前

ContiNew 官方文档站（https://continew.top）：基于 VitePress 2.0 构建的中文学术风格文档与博客站点，承载 ContiNew Admin（后台管理框架）与 ContiNew Starter（基础组件库）两个子项目的文档、博客文章、吐槽广场（Issue Hub）与赞助展示。

仓库布局 ​

docs/admin/      ContiNew Admin 文档（指南、后端/前端/功能手册、更新日志、FAQ、开发计划、吐槽广场）
docs/starter/    ContiNew Starter 文档（指南、模块手册、更新日志）
posts/           官方博客，按年份子目录组织（posts/<year>/*.md），图片置于 posts/<year>/images/<slug>/
about/           关于
ecosystem/       生态导航
sponsor/         赞助
index.md         首页
.vitepress/      构建配置与自定义主题
  config.mts     VitePress 主配置入口（标题、head、Vite 插件、themeConfig、sitemap）
  configs/       拆分配置：nav.ts（顶部导航）、sidebar.ts（侧边栏，按 URL 前缀分组）、head.ts（百度统计+内联脚本）、markdown/（Shiki 主题+自定义 md 插件）、search/（本地搜索）、constants.ts（站点元数据）
  theme/         自定义主题：index.ts（入口，扩展默认主题+注册全局组件）、components/（页面级组件）、post/（博客数据与视图）、styles/（主题样式）
src/             通用 UI 组件库（VT* 前缀，参照 VitePress 官方主题组件风格）与基础样式（src/styles/），经 src/index.ts 统一导出
public/          静态资源（logo、图标 SVG、二维码、赞助图等）
.agents/skills/  Agent skills 唯一事实源（.claude/skills 符号链接指向这里）
deploy.sh        一键部署脚本

常用命令 ​

sh
pnpm dev        # 启动开发服务器（VitePress，端口固定 strictPort）
pnpm build      # 构建生产站点到 .vitepress/dist/
pnpm preview    # 本地预览构建产物
bash deploy.sh  # 一键部署：本地构建 → SSH 传输到远端 Nginx 目录（/root/continew/nginx/html/doc）→ 清理本地产物

deploy.sh 通过环境变量 REMOTE_USER/REMOTE_HOST 覆盖目标主机；首次运行会引导配置 SSH 密钥。构建产物为纯静态站点，部署会彻底清理远端目录后重新传输，确保不残留废弃文件；站点配置了 sitemap（hostname: https://continew.top/）与百度统计。

架构 ​

主题与布局机制 ​

theme/index.ts 通过 Layout 插槽扩展默认主题，注入的插槽：

  • layout-top → Banner.vue
  • sidebar-nav-before → SidebarTop.vue（赞助占位）
  • aside-outline-after → SponsorsAside.vue
  • aside-ads-before → WwAds.vue
  • layout-bottom → Footer.vue

enhanceApp 全局注册 Badge、VTLink、DocMeta、PostMeta、IssueHubPage、PlanBoardBanner（开发计划页跳转 AtomGit 看板的横幅，props：boardUrl/repo）、PlanRoadmap（开发计划页的升级路线垂直时间轴，数据在组件内维护）组件；Arco Design Vue（@arco-design/web-vue）为按需引入（仅注册实际使用的 Modal/Image/ImagePreviewGroup/Space 与 3 个图标，样式走各组件 style/css.js 链，config.mts 中 vite.ssr.noExternal 强制其走 Vite 模块图）——新增 Arco 组件使用时需同步在 theme/index.ts 注册并补样式导入。

Markdown 扩展 ​

configs/markdown/docMetaMdPlugin.ts 是核心 md 插件：在每个 </h1> 后自动注入元信息组件 —— 路径包含 posts/ 的注入 <PostMeta />（显示作者、发布时间、分类、转载标记），其余注入 <DocMeta />（显示最后更新时间、实践版本、版本时效提示）。文档/文章页面无需手动添加元信息组件。

其他 Vite 插件：

  • vitepress-plugin-group-icons — 代码组图标（支持 java/xml/sql/conf/sh/bat 及 atomgit/gitee/github 本地图标）
  • vitepress-plugin-image-preview — 图片点击预览

自定义 themeConfig 扩展 ​

config.mts 的 themeConfig 包含非标准扩展字段（需 @ts-ignore）：

  • version — Admin 与 Starter 的版本信息（当前 Admin release 4.1.0/tags 26，Starter release 2.16.0/tags 47），用于 DocMeta 版本时效判断；新版本发布后由 docs-sync skill 更新
  • docMetaConfig — 文档元信息配置（enabled、tipTime 提示天数阈值、ads）
  • footerConfig — 页脚配置（ICP 备案、公安备案、版权信息）

吐槽广场（Issue Hub） ​

theme/components/issue-hub/ 实现基于三平台（AtomGit → GitHub → Gitee）数据的 Issue 聚合页面：scripts/fetch-issues.mjs 在构建期拉取各平台开放 API（仓库：continew-admin、continew-admin-ui、continew-starter；owner 分别为 continew/continew-org/continew；GitHub 需过滤 PR）并生成 public/data/issues.json，前端运行时 fetch 加载（不打包进 bundle，仅吐槽广场页产生一次请求）。admin 页面按仓库前缀合并 admin-ui 的 Issue（对齐原后端 LIKE 'continew-admin%' 语义）；GitHub/Gitee/AtomGit 可选通过 GITHUB_TOKEN/GITEE_TOKEN/ATOMGIT_TOKEN 环境变量提升限流。数据新鲜度：构建部署时随站点更新；服务器 cron（每日北京 06:30）直接调服务器上的同款脚本经 ISSUES_OUTPUT_PATH 重写 Nginx 目录下的单文件，无需重建站点（脚本由 deploy.sh 每次部署同步）。页面支持按标签（feature/bug/question/wontfix/invalid/duplicate）筛选、关键词搜索（标题+正文）、分页、Top3 吐槽用户排行（排除 Charles7c）；状态（标签、页码、搜索词）同步到 URL 查询参数，支持浏览器前进后退。通过 <IssueHubPage repo="continew-admin" /> 或 <IssueHubPage repo="continew-starter" /> 在 Markdown 中使用。

约定 ​

博客文章 frontmatter ​

  • title、author、datetime（格式如 2025-11-17 22:00）— 必填
  • category — 分类
  • top: true + order — 置顶及置顶排序
  • original: false + originalLink + authorLink — 转载文章标记（默认 original 为 true）
  • description — 摘要（未提供时自动从正文清洗生成，参见 removeMdPro.ts）
  • version — 文档对应的实践版本号（用于版本时效提示）
  • lastUpdated: false — 关闭最后更新时间显示

文章列表由 posts.data.ts 通过 createContentLoader 在构建时生成，按 datetime 倒序排列，置顶文章按 order 排在前。

开发要点 ​

  • 修改导航/侧边栏：编辑 .vitepress/configs/nav.ts 与 sidebar.ts，注意 activeMatch 正则要精确匹配 URL 前缀
  • 新增博客文章：在 posts/<year>/ 下创建 .md，按约定填写 frontmatter，图片放 posts/<year>/images/<slug>/
  • 新增文档页面：在 docs/admin/ 或 docs/starter/ 下创建，并在对应 sidebar.ts 分组中登记链接
  • 样式变量：主题色通过 src/styles/variables.css 与 theme/styles/ 中的 CSS 变量定义，组件使用 var(--vt-c-*) / var(--vp-c-*) 系列
  • 代码中访问运行时环境用 inBrowser（来自 vitepress）判断，避免 SSR 阶段访问 window
  • posts.data.ts 使用 createContentLoader 在构建时生成数据，修改后需重启 dev server 生效

编辑这些指令 ​

.claude/skills 是指向 .agents/skills 的符号链接；只编辑真实文件，不要改动链接本身。保持每条规则自洽完整；能精简时精简。

最后更新: