From 50c98a4fa9a4826fb32e25eaba18c96e19b05a76 Mon Sep 17 00:00:00 2001 From: wellwelwel <46850407+wellwelwel@users.noreply.github.com> Date: Mon, 27 Nov 2023 10:23:59 -0300 Subject: [PATCH] docs: create website Contributing page --- website/docs/contributing.mdx | 4 - website/docs/contributing/00-index.mdx | 13 ++ website/docs/contributing/website.mdx | 208 ++++++++++++++++++ website/docusaurus.config.ts | 7 +- .../current.json | 3 + .../current/contributing.mdx | 4 - .../current/contributing/00-index.mdx | 13 ++ .../current.json | 3 + .../00-index.mdx} | 9 + website/sidebars.ts | 10 +- website/src/components/FAQ.tsx | 11 + website/src/css/_history.scss | 3 +- 12 files changed, 273 insertions(+), 15 deletions(-) delete mode 100644 website/docs/contributing.mdx create mode 100644 website/docs/contributing/00-index.mdx create mode 100644 website/docs/contributing/website.mdx delete mode 100644 website/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing.mdx create mode 100644 website/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing/00-index.mdx rename website/i18n/zh-CN/docusaurus-plugin-content-docs/current/{contributing.mdx => contributing/00-index.mdx} (56%) diff --git a/website/docs/contributing.mdx b/website/docs/contributing.mdx deleted file mode 100644 index f01e7b9ac2..0000000000 --- a/website/docs/contributing.mdx +++ /dev/null @@ -1,4 +0,0 @@ -# Contributing - -Want to improve something in **MySQL2**? -Please check [Contributing.md](https://github.com/sidorares/node-mysql2/blob/master/Contributing.md) for detailed instruction on how to get started. diff --git a/website/docs/contributing/00-index.mdx b/website/docs/contributing/00-index.mdx new file mode 100644 index 0000000000..cc8e64ee1b --- /dev/null +++ b/website/docs/contributing/00-index.mdx @@ -0,0 +1,13 @@ +--- +slug: /contributing +title: MySQL2 +--- + +import { PageTitle } from '@site/src/components/PageTitle'; + + + +# Contributing + +Want to improve something in **MySQL2**? +Please check [Contributing.md](https://github.com/sidorares/node-mysql2/blob/master/Contributing.md) for detailed instruction on how to get started. diff --git a/website/docs/contributing/website.mdx b/website/docs/contributing/website.mdx new file mode 100644 index 0000000000..b8011ccb55 --- /dev/null +++ b/website/docs/contributing/website.mdx @@ -0,0 +1,208 @@ +--- +title: Documentation Site +--- + +import { FAQ } from '@site/src/components/FAQ'; +import { History } from '@site/src/components/History'; +import { Stability } from '@site/src/components/Stability'; + +# Website Contributing Guidelines + +This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator. + +--- + +## Environment + +You will need these tools installed on your system: + +- [Node.js (18.x or higher)](https://nodejs.org/) + +--- + +## Development + +1. Fork the [MySQL2](https://github.com/sidorares/node-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](https://docusaurus.io/docs). + + + +```bash +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_ + +:::danger 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:**](https://docusaurus.io/docs/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. + +{/* prettier-ignore-start */} +```tsx +import { History } from '@site/src/components/History'; + + +``` +{/* prettier-ignore-end */} + +:::tip +You can also utilize React components in the `changes` option. +::: + + + + + +--- + +### Stability + +See the [Stability Badges](/docs/stability-badges) for more detais. + +{/* prettier-ignore-start */} +```tsx +import { History } from '@site/src/components/History'; + + + +``` +{/* prettier-ignore-end */} + +:::tip +You can also utilize React components in the `message` option. +::: + +Available levels: `0`, `1`, `1.1`, `1.2`, `2` and `3`. + + + + + + +--- + +### FAQ + +{/* prettier-ignore-start */} +```tsx +import { FAQ } from '@site/src/components/FAQ'; + + + + > Some markdown (**MDX**) content. + + +``` +{/* prettier-ignore-end */} + +:::tip + +- The **FAQ** component can be utilized in any section or page. +- Code blocks are compatible and can be used within the **FAQ** component. + ::: + + + + + > Some markdown (**MDX**) content. + + + + +--- + +## Running Tests + + + +```bash +npm run lintcheck +``` + +- Included in the **GitHub Actions** workflow. + + + + + + Checks for MDX components are missing. + + } +/> + +```bash +npm run typecheck +``` + +- Included in the **GitHub Actions** workflow. + + + + +```bash +npm run clear +npm run build +``` + +- Included in the **GitHub Actions** workflow. + + + + +```bash +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. + + diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 243e0d2ca8..fa1191739a 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -63,6 +63,11 @@ const config: Config = { className: 'navbar__brand navbar__manual--title text--truncate', activeBaseRegex: `^/$`, }, + { + to: '/docs/examples', + label: 'Examples', + position: 'left', + }, { to: '/docs/faq', label: 'FAQ', @@ -88,7 +93,7 @@ const config: Config = { prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, - additionalLanguages: ['json'], + additionalLanguages: ['json', 'bash', 'tsx'], }, } satisfies Preset.ThemeConfig, diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current.json b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current.json index fe3aac267c..13b9013247 100644 --- a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current.json @@ -4,5 +4,8 @@ }, "sidebar.docs.category.Examples": { "message": "Exemplos" + }, + "sidebar.docs.category.Contributing": { + "message": "Contribuições" } } diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing.mdx deleted file mode 100644 index 8c05aaca21..0000000000 --- a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing.mdx +++ /dev/null @@ -1,4 +0,0 @@ -# Contribuições - -Quer melhorar algo no **MySQL2**? -Consulte o arquivo [Contributing.md](https://github.com/sidorares/node-mysql2/blob/master/Contributing.md) para instruções detalhadas sobre como começar. diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing/00-index.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing/00-index.mdx new file mode 100644 index 0000000000..323705d638 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing/00-index.mdx @@ -0,0 +1,13 @@ +--- +slug: /contributing +title: MySQL2 +--- + +import { PageTitle } from '@site/src/components/PageTitle'; + + + +# Contribuições + +Quer melhorar algo no **MySQL2**? +Consulte o arquivo [Contributing.md](https://github.com/sidorares/node-mysql2/blob/master/Contributing.md) para instruções detalhadas sobre como começar. diff --git a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current.json b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current.json index 1acf88478e..f5bb4bd3a8 100644 --- a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current.json @@ -4,5 +4,8 @@ }, "sidebar.docs.category.Examples": { "message": "Examples" + }, + "sidebar.docs.category.Contributing": { + "message": "贡献" } } diff --git a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/contributing.mdx b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/contributing/00-index.mdx similarity index 56% rename from website/i18n/zh-CN/docusaurus-plugin-content-docs/current/contributing.mdx rename to website/i18n/zh-CN/docusaurus-plugin-content-docs/current/contributing/00-index.mdx index effe6db940..498ab0d40b 100644 --- a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/contributing.mdx +++ b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/contributing/00-index.mdx @@ -1,3 +1,12 @@ +--- +slug: /contributing +title: MySQL2 +--- + +import { PageTitle } from '@site/src/components/PageTitle'; + + + # 贡献 如果要为`node-mysql2`做些贡献.请查阅 [Contributing.md](https://github.com/sidorares/node-mysql2/blob/master/Contributing.md) 来获得更多详细信息。 diff --git a/website/sidebars.ts b/website/sidebars.ts index b952ea208d..8bdfbfbad1 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -10,15 +10,15 @@ const sidebars: SidebarsConfig = { label: 'Documentation', items: [{ type: 'autogenerated', dirName: 'documentation' }], }, + 'api-and-configurations', + 'acknowledgements', { type: 'category', - label: 'Examples', - items: [{ type: 'autogenerated', dirName: 'examples' }], + label: 'Contributing', + items: [{ type: 'autogenerated', dirName: 'contributing' }], }, - 'api-and-configurations', - 'acknowledgements', - 'contributing', ], + examples: [{ type: 'autogenerated', dirName: 'examples' }], faq: [{ type: 'autogenerated', dirName: 'faq' }], }; diff --git a/website/src/components/FAQ.tsx b/website/src/components/FAQ.tsx index c6fa6edd9f..51c5593724 100644 --- a/website/src/components/FAQ.tsx +++ b/website/src/components/FAQ.tsx @@ -8,6 +8,17 @@ export type FAQProps = { title: string; }; +/** + * Usage example: + * + * ```mdx + * + * + * > Some markdown (**MDX**) content. + * + * + * ``` + */ export const FAQ: FC = ({ children, open, title }) => { return (