10 KiB
贡献指南
感谢您的贡献，并感谢您在执行贡献操作之前阅读此文档！
致新贡献者
欢迎你的到来，非常感谢你愿意一起建设 HDU-CS-WIKI 💖。
初次参与，你遇到任何问题都可以直接反馈到本仓库，包括但不限于：
- 开发环境搭建时遇到任何问题。
- 文档遇到任何问题（笔误，格式，错误等）。
如果你在运行项目的时候发现任何不符合预期或不合理的地方，请直接提交 Issue 反馈和 Bug 报告！
如何贡献
我们欢迎各种贡献，包括但不限于：
- 新功能（Feature）
- 代码构建、CI/CD
- Bug 修复
- 文档内容增删改
- Issue 分类、发起、回复、管理、维护
- 网站页面设计
- 在各种媒体、博客文章、群内宣传 HDU-CS-WIKI
文档命名
-
对于 md 文件，请命名为
数字与小数点前缀+文档标题的格式1.1.2 新内容.md 2. 序言.md -
如果您需要开启新的小章节模块，请新建一个文件夹，文件夹的命名格式与 md 文件类似，为
数字与小数点前缀+模块名2.2 模块 2 -
不论是 md 文件还是文件夹,请不要使用字母或其他特殊符号作为前缀
一个合理的文档结构如下：
.
└─ 1.第一章
├── 1.1 模块 1
│ ├── 1.1.10 JavaScript.md
│ ├── 1.1.11 Lua.md
│ ├── 1.1.12 Lisp.md
│ ├── 1.1.1 Ruby.md
│ ├── 1.1.2 Java.md
│ ├── 1.1.3 C++.md
│ ├── 1.1.4 C.md
│ ├── 1.1.5 Math.md
│ ├── 1.1.6 Matlab.md
│ ├── 1.1.7 React.md
│ ├── 1.1.8 Jupyter.md
│ └── 1.1.9 Vue.md
├── 1.2 模块 2
│ ├── 1.2.1 C#.md
│ ├── 1.2.2 Python.md
│ └── static
├── 1.3 结语.md
├── 1. 序言.md
└── static
static 文件夹用于存放您的静态资源，如图片，您也可以在模块文件夹下放置新的 static 文件夹，方便引用资源
文档风格
-
使用 Markdown 编写文档，文档格式参考 Markdown 语法。
-
一个页面必须且只有一个 1 级标题（H1，一个#），其他标题从 2 级开始（H2，##）。
-
本项目自动在英文与中文、数字与中文之间添加空格。
AI 与人工智能，AGI 的发展方向。 -
标题内的英文单词首字母大写。
-
代码块使用
```包裹，并标注常见的语言标识符，如```python，其作用是使代码正常高亮。 ::: details 代码高亮支持的语言
export type Lang =
| "abap"
| "actionscript-3"
| "ada"
| "apache"
| "apex"
| "apl"
| "applescript"
| "ara"
| "asm"
| "astro"
| "awk"
| "ballerina"
| "bat"
| "batch"
| "beancount"
| "berry"
| "be"
| "bibtex"
| "bicep"
| "blade"
| "c"
| "cadence"
| "cdc"
| "clarity"
| "clojure"
| "clj"
| "cmake"
| "cobol"
| "codeql"
| "ql"
| "coffee"
| "cpp"
| "crystal"
| "csharp"
| "c#"
| "cs"
| "css"
| "cue"
| "cypher"
| "cql"
| "d"
| "dart"
| "dax"
| "diff"
| "docker"
| "dockerfile"
| "dream-maker"
| "elixir"
| "elm"
| "erb"
| "erlang"
| "erl"
| "fish"
| "fsharp"
| "f#"
| "fs"
| "gdresource"
| "gdscript"
| "gdshader"
| "gherkin"
| "git-commit"
| "git-rebase"
| "glimmer-js"
| "gjs"
| "glimmer-ts"
| "gts"
| "glsl"
| "gnuplot"
| "go"
| "graphql"
| "groovy"
| "hack"
| "haml"
| "handlebars"
| "hbs"
| "haskell"
| "hs"
| "hcl"
| "hjson"
| "hlsl"
| "html"
| "http"
| "imba"
| "ini"
| "properties"
| "java"
| "javascript"
| "js"
| "jinja-html"
| "jison"
| "json"
| "json5"
| "jsonc"
| "jsonl"
| "jsonnet"
| "jssm"
| "fsl"
| "jsx"
| "julia"
| "kotlin"
| "kusto"
| "kql"
| "latex"
| "less"
| "liquid"
| "lisp"
| "logo"
| "lua"
| "make"
| "makefile"
| "markdown"
| "md"
| "marko"
| "matlab"
| "mdx"
| "mermaid"
| "mojo"
| "narrat"
| "nar"
| "nextflow"
| "nf"
| "nginx"
| "nim"
| "nix"
| "objective-c"
| "objc"
| "objective-cpp"
| "ocaml"
| "pascal"
| "perl"
| "php"
| "plsql"
| "postcss"
| "powerquery"
| "powershell"
| "ps"
| "ps1"
| "prisma"
| "prolog"
| "proto"
| "pug"
| "jade"
| "puppet"
| "purescript"
| "python"
| "py"
| "r"
| "raku"
| "perl6"
| "razor"
| "reg"
| "rel"
| "riscv"
| "rst"
| "ruby"
| "rb"
| "rust"
| "rs"
| "sas"
| "sass"
| "scala"
| "scheme"
| "scss"
| "shaderlab"
| "shader"
| "shellscript"
| "bash"
| "sh"
| "shell"
| "zsh"
| "shellsession"
| "console"
| "smalltalk"
| "solidity"
| "sparql"
| "splunk"
| "spl"
| "sql"
| "ssh-config"
| "stata"
| "stylus"
| "styl"
| "svelte"
| "swift"
| "system-verilog"
| "tasl"
| "tcl"
| "tex"
| "toml"
| "tsx"
| "turtle"
| "twig"
| "typescript"
| "ts"
| "v"
| "vb"
| "cmd"
| "verilog"
| "vhdl"
| "viml"
| "vim"
| "vimscript"
| "vue-html"
| "vue"
| "vyper"
| "vy"
| "wasm"
| "wenyan"
| "文言"
| "wgsl"
| "wolfram"
| "xml"
| "xsl"
| "yaml"
| "yml"
| "zenscript"
| "zig";
:::
::: tip 🤓 注意
尽量不要使用 typora 等编辑器编辑完 .md 文件后直接提交，因为它的渲染效果和本项目前端 md 渲染器 vitepress markdown-it 不一致。
在 typora 中编辑完成后，确认一下 .md 文件源代码是否为正常 Markdown 。
编辑完成后请务必启动本项目在前端查看效果。 :::
项目构建指南
vitepress 框架要求，强制需要 nodejs v18.0 及以上版本。
本项目使用包管理器 npm。
npm install
npm run docs:dev #运行预览环境
npm run docs:build #编译线上环境
npm run docs:preview #预览线上环境
图片放置指南
图片放置在当前大章节 或者 模块章节的 static 目录下，然后在 md 文件中使用相对路径引用。
注意尽量不要使用 img 这个 HTML 标签，因为经前端构建解析后路径会不正确。
后续会统一放置到 cos 存储桶中。
项目配置指南
::: warning 🚧 注意
如果改了文件路径却没有配置 .vitepress/config.js、.vitepress/sidebar.js 文件会导致项目构建失败。
:::
修改新添加或移动位置的 md 文件需要在 .vitepress/config.js、.vitepress/sidebar.js 中添加或修改对应的配置。
sidebar.js 文件会管理显示在左侧导航栏的所有路由
如何使用 Git 和 Github
Commit Message 规范
::: tip 🐒 本项目没有强制使用 commitlint ，但是建议遵循以下规范。
commitlint : 一个提交检查插件 ，可以在提交前检查 commit message 是否符合规范。
本项目选用的规范为 @commitlint/config-conventional（基于 Angular 约定） :::
本项目遵循以下 commit message 规范：
模板：
type(scope): subject
type为commit的类型
feat: 新特性
fix: 修改问题
refactor: 代码重构
docs: 文档修改
style: 代码格式修改
test: 测试用例修改
chore: 其他修改, 比如构建流程, 依赖管理
perf: 性能提升的修改
build: 对项目构建或者依赖的改动
ci: CI 的修改
revert: revert 前一个 commit(撤销前一个commit)
scope是文件名 / 模块名 / 影响的范围
例如 schoolSchedule
subject为commit概述
建议符合 50 / 72 formatting
例 feat(JoinForm): add success submit tips
冒号后方可以使用中文描述
注意 冒号和subject之间要加空格
其中详细内容可以参照 约定式提交
本项目额外有使用 semantic-release 自动化版本发布，所以请务必遵循规范提交。
注意：fix、feat、BREAKING CHANGE 这三种类型的提交会触发自动版本发布。
Pull Request 流程与指南
Fork 本仓库，然后在你的仓库中进行修改，修改完成后在本仓库创建 NEW Pull Request ，选择 compare across forks 提交 pr 并评论上你修改的具体信息即可，我们会第一时间审阅并合并。
Feature
-
Markdown 内支持 Latex 公式，格式为单行公式双 dollar 符号、单行公式单 dollar 符号。（单行公式需要换行才能解析）例如：
$行内公式\arccos{a}$会渲染成
\arccos{a}$$单行公式\arcsin{b}$$会渲染成
\arcsin{b}::: tip Latex 语法在线编辑器 https://www.latexlive.com :::
-
支持 Mermaid 流程图，格式如下
```mermaid graph TD; A-->B; A-->C; B-->D; C-->D; ```会渲染成
graph TD; A-->B; A-->C; B-->D; C-->D;:::tip 语法自查 https://mermaid.js.org :::
-
代码分块
::: code-group ```sh [npm] $ npm install -D vitepress ``` ```sh [pnpm] $ pnpm add -D vitepress ``` ```sh [yarn] $ yarn add -D vitepress ``` :::::: code-group
$ npm install -D vitepress$ pnpm add -D vitepress$ yarn add -D vitepress:::
-
图片缩放
图片默认支持缩放，鼠标悬浮图片上方会出现放大镜图标，点击即可放大图片。
如果不想让图片缩放，可以在图片 class 内后添加 no-zoom 参数。
markdown 的使用方式如下
# 默认（支持缩放）
# 不支持缩放
{.no-zoom}