贡献指南

注意

文档网站积极修改建设中，项目结构和贡献指南可能会发生变化。

提示

欢迎贡献！

由于课程信息具有时效性，仅凭一个人的视角无法跨越时空，也难以涵盖细节，因此我们欢迎贡献。

课程补充和更新、错误修正、攻略心得分享或者其他专业的课程都会受到欢迎！

项目构建

本项目使用 Docusaurus v3 构建静态文档网站。

前置要求

Node.js 版本 >= 18（推荐使用 LTS 版本）
npm（推荐）或 yarn

本地开发与运行

克隆仓库：

git clone https://github.com/rurumuri/ysuse-2022.git
cd ysuse-2022

安装依赖：
```
npm install
```
构建和启动：
```
npm run start
```
开发服务器默认运行在 http://localhost:3000。任何对 Markdown 文件、配置或组件的修改都会触发热重载，浏览器会自动刷新。

如果需要指定端口：
```
npm run start -- --port 8080
```

贡献方法

提出 Issue
fork 仓库，提交 PR (pull request)

文件路径和命名

仓库主要分为两个主要部分，一部分是 docs/[课程类别]/ 下的课程文档，另一部分是 static/course/ 下的课程资料文件夹。

docs/ 下的目录说明：

misc/: 杂项（比如实训基地生存攻略、选课技巧等）
practical/: 集中实践课（课程设计、企业实训等会包含在这里）
subject-compulsory/: 专业必选课
subject-elective/: 专业选修课

/static/course/ 下的课程资料目录说明：

README.md: 课程资料文件相关的说明
ebook/: 电子版教材
slide/: 电子版课件
lab/: 实验指导书、实验代码、实验报告模板、实验报告成果等
hw/: 平时作业题目、笔记模板、作业成果等
proj/: 项目指导书、项目实现代码、项目（讨论课）报告模板、项目（讨论课）报告成果等

其他内容也可以新建文件夹归类存放（比如头歌在线教学平台中的作业），并在 README.md 中说明。

对于过时的内容，可以考虑直接替换，也可以命名标注年份或建立子文件夹进行区分。

课程文档

课程文档结构大致如下：

---
slug: /[课程编码]
---

# [课程编码]-[中文课程名]

// 课程概述

## 课程信息

### 学期

### 学分 & 学时

### 教材

### 考核方式

## 参考资料

课程命名规范为 [课程编码]-[中文课程名]，课程编码可以从课程教学大纲、培养方案或教务系统成绩查询处获得。课程文档的文件名和文件中的一级标题应遵守此规范。

课程信息 部分的内容应反映课程的基本情况，至少包含课程简介、开课学期、学分和学时、使用教材等信息，这部分内容应简洁客观。

信息

课程概述 应是置于文档一级标题后紧邻的正文，从而使 Sidebar items 卡片能默认自动获取这部分作为文档的预览描述部分。

参考资料 部分应至少包含对应的链接指向 GitHub 仓库中的课程资料目录。

课程评价、攻略和经验分享

相对简短的内容可以直接穿插在课程文档中。对于个人评价等可能主观的内容和其他说明性内容，建议使用 Admonitions 进行标注和提示。

示例

主观评价

此部分内容相对主观，请自行辨别。

课程简评

...

对于以下情况：

内容篇幅较长
内容通用，不局限于单个课程

可以考虑在 docs/misc/ 下单独的文档中编写，并在相关课程中引用。

文件上传注意事项

请注意保护个人隐私，上传内容不要误包含姓名、学号等个人信息。

本仓库已启用 git-lfs，符合 .gitattributes 中配置的文件会以 LFS 方式存储。请避免上传大尺寸二进制文件，上传项目代码时请注意清理构建产物。

下列内容为不适合上传的内容。如果你认为缺少这些资料将会影响资源的完整性，请优先考虑放在其他资源平台。建议通过 README.md 文档放置一些链接或指引文字来帮助找到这些资源。

盗版电子书/付费电子书
盗版/破解版/绿色版付费软件及其安装包
课程/教师主页上列出的内容（请在获得教师许可后上传）

如果你认为本仓库的一些文件侵犯了您的权益，请留下issue，我们将会从仓库中彻底清除这些文件。

以上方法摘录，修改自西工大计算机专业课程攻略

项目构建​

前置要求​

本地开发与运行​

贡献方法​

文件路径和命名​

课程文档​

课程评价、攻略和经验分享​

文件上传注意事项​