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

docs: propose the code of document naming

Browse Source
This commit is contained in:
kiameow
2024-07-29 21:59:21 +08:00
parent d60855c8e8
commit 9bcce5aa29
1 changed files with 344 additions and 240 deletions
Download Patch File Download Diff File Expand all files Collapse all files

584
CONTRIBUTING.md
View File

@@ -25,198 +25,291 @@
- 网站页面设计 - 网站页面设计
- 在各种媒体、博客文章、群内宣传 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' | 'batch' | "bat"
| 'beancount' | "batch"
| 'berry' | 'be' | "beancount"
| 'bibtex' | "berry"
| 'bicep' | "be"
| 'blade' | "bibtex"
| 'c' | "bicep"
| 'cadence' | 'cdc' | "blade"
| 'clarity' | "c"
| 'clojure' | 'clj' | "cadence"
| 'cmake' | "cdc"
| 'cobol' | "clarity"
| 'codeql' | 'ql' | "clojure"
| 'coffee' | "clj"
| 'cpp' | "cmake"
| 'crystal' | "cobol"
| 'csharp' | 'c#' | 'cs' | "codeql"
| 'css' | "ql"
| 'cue' | "coffee"
| 'cypher' | 'cql' | "cpp"
| 'd' | "crystal"
| 'dart' | "csharp"
| 'dax' | "c#"
| 'diff' | "cs"
| 'docker' | 'dockerfile' | "css"
| 'dream-maker' | "cue"
| 'elixir' | "cypher"
| 'elm' | "cql"
| 'erb' | "d"
| 'erlang' | 'erl' | "dart"
| 'fish' | "dax"
| 'fsharp' | 'f#' | 'fs' | "diff"
| 'gdresource' | "docker"
| 'gdscript' | "dockerfile"
| 'gdshader' | "dream-maker"
| 'gherkin' | "elixir"
| 'git-commit' | "elm"
| 'git-rebase' | "erb"
| 'glimmer-js' | 'gjs' | "erlang"
| 'glimmer-ts' | 'gts' | "erl"
| 'glsl' | "fish"
| 'gnuplot' | "fsharp"
| 'go' | "f#"
| 'graphql' | "fs"
| 'groovy' | "gdresource"
| 'hack' | "gdscript"
| 'haml' | "gdshader"
| 'handlebars' | 'hbs' | "gherkin"
| 'haskell' | 'hs' | "git-commit"
| 'hcl' | "git-rebase"
| 'hjson' | "glimmer-js"
| 'hlsl' | "gjs"
| 'html' | "glimmer-ts"
| 'http' | "gts"
| 'imba' | "glsl"
| 'ini' | 'properties' | "gnuplot"
| 'java' | "go"
| 'javascript' | 'js' | "graphql"
| 'jinja-html' | "groovy"
| 'jison' | "hack"
| 'json' | "haml"
| 'json5' | "handlebars"
| 'jsonc' | "hbs"
| 'jsonl' | "haskell"
| 'jsonnet' | "hs"
| 'jssm' | 'fsl' | "hcl"
| 'jsx' | "hjson"
| 'julia' | "hlsl"
| 'kotlin' | "html"
| 'kusto' | 'kql' | "http"
| 'latex' | "imba"
| 'less' | "ini"
| 'liquid' | "properties"
| 'lisp' | "java"
| 'logo' | "javascript"
| 'lua' | "js"
| 'make' | 'makefile' | "jinja-html"
| 'markdown' | 'md' | "jison"
| 'marko' | "json"
| 'matlab' | "json5"
| 'mdx' | "jsonc"
| 'mermaid' | "jsonl"
| 'mojo' | "jsonnet"
| 'narrat' | 'nar' | "jssm"
| 'nextflow' | 'nf' | "fsl"
| 'nginx' | "jsx"
| 'nim' | "julia"
| 'nix' | "kotlin"
| 'objective-c' | 'objc' | "kusto"
| 'objective-cpp' | "kql"
| 'ocaml' | "latex"
| 'pascal' | "less"
| 'perl' | "liquid"
| 'php' | "lisp"
| 'plsql' | "logo"
| 'postcss' | "lua"
| 'powerquery' | "make"
| 'powershell' | 'ps' | 'ps1' | "makefile"
| 'prisma' | "markdown"
| 'prolog' | "md"
| 'proto' | "marko"
| 'pug' | 'jade' | "matlab"
| 'puppet' | "mdx"
| 'purescript' | "mermaid"
| 'python' | 'py' | "mojo"
| 'r' | "narrat"
| 'raku' | 'perl6' | "nar"
| 'razor' | "nextflow"
| 'reg' | "nf"
| 'rel' | "nginx"
| 'riscv' | "nim"
| 'rst' | "nix"
| 'ruby' | 'rb' | "objective-c"
| 'rust' | 'rs' | "objc"
| 'sas' | "objective-cpp"
| 'sass' | "ocaml"
| 'scala' | "pascal"
| 'scheme' | "perl"
| 'scss' | "php"
| 'shaderlab' | 'shader' | "plsql"
| 'shellscript' | 'bash' | 'sh' | 'shell' | 'zsh' | "postcss"
| 'shellsession' | 'console' | "powerquery"
| 'smalltalk' | "powershell"
| 'solidity' | "ps"
| 'sparql' | "ps1"
| 'splunk' | 'spl' | "prisma"
| 'sql' | "prolog"
| 'ssh-config' | "proto"
| 'stata' | "pug"
| 'stylus' | 'styl' | "jade"
| 'svelte' | "puppet"
| 'swift' | "purescript"
| 'system-verilog' | "python"
| 'tasl' | "py"
| 'tcl' | "r"
| 'tex' | "raku"
| 'toml' | "perl6"
| 'tsx' | "razor"
| 'turtle' | "reg"
| 'twig' | "rel"
| 'typescript' | 'ts' | "riscv"
| 'v' | "rst"
| 'vb' | 'cmd' | "ruby"
| 'verilog' | "rb"
| 'vhdl' | "rust"
| 'viml' | 'vim' | 'vimscript' | "rs"
| 'vue-html' | "sas"
| 'vue' | "sass"
| 'vyper' | 'vy' | "scala"
| 'wasm' | "scheme"
| 'wenyan' | '文言' | "scss"
| 'wgsl' | "shaderlab"
| 'wolfram' | "shader"
| 'xml' | "shellscript"
| 'xsl' | "bash"
| 'yaml' | 'yml' | "sh"
| 'zenscript' | "shell"
| 'zig' | "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 🤓 注意 ::: tip 🤓 注意
尽量不要使用 `typora` 等编辑器编辑完 .md文件后直接提交，因为它的渲染效果和本项目前端 md 渲染器 `vitepress markdown-it` 不一致。 尽量不要使用 `typora` 等编辑器编辑完 .md 文件后直接提交，因为它的渲染效果和本项目前端 md 渲染器 `vitepress markdown-it` 不一致。
在 `typora` 中编辑完成后，确认一下 .md 文件源代码是否为正常 Markdown 。 在 `typora` 中编辑完成后，确认一下 .md 文件源代码是否为正常 Markdown 。
@@ -230,7 +323,7 @@ vitepress 框架要求，强制需要 nodejs v18.0 及以上版本。
本项目使用包管理器 npm。 本项目使用包管理器 npm。
```bash ```bash
npm install npm install
npm run docs:dev #运行预览环境 npm run docs:dev #运行预览环境
``` ```
@@ -241,7 +334,7 @@ npm run docs:preview #预览线上环境
## 图片放置指南 ## 图片放置指南
图片放置在当前大章节的 `static` 目录下，然后在 md 文件中使用相对路径引用。 图片放置在当前大章节 或者 模块章节的 `static` 目录下，然后在 md 文件中使用相对路径引用。
```markdown ```markdown
![](static/xxx.png) ![](static/xxx.png)
@@ -265,12 +358,13 @@ 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) 约定）
@@ -294,13 +388,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
冒号后方可以使用中文描述 冒号后方可以使用中文描述
@@ -322,93 +416,103 @@ 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
:::
2. 支持Mermaid流程图，格式如下 ```latex
```markdown $行内公式\arccos{a}$
```mermaid ```
graph TD;
A-->B; > 会渲染成 $\arccos{a}$
A-->C;
B-->D; ```latex
C-->D; $$单行公式\arcsin{b}$$
``` ```
```
会渲染成 > 会渲染成
```mermaid >
graph TD; > $$\arcsin{b}$$
A-->B; > ::: tip
A-->C; > Latex 语法在线编辑器 https://www.latexlive.com
B-->D; > :::
C-->D;
``` 2. 支持 Mermaid 流程图，格式如下
:::tip
语法自查 https://mermaid.js.org ````markdown
::: ```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
```sh [npm] ::: code-group
$ npm install -D vitepress
```
```sh [pnpm] ```sh [npm]
$ pnpm add -D vitepress $ npm install -D vitepress
``` ```
```sh [yarn] ```sh [pnpm]
$ yarn add -D vitepress $ pnpm 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}
``` ```