moyin/fzu-product
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

Revert "docs: propose the code of document naming"

Browse Source 
This reverts commit 9bcce5aa29.
This commit is contained in:
kiameow
2024-07-29 22:48:44 +08:00
parent 9bcce5aa29
commit fb276b21cf
1 changed files with 240 additions and 344 deletions
Download Patch File Download Diff File Expand all files Collapse all files

584
CONTRIBUTING.md
View File

@@ -25,291 +25,198 @@
- 网站页面设计 - 网站页面设计
- 在各种媒体、博客文章、群内宣传 HDU-CS-WIKI - 在各种媒体、博客文章、群内宣传 HDU-CS-WIKI
## 文档命名
1. 对于 md 文件，请命名为 `数字与小数点前缀+文档标题` 的格式
```
1.1.2 新内容.md
2. 序言.md
```
2. 如果您需要开启新的小章节模块，请新建一个文件夹，文件夹的命名格式与 md 文件类似，为 `数字与小数点前缀+模块名`
```
2.2 模块 2
```
3. 不论是 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 文件夹，方便引用资源
## 文档风格 ## 文档风格
1. 使用 Markdown 编写文档，文档格式参考 Markdown 语法。 1. 使用 Markdown 编写文档，文档格式参考 Markdown 语法。
2. 一个页面必须且只有一个 1 级标题（H1，一个#），其他标题从 2 级开始（H2，##）。 2. 一个页面必须且只有一个1级标题（H1，一个#），其他标题从2级开始（H2，##）。
3. 本项目自动在英文与中文、数字与中文之间添加空格。 3. 本项目自动在英文与中文、数字与中文之间添加空格。
```markdown ```markdown
AI 与人工智能，AGI 的发展方向。 AI 与人工智能，AGI 的发展方向。
``` ```
4. 标题内的英文单词首字母大写。 4. 标题内的英文单词首字母大写。
5. 代码块使用 ` ``` ` 包裹，并标注常见的语言标识符，如 ` ```python ` ，其作用是使代码正常高亮。 5. 代码块使用 ` ``` ` 包裹，并标注常见的语言标识符，如 ` ```python ` ，其作用是使代码正常高亮。
::: details 代码高亮支持的语言 ::: details 代码高亮支持的语言
```ts twoslash ```ts twoslash
export type Lang = export type Lang =
| "abap" | 'abap'
| "actionscript-3" | 'actionscript-3'
| "ada" | 'ada'
| "apache" | 'apache'
| "apex" | 'apex'
| "apl" | 'apl'
| "applescript" | 'applescript'
| "ara" | 'ara'
| "asm" | 'asm'
| "astro" | 'astro'
| "awk" | 'awk'
| "ballerina" | 'ballerina'
| "bat" | 'bat' | 'batch'
| "batch" | 'beancount'
| "beancount" | 'berry' | 'be'
| "berry" | 'bibtex'
| "be" | 'bicep'
| "bibtex" | 'blade'
| "bicep" | 'c'
| "blade" | 'cadence' | 'cdc'
| "c" | 'clarity'
| "cadence" | 'clojure' | 'clj'
| "cdc" | 'cmake'
| "clarity" | 'cobol'
| "clojure" | 'codeql' | 'ql'
| "clj" | 'coffee'
| "cmake" | 'cpp'
| "cobol" | 'crystal'
| "codeql" | 'csharp' | 'c#' | 'cs'
| "ql" | 'css'
| "coffee" | 'cue'
| "cpp" | 'cypher' | 'cql'
| "crystal" | 'd'
| "csharp" | 'dart'
| "c#" | 'dax'
| "cs" | 'diff'
| "css" | 'docker' | 'dockerfile'
| "cue" | 'dream-maker'
| "cypher" | 'elixir'
| "cql" | 'elm'
| "d" | 'erb'
| "dart" | 'erlang' | 'erl'
| "dax" | 'fish'
| "diff" | 'fsharp' | 'f#' | 'fs'
| "docker" | 'gdresource'
| "dockerfile" | 'gdscript'
| "dream-maker" | 'gdshader'
| "elixir" | 'gherkin'
| "elm" | 'git-commit'
| "erb" | 'git-rebase'
| "erlang" | 'glimmer-js' | 'gjs'
| "erl" | 'glimmer-ts' | 'gts'
| "fish" | 'glsl'
| "fsharp" | 'gnuplot'
| "f#" | 'go'
| "fs" | 'graphql'
| "gdresource" | 'groovy'
| "gdscript" | 'hack'
| "gdshader" | 'haml'
| "gherkin" | 'handlebars' | 'hbs'
| "git-commit" | 'haskell' | 'hs'
| "git-rebase" | 'hcl'
| "glimmer-js" | 'hjson'
| "gjs" | 'hlsl'
| "glimmer-ts" | 'html'
| "gts" | 'http'
| "glsl" | 'imba'
| "gnuplot" | 'ini' | 'properties'
| "go" | 'java'
| "graphql" | 'javascript' | 'js'
| "groovy" | 'jinja-html'
| "hack" | 'jison'
| "haml" | 'json'
| "handlebars" | 'json5'
| "hbs" | 'jsonc'
| "haskell" | 'jsonl'
| "hs" | 'jsonnet'
| "hcl" | 'jssm' | 'fsl'
| "hjson" | 'jsx'
| "hlsl" | 'julia'
| "html" | 'kotlin'
| "http" | 'kusto' | 'kql'
| "imba" | 'latex'
| "ini" | 'less'
| "properties" | 'liquid'
| "java" | 'lisp'
| "javascript" | 'logo'
| "js" | 'lua'
| "jinja-html" | 'make' | 'makefile'
| "jison" | 'markdown' | 'md'
| "json" | 'marko'
| "json5" | 'matlab'
| "jsonc" | 'mdx'
| "jsonl" | 'mermaid'
| "jsonnet" | 'mojo'
| "jssm" | 'narrat' | 'nar'
| "fsl" | 'nextflow' | 'nf'
| "jsx" | 'nginx'
| "julia" | 'nim'
| "kotlin" | 'nix'
| "kusto" | 'objective-c' | 'objc'
| "kql" | 'objective-cpp'
| "latex" | 'ocaml'
| "less" | 'pascal'
| "liquid" | 'perl'
| "lisp" | 'php'
| "logo" | 'plsql'
| "lua" | 'postcss'
| "make" | 'powerquery'
| "makefile" | 'powershell' | 'ps' | 'ps1'
| "markdown" | 'prisma'
| "md" | 'prolog'
| "marko" | 'proto'
| "matlab" | 'pug' | 'jade'
| "mdx" | 'puppet'
| "mermaid" | 'purescript'
| "mojo" | 'python' | 'py'
| "narrat" | 'r'
| "nar" | 'raku' | 'perl6'
| "nextflow" | 'razor'
| "nf" | 'reg'
| "nginx" | 'rel'
| "nim" | 'riscv'
| "nix" | 'rst'
| "objective-c" | 'ruby' | 'rb'
| "objc" | 'rust' | 'rs'
| "objective-cpp" | 'sas'
| "ocaml" | 'sass'
| "pascal" | 'scala'
| "perl" | 'scheme'
| "php" | 'scss'
| "plsql" | 'shaderlab' | 'shader'
| "postcss" | 'shellscript' | 'bash' | 'sh' | 'shell' | 'zsh'
| "powerquery" | 'shellsession' | 'console'
| "powershell" | 'smalltalk'
| "ps" | 'solidity'
| "ps1" | 'sparql'
| "prisma" | 'splunk' | 'spl'
| "prolog" | 'sql'
| "proto" | 'ssh-config'
| "pug" | 'stata'
| "jade" | 'stylus' | 'styl'
| "puppet" | 'svelte'
| "purescript" | 'swift'
| "python" | 'system-verilog'
| "py" | 'tasl'
| "r" | 'tcl'
| "raku" | 'tex'
| "perl6" | 'toml'
| "razor" | 'tsx'
| "reg" | 'turtle'
| "rel" | 'twig'
| "riscv" | 'typescript' | 'ts'
| "rst" | 'v'
| "ruby" | 'vb' | 'cmd'
| "rb" | 'verilog'
| "rust" | 'vhdl'
| "rs" | 'viml' | 'vim' | 'vimscript'
| "sas" | 'vue-html'
| "sass" | 'vue'
| "scala" | 'vyper' | 'vy'
| "scheme" | 'wasm'
| "scss" | 'wenyan' | '文言'
| "shaderlab" | 'wgsl'
| "shader" | 'wolfram'
| "shellscript" | 'xml'
| "bash" | 'xsl'
| "sh" | 'yaml' | 'yml'
| "shell" | 'zenscript'
| "zsh" | 'zig'
| "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 🤓 注意 ::: tip 🤓 注意
尽量不要使用 `typora` 等编辑器编辑完 .md 文件后直接提交，因为它的渲染效果和本项目前端 md 渲染器 `vitepress markdown-it` 不一致。 尽量不要使用 `typora` 等编辑器编辑完 .md文件后直接提交，因为它的渲染效果和本项目前端 md 渲染器 `vitepress markdown-it` 不一致。
在 `typora` 中编辑完成后，确认一下 .md 文件源代码是否为正常 Markdown 。 在 `typora` 中编辑完成后，确认一下 .md 文件源代码是否为正常 Markdown 。
@@ -323,7 +230,7 @@ vitepress 框架要求，强制需要 nodejs v18.0 及以上版本。
本项目使用包管理器 npm。 本项目使用包管理器 npm。
```bash ```bash
npm install npm install
npm run docs:dev #运行预览环境 npm run docs:dev #运行预览环境
``` ```
@@ -334,7 +241,7 @@ npm run docs:preview #预览线上环境
## 图片放置指南 ## 图片放置指南
图片放置在当前大章节 或者 模块章节的 `static` 目录下，然后在 md 文件中使用相对路径引用。 图片放置在当前大章节的 `static` 目录下，然后在 md 文件中使用相对路径引用。
```markdown ```markdown
![](static/xxx.png) ![](static/xxx.png)
@@ -358,13 +265,12 @@ npm run docs:preview #预览线上环境
## 如何使用 Git 和 Github ## 如何使用 Git 和 Github
详见 [3.5 Git 和 Github](./2023旧版内容/3.编程思维体系构建/3.5git与github.md) 详见 [3.5 Git和Github](./2023旧版内容/3.编程思维体系构建/3.5git与github.md)
## Commit Message 规范 ## Commit Message 规范
::: tip 🐒 ::: tip 🐒
本项目没有强制使用 [commitlint](https://github.com/conventional-changelog/commitlint) ，但是建议遵循以下规范。 本项目没有强制使用 [commitlint](https://github.com/conventional-changelog/commitlint) ，但是建议遵循以下规范。
> commitlint : 一个提交检查插件 ，可以在提交前检查 commit message 是否符合规范。 > commitlint : 一个提交检查插件 ，可以在提交前检查 commit message 是否符合规范。
本项目选用的规范为 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)（基于 [Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) 约定） 本项目选用的规范为 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)（基于 [Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) 约定）
@@ -388,13 +294,13 @@ type为commit的类型
build: 对项目构建或者依赖的改动 build: 对项目构建或者依赖的改动
ci: CI 的修改 ci: CI 的修改
revert: revert 前一个 commit(撤销前一个commit) revert: revert 前一个 commit(撤销前一个commit)
scope是文件名 / 模块名 / 影响的范围 scope是文件名 / 模块名 / 影响的范围
例如 schoolSchedule 例如 schoolSchedule
subject为commit概述 subject为commit概述
建议符合 50 / 72 formatting 建议符合 50 / 72 formatting
例 feat(JoinForm): add success submit tips 例 feat(JoinForm): add success submit tips
冒号后方可以使用中文描述 冒号后方可以使用中文描述
@@ -416,103 +322,93 @@ Fork 本仓库，然后在你的仓库中进行修改，修改完成后在本仓
## Feature ## Feature
1. Markdown 内支持 Latex 公式，格式为单行公式双 dollar 符号、单行公式单 dollar 符号。（单行公式需要换行才能解析）例如： 1. Markdown 内支持Latex公式，格式为单行公式双dollar符号、单行公式单dollar符号。（单行公式需要换行才能解析）例如：
```latex
$行内公式\arccos{a}$
```
> 会渲染成 $\arccos{a}$
```latex
$$单行公式\arcsin{b}$$
```
> 会渲染成
>
> $$\arcsin{b}$$
::: tip
Latex语法在线编辑器 https://www.latexlive.com
:::
```latex 2. 支持Mermaid流程图，格式如下
$行内公式\arccos{a}$ ```markdown
``` ```mermaid
graph TD;
> 会渲染成 $\arccos{a}$ A-->B;
A-->C;
```latex B-->D;
$$单行公式\arcsin{b}$$ C-->D;
``` ```
```
> 会渲染成 会渲染成
> ```mermaid
> $$\arcsin{b}$$ graph TD;
> ::: tip A-->B;
> Latex 语法在线编辑器 https://www.latexlive.com A-->C;
> ::: B-->D;
C-->D;
2. 支持 Mermaid 流程图，格式如下 ```
:::tip
````markdown 语法自查 https://mermaid.js.org
```mermaid :::
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
````
会渲染成
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
:::tip
语法自查 https://mermaid.js.org
:::
3. 代码分块 3. 代码分块
```` ```
::: code-group ::: code-group
```sh [npm] ```sh [npm]
$ npm install -D vitepress $ npm install -D vitepress
``` ```
```sh [pnpm] ```sh [pnpm]
$ pnpm add -D vitepress $ pnpm add -D vitepress
``` ```
```sh [yarn] ```sh [yarn]
$ yarn add -D vitepress $ yarn add -D vitepress
``` ```
::: :::
```` ```
::: code-group
::: code-group ```sh [npm]
$ npm install -D vitepress
```
```sh [npm] ```sh [pnpm]
$ npm install -D vitepress $ pnpm add -D vitepress
``` ```
```sh [pnpm] ```sh [yarn]
$ pnpm add -D vitepress $ yarn add -D vitepress
``` ```
```sh [yarn] :::
$ yarn add -D vitepress
```
:::
4. 图片缩放 4. 图片缩放
图片默认支持缩放，鼠标悬浮图片上方会出现放大镜图标，点击即可放大图片。 图片默认支持缩放，鼠标悬浮图片上方会出现放大镜图标，点击即可放大图片。
如果不想让图片缩放，可以在图片 class 内后添加 `no-zoom` 参数。 如果不想让图片缩放，可以在图片class内后添加 `no-zoom` 参数。
markdown 的使用方式如下 markdown 的使用方式如下
```markdown ```markdown
# 默认（支持缩放） # 默认（支持缩放）
![](static/xxx.png) ![](static/xxx.png)
``` ```
```markdown ```markdown
# 不支持缩放 # 不支持缩放
![](static/xxx.png){.no-zoom} ![](static/xxx.png){.no-zoom}
``` ```