跳转到内容
CST 自学指南

贡献指南

这份资料的源代码开源在了 GitHub NJUPTFreeExams/CST-Self-Learning。我们欢迎您以创建拉取请求（PR）的方式向此项目贡献内容。

项目框架与文件目录结构

该项目是使用 Astro 构建的，使用了 Starlight 主题。

文件目录结构如下：

  • 文件夹public/
    • …
  • 文件夹src
    • 文件夹assets/
      • …
    • 文件夹content/
      • 文件夹docs/
        • 文件夹intro/
          • …
        • 文件夹guides/
          • …
        • 文件夹science/
          • …
        • 文件夹technology/
          • …
        • index.mdx
        • …
  • astro.config.mjs
  • package.json
  • tsconfig.json

高亮显示的目录和文件是您需要重点关注的部分：

  • src/assets/：如果您需要在文档中插入图片等资源，可以将其放在这里。
  • src/content/docs/：这是文档的主要目录。您的文章应该放在这里。
  • astro.config.mjs：这是项目的配置文件。如果您新增了一篇文章，需要在这里添加对应的路由。

更多关于项目的配置信息，请参考 Astro 文档 和 Starlight 文档。

文件格式

我们使用 Markdown 进行文档编写。同时，我们也支持基于此扩展的 MDX 格式。请阅读 Starlight 文档 以了解更多。

写作风格

我们希望您的文章能够尽可能地符合一定的写作风格，以保证整个文档的一致性，提升读者的体验。例如，我们使用 “我们”、“作者” 等词语来指代文档作者，使用 “您” 来指代读者。

这里是一份参考资料：

步骤示例

这是一个完整的示例，展示了如何向项目贡献一篇新的文章的步骤。在此流程中，您需要使用 Git 和 GitHub。所以，如果您还不熟悉 Git 和 GitHub，您可以参考本站的 Git 和 GitHub 文档。

前置条件

具体步骤

  1. 首先，您需要前往本项目的 GitHub 主页，点击右上角的 “Fork” 按钮，将项目复刻到您自己的账户下。
  2. 然后，您需要将项目克隆到本地。在您的终端中执行以下命令：
Terminal window
git clone git@github.com:NJUPTFreeExams/CST-Self-Learning.git

上面的命令将会在您的当前工作目录创建 CST-Self-Learning 子目录。

  1. 使用下面的命令进入该子目录：
Terminal window
cd CST-Self-Learning
  1. 然后运行下面的命令来安装依赖：
Terminal window
pnpm i
  1. 输入下面的命令来创建一个新的分支：
Terminal window
git checkout -b BRANCH_NAME

您需要将 BRANCH_NAME 替换为一个语义化的有效字符组成的分支名，例如 update-contribution-guide。

  1. 打开您的编辑器，修改文件并适时地使用 git add 和 git commit 来保存 Commit：
Terminal window
git add FILENAME
git commit -m "SHORT_MESSAGE_SHOWING_YOUR_CHANGE"
  1. 当您完成了所有的修改后，您可以使用下面的命令将您的分支推送到您的 GitHub 仓库，请使用与上面相同的分支名：
Terminal window
git push -u origin BRANCH_NAME

  1. 前往 GitHub 网站到您复刻得到的仓库首页，您将会看到一个 “Compare & pull request” 按钮。点击它，填写 PR 的标题和描述，然后点击 “Create pull request” 按钮。

  2. 等待项目维护者的审核。如果您的 PR 被接受，您的修改将会被合并。

更多参考内容