topaz venture
Hi all, name name is Chris, I am the core maintainer for Skeleton (https://www.skeleton.dev/). We provide a design system and component library that currently supports multiple frameworks (React/Svelte). And we've used Astro for our docs site for a little over a year now with the help of integrations like MDX rendering, etc.
Unfortunately we've been really struggling to determine the best manner to selectively segment portions of the page and tailor content to be framework specific. In many cases, the majority of the page content will be the same for all frameworks, just code examples or minor text differences - such as as our Component docs:
https://www.skeleton.dev/docs/components/accordion/react
(jump between each framework tab)
We took what, in hindsight, was a bit of heavy handed approach to solve for this. We actually author each framework "tab" as a separate MDX file. Then have the common frontmatter (title, description, etc) stored in a sibling meta.mdx file. Then stitch it all together. See it in practic here:
https://github.com/skeletonlabs/skeleton/tree/main/sites/skeleton.dev/src/content/docs/components/accordion
As you might suspect, this solution is not scaling well for us. We're doubling the work to maintain React/Svelte docs now and will likely quadruple this effort as we introduce Vue/Solid support in the future. So we're taking a step back to try and reimagine how we handle this.
We've come up with a few ideas:
- Go all in on a route-based approach and conditionally render portions of the pages (like fragments)
- Use a cookie-based approach where users select their preferred framework and the content renders based on this
- Using multi-tabbed preview/code blocks to provide all possible source available with a couple clicks
Each of these methods has their own pros and cons though. Some more significant than others.
- Split routing is great, but we sort of need it arbitrarily from page to page. Only the Components section need it for every instance.
- Cookie-based is easy for users to understand, but we lose the speed of pre-rendered static pages
- And tabbed sections work, but feel very clunky UX-wise. You're constantly having to switch to your favored framework
So we want to open up the issue to the Astro community. See if anyone has gone down this path before. And perhaps provide suggestions or techniques we haven't considered. Perhaps Astro has some neat built-in features for this sort of thing we haven't yet been made aware of. Maybe there's a generalized option that would work regardless of meta-framework, etc.
But generally speaking, these are our goals:
- Make it easy for users to select their framework of choice and persist that from session to session
- Make it easy for users to switch frameworks on demand - as we (the maintainers) use this a lot to confirm feature/content pairity
- Ideally keep pages static - so things like page search, search indexing, and performance all remain top-notch
- We can and do use MDX heavily, so this must remain part of the discussion
- And of course we will be sticking with Astro. It provides so many benefits in so many regards
Feel free to ask any questions about our implementation. But note our docs are open source if you want to view our current implementation:
https://github.com/skeletonlabs/skeleton/tree/main/sites/skeleton.dev
And again you can view the doc site here to see what sections do/don't require framework-specific content:
https://www.skeleton.dev/
violet cypress