Use Parcel to build website; use MDX to write docs

[alexeyraspopov]

Semiotic website, derived from the separate repo, has been using react-scripts (aka Create React App) to run and build the website. While CRA works decently for single-page apps, Semiotic docs require very different benefits and features for us to be able to easily write new docs and guides.

Given how existing guides are structured, we need a way to write text content in Markdown with occasional need to plug in some interactive examples and related code snippets. It would be quite easy to immediately suggest using things like https://docusaurus.io since that's what they were built for. However, I strongly believe that unique website design makes the product (framework in our case) more recognizable and identifiable. Most importantly, existing design is easy enough to read through, so we can keep it. The main thing, the main capability that I'd like us to borrow from frameworks like Docusaurus is the ability to write Markdown with interactive examples. This is where https://mdxjs.com comes into play.

We already have Parcel in the project, which appears to be quite useful for the thing we want. Replacing react-scripts with parcel we not only improve the docs website building time and size but also can easily start using MDX-js without doing any config magic: it only takes a plugin to be installed.

In this PR you can find an example of migrating Line Chart guide from JS to MDX. What's amazing abount MDX is that we still keep the original JS file to hide some technical details and data required for running examples, so the actual guide content is just about its topic.

In order to migrate an existing JS guide, create an .mdx file with the same name next to it, and update docs/src/App.js to use MDX file directly:

-import AreaChart from "./guides/AreaChart"
+import AreaChart from "./guides/AreaChart.mdx"

Whatever <MarkdownText ... you can find in the original JS file can be safely copied to the MDX file. It is just markdown after all. The way how interactive examples are defined in that JS file (look for <DocumentFrame ...) can also be copied directly but you need to ensure that there all necessary imports added to the beginning of MDX file (see LineChart.mdx for examples).

When you pull this PR:

• Make sure to run yarn install in the root and in docs
• Run yarn website:start from the root
• Open localhost:1234 in the browser

Other improvements:

• React v17 and React Router v6 to run the website
• Prettier config is changed to hard wrap markdown content at 100 width (to improve raw text readability)

Things to finish in this PR:

• [x] Make docs use latest semiotic code
• [x] Index pages for Guides/Examples/APIs that have small images and links
• Update layout to ensure proper scroll position when nav link is used (need to check if there is better way to do it with React Router v6) EDIT: can make it separately
• [x] Move existing markdown files (placed in docs/public/assets/markdown) to docs/src and import via MDX
• If possible, move all the dependencies to a single root package.json EDIT: can be done separately

[vercel[bot]]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/nteract/semiotic/8LFUnK69SEHLs6tGLvpSV7Uj5rti
✅ Preview: https://semiotic-git-parceldocs-nteract.vercel.app

[willingc]

FYI: Vercel's current settings

Happy to make any changes to this for you too.

[alexeyraspopov]

@willingc, seems like current setup points to the old docs that were the part of this repo before. Quite confusing, I know. Let's change the config to use yarn website:build as a build command and docs/build as the output directory.

[alexeyraspopov]

Also, probably it would be better to use semiotic.nteract.io to preview what's in main branch, so PRs don't override it all the time

[alexeyraspopov]

Seems like deploy is failing for now because it is unable to find semiotic version. However, there is another thing that keeps failing for me locally, and it has an issue opened https://github.com/parcel-bundler/parcel/issues/7090. I guess a solution going to be either to open a pr in element-resize-event or just get rid of this dependency.

[alexeyraspopov]

@emeeks @willingc finally got preview working 🎉 For some reasons the preview doesn't fallback to index.html when I refresh the page on any route, but we can investigate it separately. This PR should be good to go

[willingc]

@alexeyraspopov Love this! Thank you. Going to merge and we can clean up any details in other PRs.