Skip to main content

网站贡献指南

¥Website Contributing Guidelines

本网站使用现代静态网站生成器 Docusaurus 3 构建。

¥This website is built using Docusaurus 3, a modern static website generator.

环境​

¥Environment

你将需要在系统上安装以下工具：

¥You will need these tools installed on your system:

开发​

¥Development

  1. 复刻 MySQL2 存储库。

    ¥Fork the MySQL2 repository.

  2. 在本地下载你的复刻存储库。网站的工作区是 node-mysql2 根目录中的 "website" 目录。

    ¥Download your forked repository locally. The website's workspace is the "website" directory in node-mysql2 root.

  3. 从 master 创建一个新分支（可选）。

    ¥Create a new branch from master (optional).

  4. 运行 cd website 进入网站工作区。

    ¥Run cd website to enter the website workspace.

  5. 运行 npm ci 安装 package-lock.json 中的依赖。

    ¥Run npm ci to install the dependecies from package-lock.json.

  6. 运行 npm start 开始本地开发。

    ¥Run npm start to starting the local development.

它将启动本地开发服务器并打开浏览器窗口。大多数更改都会实时反映出来，而无需重新启动服务器。

¥It will start a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

有关 Docusaurus 完整文档，请参阅 参见此处。

¥For Docusaurus complete documentation, please see here.

CLI example
git clone https://github.com/sidorares/node-mysql2.git
git checkout -b website # optional
cd /path-to/node-mysql2/website
npm ci
npm start

文档是从放置在这些目录中的 MDX 文件自动生成的：

¥Documentation is auto-generated from MDX files placed in these directories:

  • ./docs/documentation

  • ./docs/examples

  • ./docs/faq

警告

请注意，该网站有自己的 package.json。

¥Note that the website has its own package.json.

请不要在 node-mysql2 根目录中为网站安装依赖。

¥Please, do not install dependencies for the website in node-mysql2 root.

额外组件​

¥Extras Components

每个额外组件都经过全面记录，并附有完整的类型描述。

¥Every extra component is thoroughly documented with complete typings descriptions.

Docusaurus Markdown 功能： MDX 编译器将 Markdown 文件转换为 React 组件，并允许你在 Markdown 内容中使用 JSX。这使你能够轻松地在内容中交错 React 组件，并创造愉快的学习体验。

¥Docusaurus Markdown Features: The MDX compiler transforms Markdown files to React components, and allows you to use JSX in your Markdown content. This enables you to easily interleave React components within your content, and create delightful learning experiences.

历史​

¥History

History 组件以表格形式显示版本更改，并在更改旁边列发布本号。

¥The History component displays version changes in a table format, listing version numbers alongside their changes.

import { History } from '@site/src/components/History';

<History
  records={[
    {
      version: '1.0.0',
      changes: ['Some change message.'],
    },
  ]}
/>
提示

你还可以在 changes 选项中使用 React 组件。

¥You can also utilize React components in the changes option.

Example
History
VersionChanges
v1.0.0
Some change message.

稳定性​

¥Stability

有关更多详细信息，请参阅 稳定性徽章。

¥See the Stability Badges for more detais.

import { Stability } from '@site/src/components/Stability';

<Stability level={2} />
<Stability level={2} message='Some message' />
提示

你还可以在 message 选项中使用 React 组件。

¥You can also utilize React components in the message option.

可用级别:0、1、1.1、1.2、2 和 3。

¥Available levels: 0, 1, 1.1, 1.2, 2 and 3.

Example
2Stable
2Stable

Some message.

常见问题​

¥FAQ

import { FAQ } from '@site/src/components/FAQ';

<FAQ title='Title'>

  > Some markdown (**MDX**) content.

</FAQ>
提示

  • FAQ 组件可用于任何部分或页面。

    ¥The FAQ component can be utilized in any section or page.

  • 代码块兼容，可以在 FAQ 组件中使用。

    ¥Code blocks are compatible and can be used within the FAQ component.

Example
Title

一些 markdown (MDX) 内容。

¥Some markdown (MDX) content.

ExternalCodeEmbed​

import { ExternalCodeEmbed } from '@site/src/components/ExternalCodeEmbed';

<ExternalCodeEmbed
  url='https://github.com/sidorares/node-mysql2/blob/75b05f0765c9edd0c0be8f18d85be05618770cca/.prettierrc'
  language='json'
/>

<ExternalCodeEmbed
  url='https://raw.githubusercontent.com/sidorares/node-mysql2/master/tools/parse-row.js'
  language='js'
  extractMethod='parseC'
  methodType='function'
/>
Example

运行测试​

¥Running Tests

npm run test
Check Prettier and ESLint rules for compliance
npm run lintcheck

  • 包含在 GitHub Actions 工作流中。

    ¥Included in the GitHub Actions workflow.

Check for typings errors
1Experimental

Checks for MDX components are missing.

npm run typecheck

  • 包含在 GitHub Actions 工作流中。

    ¥Included in the GitHub Actions workflow.

Clear and build the website
npm run clear
npm run build

  • 包含在 GitHub Actions 工作流中。

    ¥Included in the GitHub Actions workflow.

Fix issues from Prettier and ESLint rules
npm run lint

  • 为防止出现 lint 问题，建议在创建提交之前执行此命令。

    ¥To prevent lint issues, it is recommended to execute this command before creating your commit.

  • 未包含在 GitHub Actions 工作流程中。

    ¥Not included in the GitHub Actions workflow.