Skip to content

development.mdx

Latest commit

 

History

History
211 lines (148 loc) · 4.96 KB

development.mdx

File metadata and controls

211 lines (148 loc) · 4.96 KB
Raw
title 本地开发
description 在本地编辑、预览和部署 NEC 文档站

import { insights } from "/snippets/page-insights-data.jsx"; import { PageInsights } from "/snippets/page-insights.jsx";

本页介绍如何在本地编辑、预览和提交 NEC 文档站的改动。

环境准备

确保已安装：

  • Node.js 18+：用于运行 Mintlify CLI
  • Python 3.10+：用于运行文档健康检查脚本
  • Git：用于提交和推送

安装 Mintlify CLI

npm install -g mintlify

验证安装：

mint --version

本地预览

在项目根目录（docs.json 所在目录）运行：

mint dev

本地服务器默认在 http://localhost:3000 启动，保存文件后会自动热更新。

如果端口 3000 被占用，Mintlify 会自动尝试 3001、3002 等后续端口。

环境变量与敏感配置

如果站点未来需要接入地图等第三方服务，请在本地创建 .env 文件：

cp .env.example .env

然后按实际情况填入真实 Key。参考模板已包含高德地图常用的三类变量：

  • VITE_AMAP_KEY：JSAPI Key，用于前端地图显示
  • VITE_AMAP_SECURITY_CODE：高德安全密钥
  • VITE_AMAP_WEBSERVICE_KEY：WebService Key，用于天气/搜索等后端 API
`.env` 文件已被 `.gitignore` 忽略，**请勿将真实 API Key 直接写入仓库**。 如需在 CI/部署环境使用，请在对应平台的 Secrets 管理器中配置。

项目结构

当前文档站结构如下：

docs/
├── index.mdx                 # 站点首页
├── docs.json                 # Mintlify 站点配置与导航
├── style.css                 # 自定义主题样式
├── robots.txt                # 搜索引擎与 AI 爬虫指引
├── llms.txt                  # LLM 索引文件
├── AGENTS.md                 # 给 AI Agent 的项目说明
├── images/                   # 图片资源
│   ├── NEC-home.gif
│   ├── qq-group-qrcode.jpg
│   ├── feishu-curc-collection.png
│   └── ...
├── start-here/               # 新手上路（含 learn/ 下的角色与标签说明）
├── modules/                  # 项目模块总览
├── mechanical/               # 机械设计专题
├── vision/                   # 机器视觉专题
├── embedded-software/        # 嵌入式软件专题
├── learn/                    # 学习资源（导航中并入「新手上路」）
├── templates/                # 文档模板
├── wiki/                     # Wiki 知识库
├── ai-tools/                 # AI 工具指南（独立顶部 Tab）
├── competition/              # 竞赛概览
├── curc26/                   # CURC 2026 赛季文档
├── community/                # 社区介绍与治理
├── contributing/             # 贡献指南
└── tools/ci/                 # CI 检查脚本
    └── check_docs.py

创建新页面

  1. 在合适目录创建 .mdx 文件
  2. 添加 YAML frontmatter：
---
title: "页面标题"
description: "页面描述"
---
  1. 在 docs.json 的 navigation 中注册页面
  2. 运行 python tools/ci/check_docs.py 确认无错误
空菜单不要上线：新增导航项前，请确认目标页面已有实质内容，并且 frontmatter 完整。

图片与静态资源

  • 图片统一放入 images/ 目录
  • 引用时使用以 /images/ 开头的绝对路径：
<img src="/images/NEC-home.gif" alt="示例图片" width="400" />
  • 二维码、截图等建议压缩后再提交，避免仓库体积膨胀

常用组件

卡片

<Card title="标题" icon="icon-name">
  内容描述
</Card>

卡片组

<CardGroup cols={2}>
  <Card title="卡片1">内容1</Card>
  <Card title="卡片2">内容2</Card>
</CardGroup>

步骤

<Steps>
  <Step title="步骤1">说明1</Step>
  <Step title="步骤2">说明2</Step>
</Steps>

更多组件请参考 Mintlify 组件文档。

提交前检查

在提交 PR 或推送前，请先运行 CI 健康检查脚本：

python tools/ci/check_docs.py

脚本会自动检查：

  • docs.json JSON 合法性与推荐字段
  • 导航页面文件存在性
  • .mdx 文件 frontmatter 完整
  • 内部链接可解析
  • 无 localhost 链接
  • 外部链接抽样可达性

部署

推送到 https://github.com/necc-hub/docs 的 main 分支后，Mintlify 会自动构建并部署到：

https://docs.newenergycoder.club/

无需手动连接 Gitee/GitHub 到 Mintlify，部署由 GitHub Actions 与 Mintlify 集成自动完成。

更多资源