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

576
CONTRIBUTING.md
View File

@@ -25,291 +25,198 @@
- 网站页面设计
- 在各种媒体、博客文章、群内宣传 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 语法。
2. 一个页面必须且只有一个 1 级标题（H1，一个#），其他标题从 2 级开始（H2，##）。
2. 一个页面必须且只有一个1级标题（H1，一个#），其他标题从2级开始（H2，##）。
3. 本项目自动在英文与中文、数字与中文之间添加空格。
```markdown
AI 与人工智能，AGI 的发展方向。
AI 与人工智能，AGI 的发展方向。
```
4. 标题内的英文单词首字母大写。
5. 代码块使用 ` ``` ` 包裹，并标注常见的语言标识符，如 ` ```python ` ，其作用是使代码正常高亮。
::: details 代码高亮支持的语言
::: details 代码高亮支持的语言
```ts twoslash
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";
| '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文件后直接提交，因为它的渲染效果和本项目前端 md 渲染器 `vitepress markdown-it` 不一致。
在 `typora` 中编辑完成后，确认一下 .md 文件源代码是否为正常 Markdown 。
@@ -334,7 +241,7 @@ npm run docs:preview #预览线上环境
## 图片放置指南
图片放置在当前大章节 或者 模块章节的 `static` 目录下，然后在 md 文件中使用相对路径引用。
图片放置在当前大章节的 `static` 目录下，然后在 md 文件中使用相对路径引用。
```markdown
![](static/xxx.png)
@@ -358,13 +265,12 @@ npm run docs:preview #预览线上环境
## 如何使用 Git 和 Github
详见 [3.5 Git 和 Github](./2023旧版内容/3.编程思维体系构建/3.5git与github.md)
详见 [3.5 Git和Github](./2023旧版内容/3.编程思维体系构建/3.5git与github.md)
## Commit Message 规范
::: tip 🐒
本项目没有强制使用 [commitlint](https://github.com/conventional-changelog/commitlint) ，但是建议遵循以下规范。
> 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) 约定）
@@ -416,103 +322,93 @@ Fork 本仓库，然后在你的仓库中进行修改，修改完成后在本仓
## 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
$行内公式\arccos{a}$
```
> 会渲染成 $\arccos{a}$
```latex
$$单行公式\arcsin{b}$$
```
> 会渲染成
>
> $$\arcsin{b}$$
> ::: tip
> Latex 语法在线编辑器 https://www.latexlive.com
> :::
2. 支持 Mermaid 流程图，格式如下
````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
:::
2. 支持Mermaid流程图，格式如下
```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. 代码分块
````
::: code-group
```
::: code-group
```sh [npm]
$ npm install -D vitepress
```
```sh [npm]
$ npm install -D vitepress
```
```sh [pnpm]
$ pnpm add -D vitepress
```
```sh [pnpm]
$ pnpm add -D vitepress
```
```sh [yarn]
$ yarn add -D vitepress
```
```sh [yarn]
$ yarn add -D vitepress
```
:::
````
:::
```
::: code-group
::: code-group
```sh [npm]
$ npm install -D vitepress
```
```sh [npm]
$ npm install -D vitepress
```
```sh [pnpm]
$ pnpm add -D vitepress
```
```sh [pnpm]
$ pnpm add -D vitepress
```
```sh [yarn]
$ yarn add -D vitepress
```
```sh [yarn]
$ yarn add -D vitepress
```
:::
:::
4. 图片缩放
图片默认支持缩放，鼠标悬浮图片上方会出现放大镜图标，点击即可放大图片。
如果不想让图片缩放，可以在图片 class 内后添加 `no-zoom` 参数。
如果不想让图片缩放，可以在图片class内后添加 `no-zoom` 参数。
markdown 的使用方式如下
```markdown
# 默认（支持缩放）
![](static/xxx.png)
```
```markdown
# 不支持缩放
![](static/xxx.png){.no-zoom}
```