docs: introduce documentation website

[wellwelwel]

Introducing a documentation website 🦖✨

For now, I'm testing it in a temporary repository to see everything working on GitHub Pages.
Feel free to check how it's going in https://wellwelwel.github.io/node-mysql2-website-test.

---

How it works (for now)?

• After merged, it will create a new branch (gh-pages) and compile the website in this branch.
• By setting the Pages settings to gh-pages branch, it will create a GitHub URL (https://sidorares.github.io/node-mysql2) with this branch content
• Both the website's package.json and package-lock.json are separate from main code.

---

Required actions:

If you decide to keep GitHub Pages

• Before merge it:

  • Settings > Actions > General > Workflow permissions:
    • Check if it's flagged as Read and write permissions.

• After merge it:

  • Settings > Pages > Source:
    • Select Deploy from a branch
  • Settings > Pages > Branch:
    • Select gh-pages

---

Unofficial temporary favicon (this isn't a logo):

Example:

---

TODO

• Include all .md files
• Include a free search tool (similar to Algolia)
• Migrate translations
• Check for lint rules and build tests
• Include examples
• Components
  • History
  • Stability
  • FAQ
• Pages
  • Stability Badges
  • FAQ
    • At least one question
• Review and test links
• Create the website Contributing

---

Tech stack includes:

• Docusaurus
  • React (.tsx files)
  • MDX (.mdx files)
  • Saas (.scss files)
• TypeScript (.ts files)

---

Naturally, ask any questions you like 🧙🏻

---

To discuss (resolved)

• I opted for a 100% free format, so it uses GitHub Pages to serve the website and provides a free domain.~
• I've chosen to show examples based on promise-based first.
• As said in Documentation missing simple examples. How to insert using variables etc ... #2263 (comment), I'm using the current documentation and examples to start it. Naturally, increasing more complete documentation in the long term.
• Only after (if) this PR is approved, remove the "old" documentation and direct it to the website (in a new PR).

[wellwelwel]

Testing the documentation search 🕵🏻

[sidorares]

I'd like to balance "light and simple to navigate" vs "complete" so feel free to push on these suggestions. What do you think about adding:

• "stability" badge, similar to what node docs use
• history ( at least "version when api was introduced" )
• link to mysql wire docs, for example AuthSwitch would link to https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_connection_phase.html#sect_protocol_connection_phase_auth_method_mismatch_method_change

happy to discuss that later and if we agree to add have as a later change

[sidorares]

we could potentially use https://mysql2.js.org domain . To get it we would need to open https://github.com/js-org/js.org/pulls PR and get it approved and merged

[wellwelwel]

I'd like to balance "light and simple to navigate" vs "complete"

Yes, in a simple way, Docusaurs can be seen as a React App that parses markdowns to React Components ⚛️

So we have a flexible way to create documentations using both markdown (.md and .mdx) and entire pages in ReactJS (.tsx).

The "stability" badge for example, could be a React page.
And yes, we can set some sections as external links 🧑🏻‍🔧

---

An important point is that it should be easy to maintain by:

• creating a Contributing.md exclusive for the website, showing:
  • how to start the server locally
  • how the routes work
  • how to add a new sidebar section
  • how to add a new page (like faq, etc.)

---

history ( at least "version when api was introduced" )

I don't get it 😟
Do you say something like v3.x, v4.x, etc.? If so, yes, we can do it 🙋🏻‍♂️

---

By lastly, you can set a custom domain on GitHub Pages settings, case not, it will be the default https://sidorares.github.io/node-mysql2 🌞

[sidorares]

version when api was introduced

see "history" blocks in nodejs docs, for example here https://nodejs.org/api/async_hooks.html#class-asynchook

Basically an earliest version before which documented api cannot be used

[wellwelwel]

Hey @sidorares, a simple question about options: A or B?

For now, I'll keep it as it is (A) 👩🏻‍🎤

• A (original):

  • 

• B:

  • 

[sidorares]

Both look good, I trust your taste here

[wellwelwel]

@sidorares, finally, it's ready 🎉✨

---

Notes

• This PR keeps everything intact with absolutely 0 deletions
  • Everything happens in the "website" directory
• No documentation was modified or added, except for:
  • In README documentation section, I've added both promise and callback examples
  • I've used the Stability Badges and History in the TypeScript documentation
• Documentation and examples can now be searched dynamically
• The search works for all languages and searches all pages for each language
  • 🇺🇸
  • 🇨🇳
  • 🇧🇷
• I introduced some of the ideas we discussed:
  • History
  • Stability
  • Stability Badges page (derived and shaped from the equivalent section in the Node.js documentation)
  • FAQ page
    • I created the "How to handle errors?" FAQ as a starting point for subsequent FAQ contents

---

What's Next?

• About the https://mysql2.js.org domain, it needs the link working before to open a PR.
  • They're going to review the content first before approving the domain.
• Next up, the new challenge is to create all the long-term documentation.
  • That we can work on with the community's help 🤝
• And the most important question:
  • How do you feel about this documentation website initial state? 🙋🏻‍♂️

---

An Overview of the New Sections

• Stability Badges
  • https://wellwelwel.github.io/node-mysql2-website-test/docs/stability-badges
• History
  • https://wellwelwel.github.io/node-mysql2-website-test/docs/documentation/typescript-examples#resultsetheader
• FAQ ("How to handle errors?")
  • https://wellwelwel.github.io/node-mysql2-website-test/docs/faq/how-to-handle-errors
• Website Contributing Guidelines
  • https://wellwelwel.github.io/node-mysql2-website-test/docs/contributing/website

[wellwelwel]

Just some refinements and a Donate following link to https://github.com/sponsors/sidorares 🧑🏻‍🔧

[sidorares]

sorry very busy last few days but I promise I'll give some attention very soon!

[wellwelwel]

sorry very busy last few days but I promise I'll give some attention very soon!

Hey, everything's fine.
Thank you and no worries! 🤝✨

[sidorares]

its live 🎉

Thank you for this amazing effort @wellwelwel ❤️

I'll think about domain later and next steps in improving documentation ( I have few new topics in mind for FAQ ) but this is already looking very very good

[wellwelwel]

Yeah 🎉

The second step would be to remove the "old" docs and examples from /docs and /examples, and then adapt README.md to suggest the website, naturally concentrating/focusing the documentation and examples in just one place.

Still not changing any current documentation

I'd like to get this done before I go on my vacation 🌞

[wellwelwel]

@sidorares , a small suggestion would be to flag the "Use your GitHub Pages website" on repository details:

---

Then:

[sidorares]

done, thanks for the suggestion!