docs: import from layerchart using alias #151
Conversation
|
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
Any reason you don't add |
Thanks, and same to you! I loved your talk and looked into Kitbook, although I need to dig in deeper when things calm down (do they ever though 😁). It looks very robust and I see it solving some pain points I've encountered in LayerChart and Svlete UX's docs.
Using different imports between the examples has always been a pain point and even have a note about it in the Getting Started section (which we will be able to remove 🎉)
The alias solution looks great! TBH it's something I meant to investigate as a solution but was concerned going through the top-level index with all it's re-exporting and would be painful for development and not allow Vite to optimize on initial startup (and possibly impact HMR). If it works out for you, I think proceeding with the rest of the examples would be awesome, and we'll just be mindful of any development performance regressions and evaluate solutions as needed. I know barrel index files are always a bundlers worst nightmare and typically frowned upon, but the DX is hard to beat. I used to feel this pain a lot early on in development (first with Snowpack, then early versions of Vite), but I know Vite continues to make big improvements here. Btw, the explicit
That sounds great and I would love to see where each project can learn from one another. I rolled my own docs mostly because I wanted more control over the experience than I could get from other solutions at the time, but it's not without it's own challenges. I have an issue to track some of my ideas on how to improve the docs if you want to see where my head is. Documentation, types, accessibility, and internationalization are always areas that could be improved (along with making great functioning libraries 😁). Most of the docs were in markdown originally (mdsvex with some extra processing) but I encountered challenges with working in markdown with Svelte code examples that outweighed the ergonomic benefits, but some of these are probably from my own ignorance 🤣. I ended up re-writing most back to regular old Svelte files. See the docs issue for more context, but a few of the issues were
Theming is very important, although it's also kind of specific to the implementation. Ultimately it's leveraging Tailwind classes driven by CSS variables and LayerChart's docs are powered by Svelte UX's theming (which is a Tailwind plugin). LayerChart isn't tied to Svelte UX in general (works with other frameworks like Skeleton or shadcn-svelte, or even standalone) but I do treat it as a companion library that complements one another. Personally I would love to piecemeal some of the capability of kitbook (similar to how I leverage sveld ATM) to handle some of the challenging aspects but it might be difficult to fully replace the docs (at least in the relative near future). Speaking of Thanks again for the PR and I would love to proceed with using the alias (and hopefully we don't hit any performance bottlenecks). Svelte UX is going to be the true test 😁 |
Nope, feel free to add! |
Sean, awesome talk! Noticed you were using different imports for your docs than users need to use. I have the same situation in Kitbook and using an alias solves it. So then you can import from
layerchartwhich just happens to be an alias to your lib directory. In mine I do'kitbook': 'src/lib'but in yours I had to do'layerchart': 'src/lib/index.js'. I'm not sure why, but it works. Anyhow you can see how I changed your Arc docs to utilize it. If you like it, you can spread it across the rest of your examples. :)And yes, let's talk more if you ever decide to use Kitbook. There's a some glaring features missing from it like view source code which would be almost trivial to add as I have the raw strings from each component already, I just haven't taken the time to do it. 1 thing at a time you know. But it sure would make it easier for you in some spots like how you're writing your getting started page in html, not markdown.
Oh, and Kitbook has no dark mode support or any theme for that matter and you've blown it out of the water. So that's another thing you might want to see in Kitbook first. Not sure what's important to you.