贡献指南
感谢您的贡献,并感谢您在执行贡献操作之前阅读此文档!
致新贡献者
欢迎你的到来,非常感谢你愿意一起建设 HDU-CS-WIKI 💖。
初次参与,你遇到任何问题都可以直接反馈到本仓库,包括但不限于:
- 开发环境搭建时遇到任何问题。
- 文档遇到任何问题(笔误,格式,错误等)。
如果你在运行项目的时候发现任何不符合预期或不合理的地方,请直接提交 Issue 反馈和 Bug 报告!
如何贡献
我们欢迎各种贡献,包括但不限于:
- 新功能(Feature)
- 代码构建、CI/CD
- Bug 修复
- 文档内容增删改
- Issue 分类、发起、回复、管理、维护
- 网站页面设计
- 在各种媒体、博客文章、群内宣传 HDU-CS-WIKI
文档命名
对于 md 文件,请命名为
数字与小数点前缀+文档标题
的格式1.1.2 新内容.md 2. 序言.md
1
2如果您需要开启新的小章节模块,请新建一个文件夹,文件夹的命名格式与 md 文件类似,为
数字与小数点前缀+模块名
2.2 模块 2
1不论是 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
static 文件夹用于存放您的静态资源,如图片,您也可以在模块文件夹下放置新的 static 文件夹,方便引用资源
文档风格
使用 Markdown 编写文档,文档格式参考 Markdown 语法。
一个页面必须且只有一个 1 级标题(H1,一个 #),其他标题从 2 级开始(H2,##)。
本项目自动在英文与中文、数字与中文之间添加空格。
markdownAI 与人工智能,AGI 的发展方向。
1标题内的英文单词首字母大写。
代码块使用
```
包裹,并标注常见的语言标识符,如```python
,其作用是使代码正常高亮。
代码高亮支持的语言
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'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
🤓 注意
尽量不要使用 typora
等编辑器编辑完 .md
文件后直接提交,因为它的渲染效果和本项目前端 md 渲染器 markdown-it
不一致。
在 typora
中编辑完成后,确认一下 .md 文件源代码是否为正常 Markdown 。
编辑完成后请务必启动本项目在前端查看效果,关于如何启动,请看下文。
项目构建指南
需要 nodejs v22 及以上版本。
具体版本可以打开仓库根目录下的 .node-version
文件查看。
如果你安装有 node 版本管理工具,那么它会自动切换到对应的版本。
本项目使用 bun。
如果你没有安装 bun,可以使用以下命令安装:
npm install -g bun
或者参考 bun 官网文档进行安装。
bun i #安装依赖
bun run docs:dev #运行预览环境
2
bun run docs:build #编译线上环境
bun run docs:preview #预览线上环境
2
图片放置指南
图片放置在当前大章节的 static
目录下,然后在 md 文件中使用相对路径引用。

注意尽量不要使用 img
这个 HTML 标签,因为经前端构建解析后路径会不正确。
后续会统一放置到 cos 存储桶中。
项目配置指南
🚧 注意
文件名中禁止英文添加特殊符号,如 +
、 &
、 #
等符号,会导致构建失败。
如何使用 Git 和 Github
Commit Message 规范
🐒
本项目没有强制使用 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之间要加空格
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
其中详细内容可以参照 约定式提交
本项目额外有使用 semantic-release 自动化版本发布,所以请务必遵循规范提交。
⚠️
注意:fix、feat、BREAKING CHANGE 这三种类型的提交会触发自动版本发布。
Pull Request 流程与指南
Fork 本仓库,然后在你的仓库中进行修改,修改完成后在本仓库创建 NEW Pull Request ,选择 compare across forks 提交 pr 并评论上你修改的具体信息即可,我们会第一时间审阅并合并。
Feature
Markdown 内支持 Latex 公式,格式为单行公式双 dollar 符号、单行公式单 dollar 符号。(单行公式需要换行才能解析)例如:
latex$行内公式\arccos{a}$
1会渲染成
latex$$单行公式\arcsin{b}$$
1会渲染成
TIP
Latex 语法在线编辑器 https://www.latexlive.com
支持 Mermaid 流程图,格式如下
markdown```mermaid graph TD; A-->B; A-->C; B-->D; C-->D; ```
1
2
3
4
5
6
7会渲染成
TIP
代码分块
::: code-group ```sh [npm] $ npm install -D vitepress ``` ```sh [pnpm] $ pnpm add -D vitepress ``` ```sh [yarn] $ yarn add -D vitepress ``` :::
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15sh$ npm install -D vitepress
1sh$ pnpm add -D vitepress
1sh$ yarn add -D vitepress
1图片缩放
图片默认支持缩放,鼠标悬浮图片上方会出现放大镜图标,点击即可放大图片。
如果不想让图片缩放,可以在图片 class 内后添加 no-zoom
参数。
markdown 的使用方式如下
# 默认(支持缩放)

2
# 不支持缩放
{.no-zoom}
2