Wide-ranging docs update

[wycats]

This ended up being a huge change in the infrastructure and content of the guides.

It's not really possible to enumerate everything, because not much of the original infrastructure remains.

Some infrastructure notes:

• updates Vite and Vitepress to the latest versions
• moved a lot of the configuration in src/.vitepress into standalone packages
• gave standalone packages their own infrastructure; this infrastructure is ok for now, but I hope that the whole situation is temporary and most of the packages can move out of the repo entirely (it's stuff like MarkdownIt plugins that power code snippets, demos and stuff like that)
• standalone packages use .tsx for Vue components and CSS modules for CSS (with a bit of custom glue that injects the styles when the components are used, since these standalone packages can't use the main site's Vite setup)
  • ultimately, I had enough trouble with Volar working reliably that I'd prefer to stick to .tsx files
• moved from Sass to PostCSS, and created a few custom extensions to simplify things
• moved from hsl colors to oklch colors
• started adopting CSS layers
• deleted a bunch of duplicate or unused CSS; there's still a bunch of CSS consolidation to do, but the current situation is much better
• completely re-did the custom blocks to use fenced containers, eliminating a formatting problem with ::: containers: you need to add extra space inside of the ::: to avoid the contents of the container getting slurped into the ::: header
  • the new infrastructure just uses normal code fences starting with ```md, which correctly syntax highlights and gets the correct prettier behavior.
• Changed the syntax for pulling in external code demos (to !(./relative/file.ts#region)). I tried to use ![#region](./relative/file.ts), which had the nice property of supporting "jump to definition", but repurposing image syntax also triggered lint and build-time warnings.
• Consolidated all of the MarkdownIt extensions to use shared parsing infrastructure; this should be extracted into its own library (as writing a custom parser extension for Markdown is fairly baroque, but quite powerful!)
• Migrated from mermaid diagrams to d2 diagrams, and wrote a MarkdownIt extension that shells out to the d2 binary. Wrote a script to automatically fetch the d2 binary in prepare so it's transparently present.
• Added general-purpose demo infrastructure that allows contributors to author full-fledged demos in a directory and import them into documentation with one line. The infrastructure uses the Sandpack Vue library and implements an demo UI that's appropriate for embedding right into the docs.
• Began work on a Monaco-based tutorial system that works like the demo infrastructure, but designed to be used as a full-screen experience (like https://learn.svelte.dev/tutorial/welcome-to-svelte). This infrastructure largely works, but we still need to implement a navigation UI. It may make sense to just ship the full-screen experience as a Playground in the meantime, which would require less work to complete.

Content notes:

• Added a "stylistic conventions" section and consolidated way too many visual styles into fewer styles
• Adjusted the TS/JS switching logic and created a global TS/JS switcher that you can use even if you're not currently looking at code that has TS and JS versions
• Made it possible to mark sections of prose as "TS only", which are affected by the TS/JS switcher.
• Reworked the fundamentals guides to account for improvements in pedagogy that we've learned over time
• Created a new "philosophy" section for "universal reactivity" and "validation", which were getting in the way of the main flow. These sections are useful for people very interested in understanding the rationale, but interspersing them with understanding the fundamental concepts was confusing.
• Expanded "Our Guiding Principle" to explain the concept using code examples.
• Fleshed out the Fundamentals sections considerably (cells, functions, resources)
• Added more Deep Dive sections and generally fleshed out content for intermediate readers

There are many, many more changes, but these are some important ones that come to mind.

---

Final note: The infrastructure around the standalone packages isn't amazing, especially around dev-mode experience. This is because I focused primarily on extracting code into packages that could be ultimately extracted out of the repo, and Vite doesn't make it easy for in-repo packages to have a seamless development experience.

I plan to completely extract the bulk of these packages to their own repo pretty soon, so I decided not to try to fight Vite's perspective on this and live with the fact that the process for modifying the standalone packages isn't totally seamless. TL;DR instead of writing a bunch of contributor guides for contributing to these packages, I plan to move them into their own repositories with their own workflow.

[vercel]

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

Name	Status	Preview	Comments	Updated
docs	✅ Ready (Inspect)	Visit Preview		Mar 22, 2023 at 2:52AM (UTC)