Skip to main content

Website Contributing Guidelines

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

Environmentโ€‹

You will need these tools installed on your system:

Developmentโ€‹

  1. Fork the MySQL2 repository.
  2. Download your forked repository locally. The website's workspace is the "website" directory in node-mysql2 root.
  3. Create a new branch from master (optional).
  4. Run cd website to enter the website workspace.
  5. Run npm ci to install the dependecies from package-lock.json.
  6. 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.

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

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

  • ./docs/documentation
  • ./docs/examples
  • ./docs/faq
Caution

Note that the website has its own package.json.

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 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โ€‹

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.'],
    },
  ]}
/>
tip

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' />
tip

You can also utilize React components in the message option.

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>
tip
  • The FAQ component can be utilized in any section or page.
  • Code blocks are compatible and can be used within the FAQ component.
Example
Title

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
  • Included in the GitHub Actions workflow.
Check for typings errors
1Experimental

Checks for MDX components are missing.

npm run typecheck
  • Included in the GitHub Actions workflow.
Clear and build the website
npm run clear
npm run build
  • Included in the GitHub Actions workflow.
Fix issues from Prettier and ESLint rules
npm run lint
  • To prevent lint issues, it is recommended to execute this command before creating your commit.
  • Not included in the GitHub Actions workflow.