From 9bcce5aa298f2674979df90fb1e61e33505a17be Mon Sep 17 00:00:00 2001 From: kiameow Date: Mon, 29 Jul 2024 21:59:21 +0800 Subject: [PATCH] docs: propose the code of document naming --- CONTRIBUTING.md | 584 ++++++++++++++++++++++++++++-------------------- 1 file changed, 344 insertions(+), 240 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fca6c30..d941638 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,198 +25,291 @@ - 网站页面设计 - 在各种媒体、博客文章、群内宣传 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 。 @@ -230,7 +323,7 @@ vitepress 框架要求，强制需要 nodejs v18.0 及以上版本。 本项目使用包管理器 npm。 ```bash -npm install +npm install npm run docs:dev #运行预览环境 ``` @@ -241,7 +334,7 @@ npm run docs:preview #预览线上环境 ## 图片放置指南 -图片放置在当前大章节的 `static` 目录下，然后在 md 文件中使用相对路径引用。 +图片放置在当前大章节 或者 模块章节的 `static` 目录下，然后在 md 文件中使用相对路径引用。 ```markdown ![](static/xxx.png) @@ -265,12 +358,13 @@ 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) 约定） @@ -294,13 +388,13 @@ type为commit的类型 build: 对项目构建或者依赖的改动 ci: CI 的修改 revert: revert 前一个 commit(撤销前一个commit) - + scope是文件名 / 模块名 / 影响的范围 例如 schoolSchedule - + subject为commit概述 建议符合 50 / 72 formatting - + 例 feat(JoinForm): add success submit tips 冒号后方可以使用中文描述 @@ -322,93 +416,103 @@ Fork 本仓库，然后在你的仓库中进行修改，修改完成后在本仓 ## Feature -1. Markdown 内支持Latex公式，格式为单行公式双dollar符号、单行公式单dollar符号。（单行公式需要换行才能解析）例如： - ```latex - $行内公式\arccos{a}$ - ``` - > 会渲染成 $\arccos{a}$ - ```latex - $$单行公式\arcsin{b}$$ - ``` - > 会渲染成 - > - > $$\arcsin{b}$$ - ::: tip - Latex语法在线编辑器 https://www.latexlive.com - ::: +1. Markdown 内支持 Latex 公式，格式为单行公式双 dollar 符号、单行公式单 dollar 符号。（单行公式需要换行才能解析）例如： -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 - ::: + ```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 + ::: 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 + ::: + ```` - ```sh [npm] - $ npm install -D vitepress - ``` + ::: code-group - ```sh [pnpm] - $ pnpm add -D vitepress - ``` + ```sh [npm] + $ npm install -D vitepress + ``` - ```sh [yarn] - $ yarn add -D vitepress - ``` + ```sh [pnpm] + $ pnpm 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} ```