[Docs] Migrate docs to SvelteKit and improve them

[BeeMargarida]

Usage example, including component, action, motion, or utility API

Right now our docs are problematic:

• They use an outdated package that also limits what we can do with the docs
• Theming is very limited
• The dark theme is broken
• The deploy process is hacky

Possible implementation - describe how the feature can be implemented

There is already a migration started by @Caladan08 in branch https://github.com/svelteuidev/svelteui/tree/docs-sveltekit-migration, which already has a working version of the current docs. There are still problems to be fixed

• search functionality is buggy
• there's some weird behaviour when switching docs (does not update or the scroll becomes broken)
• the code structure could be improved
• dark theme is broken
• search menu does not allow to focus on elements with Tab (navigation with arrow keys could also be an improvement)
• fix navigation from search menu (it's appending instead of replacing the path)
• fix styling problem with code blocks
• need to change the deploy logic

This can also be an opportunity to re-design and overall improve the experience and content of the docs. We are open to ideas and contributions to improve our docs.

Do you want to contribute this feature and create a pull request

Yes

[Caladan08]

What are some of the bugs in the search functionality? I could try to fix them

[BeeMargarida]

What are some of the bugs in the search functionality? I could try to fix them

If I remember correctly, it was the navigation after the search that was problematic. Sorry, I don't remember details and can't test it out right now

[Caladan08]

OK, let me check

[Caladan08]

I think #337 should fix that issue. Anything else?

[Caladan08]

there's some weird behaviour when switching docs (does not update or the scroll becomes broken)

What is the second problem about?

[BeeMargarida]

What is the second problem about?

If you navigate through the docs you can see, there's some delay in some navigation and the scroll becomes broken in some pages

[BeeMargarida]

Another issue is the sidebar, it's using svelte:window to apply the logic but that should be moved to css with media queries

[Caladan08]

I tried moving the logic to media queries but one problem was that the transition no longer worked. Is that fine?

[BeeMargarida]

I tried moving the logic to media queries but one problem was that the transition no longer worked. Is that fine?

Hum, we can always fix that later

[Caladan08]

If you navigate through the docs you can see, there's some delay in some navigation and the scroll becomes broken in some pages

How exactly is the scroll broken? I could try fixing it

[BeeMargarida]

How exactly is the scroll broken? I could try fixing it

Not sure if it's something that still happens, but if you scrolled through a page then navigated, there was a situation where the page would appear cut, even when scrolling up

[Caladan08]

Not sure if it's something that still happens, but if you scrolled through a page then navigated, there was a situation where the page would appear cut, even when scrolling up

I tried reproducing this error but I still haven't been able to see it. Maybe one of the fixes to the slashes or something fixed it?

[BeeMargarida]

Yap, let's ignore that for now, I don't think I was able to reproduce it as well now

[BeeMargarida]

Updated the issue description with the update on what's missing, so that it does not get lost

[BeeMargarida]

@Caladan08 Dark theme for docs is basically done. Updated the description of the issue with what is missing

[Caladan08]

Relating to the styling in the code blocks, is it fine if we use a highlighter like shiki in the docs? I've tried implementing it and it looked quite good. There was only one problem regarding to the CodeDemo in the Configurator components in @svelteuidev/demos but other than that, it was quite successful

[BeeMargarida]

Relating to the styling in the code blocks, is it fine if we use a highlighter like shiki in the docs? I've tried implementing it and it looked quite good. There was only one problem regarding to the CodeDemo in the Configurator components in @svelteuidev/demos but other than that, it was quite successful

The problem is that it should not be necessary, mdsvex should already do the highlighting. There's some kind of bug happening where it's not applied.

[Caladan08]

Yeah, I noticed the same. Some times, the highlighting would appear but majority of the time, it didn't

[BeeMargarida]

Yeah, I noticed the same. Some times, the highlighting would appear but majority of the time, it didn't

I think it might be a problem with Prism, since we also use it in the demos configurator...perhaps some conflict with the stylings...still have to investigate it further

[BeeMargarida]

@Caladan08 Fixed! 👍 We were not importing the correct highlight stylesheet.
The last things missing are:

1. Fixing ComponentsExample mobile layout appearing before the JS is loaded
2. double check that everything looks good
3. the deploy setup (there are problems with prerendering)

[Caladan08]

The ComponentsExample mobile layout appears because the windowWidth variable's initial value is 0. Let me fix that

[Caladan08]

Even after enabling SSR in the SvelteUIProvider and only using the useStyles() function, there is still a FOUC in the ComponentsExample. I could create two versions of it under different divs and use display: hidden and media queries in the CSS to make it work, but it would be too verbose. Would that work?

[BeeMargarida]

@Caladan08 The solution must be through media queries, since it's the only way without javascript. Yeah, probably a lot of duplicated code. We can always refactor later, though

[Caladan08]

Any idea why the ComponentExamples is rendering in this broken form? Even the Tabs are not being rendered properly. This happened after I removed all the references to <svelte:window> in the Tabs component except in these two lines:

orientation={windowWidth < 1075 ? 'horizontal' : 'vertical'}
variant="unstyled"
position={windowWidth < 1075 ? 'center' : 'left'}

Screen.Recording.2023-04-28.at.10.26.17.PM.mov

[BeeMargarida]

Any idea why the ComponentExamples is rendering in this broken form? Even the Tabs are not being rendered properly. This happened after I removed all the references to svelte:window in the Tabs component except in these two lines:

Ok, that is weird. I'll need to take a closer look, since I'm not sure what is happening. For now, I would remove the desktop style and just set the tabs as in mobile (tabs above the content instead of to the left) and align them to the left perhaps. It can simplify all this logic and still look alright

[BeeMargarida]

@Caladan08 I made some big changes in the structure of the docs. Basically they came from troubles prerendering the docs as they were. I've also tried it out on my own GH pages, it seems like it worked well. I think it's basically done, just ironing out some small stuff.
While I have you here, I would like to say a huge thank you for all your help, it was really big motivator to continue to move forward with this migration. Thank you!! 🙌 🙏 🙌

[Caladan08]

It's been a pleasure working with you as well. Thanks for all the help 👏

[BeeMargarida]

It's been merged and deployed! 🥳 Great work @Caladan08, thank you again!

[Caladan08]

It looks amazing 🎉🎉