[WIP] switch to using Docusaurus to build the site

[alicewriteswrongs]

This PR contains work (started by @ltm!) to switch the Stencil website from a custom, Stencil-based application and build system to using Docusaurus. Docusaurus has built-in (or plugin-based) support for nearly all of what the existing site does and adds a series of new features as well.

At present this is a WIP PR and is not in a mergeable state. The following things are in-place:

• rendering the documentation content w/ light and dark mode support
• automatically generated navigation sidebar
• getting Vercel configured to, uh, build the site correctly!

And the following are partial or not in place:

• porting the existing home and resource pages to React
• the 'contributors' widget we currently show on documentation pages

modifications to our Markdown to render with Docusaurus

Overall we don't need to make many changes to our existing Markdown content to get things to work. The only thing which we really needed to change was to change block quotes like this one:

https://github.com/ionic-team/stencil-site/blob/982edccb2106702a9bf00fe2d043db4aa822ebf9/src/docs/output-targets/custom-elements.md?plain=1#L68-L70

To use 'admonitions' instead, which look like this:

:::note
At this time, components created not using JSX may not be automatically
defined. This is a known limitation of the API and users should be aware of
it
:::

which renders like this:

However, there are also a few things which are really enhancements, like taking advantage of Docusaurus' support for setting a code-block title and automatically translating npm commands to yarn.

what still needs to be done?

The main work remaining is completing the port of the Home page and the Resources page from Stencil / web components to React. Other than that, I think we need to decide how much to modify the default Docusaurus theme used for the documentation content itself (currently it's almost entirely unmodified). We also need to do some sort of check to make sure that all pages in the docs are rendering correctly.

Once we've done those things we just need to delete all the Stencil components!

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated
stencil-site	✅ Ready (Inspect)	Visit Preview	💬 Add your feedback	Jan 24, 2023 at 6:17PM (UTC)