ContiNew

切换日光/暗黑模式

AGENTS.md ​

最后更新: 1 分钟前

This file provides guidance to AI agents when working with code in this repository.

CLAUDE.md and AGENTS.md are mirror files. Whenever either file changes, apply the identical change to the other file and verify that their contents remain byte-for-byte identical（标题文件名除外）.

项目概述 ​

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

常用命令 ​

  • pnpm dev — 启动开发服务器（VitePress，端口固定 strictPort）
  • pnpm build — 构建生产站点到 .vitepress/dist/
  • pnpm preview — 本地预览构建产物
  • bash deploy.sh — 一键部署：本地构建 → SSH 传输到远端 Nginx 目录（/root/continew/nginx/html/doc）→ 清理本地产物。支持通过环境变量 REMOTE_USER/REMOTE_HOST 覆盖目标主机；首次运行会引导配置 SSH 密钥

架构 ​

目录布局 ​

项目根分为内容区与配置/主题区两大块：

  • 内容区（VitePress 直接消费的 Markdown）
    • docs/admin/ — ContiNew Admin 文档（指南、后端/前端/功能手册、更新日志、FAQ、开发计划、吐槽广场）
    • docs/starter/ — ContiNew Starter 文档（指南、模块手册、更新日志）
    • posts/ — 官方博客，按年份子目录组织（posts/2025/*.md），图片置于 posts/<year>/images/
    • about/、ecosystem/、sponsor/、index.md — 关于、生态导航、赞助、首页
  • .vitepress/ — 构建配置与自定义主题
    • config.mts — VitePress 主配置入口（标题、head、Vite 插件、themeConfig、sitemap）
    • configs/ — 拆分配置：nav.ts（顶部导航）、sidebar.ts（侧边栏，按 URL 前缀分组）、head.ts（含百度统计、内联脚本）、markdown/index.ts（Shiki 主题 + 自定义 md 插件）、search/local-search.ts（本地搜索）、constants.ts（站点元数据）
    • theme/index.ts — 自定义主题入口，扩展默认主题并注册全局组件（DocMeta、PostMeta、IssueHubPage、VTLink、Badge），集成 Arco Design Vue
    • theme/components/ — 页面级组件：Home.vue（首页 hero + 特性卡片 + 赞助）、Footer.vue、Banner.vue、DocMeta.vue（文档元信息 + 版本时效提示）、SiteMap.vue、issue-hub/（吐槽广场）、sponsor/（赞助模块）
    • theme/post/ — 博客相关：posts.data.ts（基于 createContentLoader 加载 posts/**/*.md 生成文章列表数据）、PageView.vue（文章列表分页视图）、PostMeta.vue（文章标题下方作者/时间/分类元信息）、removeMdPro.ts（Markdown 摘要清洗）、type.ts（Post 类型）
    • theme/styles/ — 主题样式
  • src/ — 通用 UI 组件库（VT* 前缀，如 VTLink、VTMenu、VTSwitchAppearance、VTCodeGroup 等，参照 VitePress 官方主题组件风格）与基础样式（src/styles/）。通过 src/index.ts 统一导出
  • public/ — 静态资源（logo、图标 SVG、二维码、赞助图等）

主题与布局机制 ​

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 组件，并启用 Arco Design Vue（@arco-design/web-vue）及其图标库。

Markdown 扩展 ​

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

博客文章约定 ​

文章 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 排在前。

吐槽广场（Issue Hub） ​

theme/components/issue-hub/ 实现了一个基于后端 API（https://api.charles7c.top/git/issue）的 Issue 聚合页面，支持按标签（feature/bug/question/wontfix/invalid/duplicate/smart）筛选、关键词搜索、分页、Top3 吐槽用户排行。状态（标签、页码、搜索词）会同步到 URL 查询参数，支持浏览器前进后退。通过 <IssueHubPage repo="continew-admin" /> 或 <IssueHubPage repo="continew-starter" /> 在 Markdown 中使用。

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（当前 release 4.1.0，tags 26）与 Starter（release 2.16.0，tags 47）的版本信息，用于 DocMeta 版本时效判断
  • docMetaConfig — 文档元信息配置（enabled、tipTime 提示天数阈值、ads）
  • footerConfig — 页脚配置（ICP 备案、公安备案、版权信息）

部署 ​

构建产物为纯静态站点，部署到远端 Nginx。deploy.sh 会彻底清理远端目录后重新传输，确保不残留废弃文件。站点配置了 sitemap（hostname: https://continew.top/）与百度统计。

开发要点 ​

  • 修改导航/侧边栏：编辑 .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 生效

最后更新: