[Docs] Migrate docs to SvelteKit and improve them

BeeMargarida commented 1 year ago

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

[X] search functionality is buggy
[X] there's some weird behaviour when switching docs (does not update or the scroll becomes broken)
[X] the code structure could be improved
[x] dark theme is broken
[x] search menu does not allow to focus on elements with Tab (navigation with arrow keys could also be an improvement)
[x] fix navigation from search menu (it's appending instead of replacing the path)
[x] fix styling problem with code blocks
[x] 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

1yne commented 1 year ago

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

BeeMargarida commented 1 year ago

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

1yne commented 1 year ago

OK, let me check

1yne commented 1 year ago

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

1yne commented 1 year ago

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

What is the second problem about?

BeeMargarida commented 1 year ago

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 commented 1 year ago

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

1yne commented 1 year ago

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

BeeMargarida commented 1 year ago

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

1yne commented 1 year ago

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 commented 1 year ago

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

1yne commented 1 year ago

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 commented 1 year ago

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

BeeMargarida commented 1 year ago

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

BeeMargarida commented 1 year ago

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

1yne commented 1 year ago

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 commented 1 year ago

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.

1yne commented 1 year ago

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

BeeMargarida commented 1 year ago

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 commented 1 year ago

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

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

1yne commented 1 year ago

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

1yne commented 1 year ago

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 commented 1 year ago

@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

1yne commented 1 year ago

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'}

https://user-images.githubusercontent.com/94300963/235209041-41fcc6fb-9a37-424c-b09e-544cd18b4f67.mov

BeeMargarida commented 1 year ago

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 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 commented 1 year ago

@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!! :raised_hands: :pray: :raised_hands:

1yne commented 1 year ago

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

BeeMargarida commented 1 year ago

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

1yne commented 1 year ago

It looks amazing 🎉🎉

svelteuidev / svelteui