⚠️ No Changeset found

Latest commit: 6f731dc

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Not sure I'm a fan of this approach. It adds a bunch of busywork and makes it much harder to understand the ordering of docs (I now have to keep looking back between my file tree and one of a dozen config.json files).

The original thinking was that the docs site would have the flexibility to control where and how things are imported, so if for some reason @dominikg refuses to structure the vite-plugin-svelte docs in a way that allows the entire directory to be imported, svelte.dev can create the correct structure and import individual files.

This seems like a step backwards.

If we want to have the file order be consistent with how it's in the JSON we can just revert the renaming changes. I like the JSON structure because it's much more robust and it puts the repository on control of what is displayed. I don't want to handle that within the svelte.dev repo, that would be very brittle and prone to accidental breakage because people might forget that svelte.dev is relying on certain files to be at certain places. If each repository has a well-defined meta.json that a) increases the likelyhood of contributors to know that something else is relying on this and b) puts the repos on control of what is displayed in what order. It also makes the logic in the svelte.dev repository a bit simpler.

I don't buy it. There's no reason that a maintainer (and which maintainers are we talking about, exactly?) would refuse to adhere to some common file structure but would be fine adhering to some common config.json format while going rogue elsewhere. Surely it's preferable to have consistency across repos?

tldr: I'm against this change, file-based structure is superior

Reiterating to my previous argument on kit repo, in my company, we have a config based nav.js(inspired from bun docs). They hired a 3rd party contractor to redo the documentation. He changed the documentation well enough, but forgot to update the nav.js, which caused a lot of broken links and complaints. This would've been avoidable if the config was auto-generated from the file structure. I made a PR to copy svelte docs structure pretty much as is, and now any changes to docs are always in-sync without human intervention

This is also likely to happen at some point to us. There's only so much vigilance one can have

i don't take an opinion to how the vite-plugin-svelte docs are presented on the omnisite, where in the sidebar they go or in which order they are. What I do not want is to have to rename files that have existed for a long time and have external and internal references like faq.md to 10-faq.md just to bring them into an order for the omnisite. If the site wants to order it, thats perfectly fine, but why use filenames for that (and vite-plugin-svelte isn't the only repo affected).

happy to add an omnidocs directory with numbered symlinks to accomodate that scheme though, as already mentioned here sveltejs/vite-plugin-svelte#942 (comment)

But to be clear, i don't think that using the filesystem as host for this metadata scales well, and the numbering scheme on svelte docs is a bit confusing ( why is it 98-reference, or why are there multiple files starting with 21 in it etc).

A defined metadata file (we can even add a json schema, validate it and automate) is a lot more robust and offers more features than a single filename/directorystructure could.

I also never suggested that svelte or kit docs change their preferred scheme, in fact i would keep the current filenames and just add the json on top so omnisite has an easier way to consume the content with a single pipeline - which again is possible with a metadata file but not if we force all repos to adhere to one omnisite preferred structure

i don't think that using the filesystem as host for this metadata scales well

It scales a hell of a lot better than manually keeping stuff in sync!

What I do not want is to have to rename files that have existed for a long time

Why is the age of the file relevant? Git understands renames

so you are saying that when we rename faq.md to 10-faq.md github is not going to 404 when links try to open it but redirect to 10-faq.md ?

because due to its age, there are a some references out there and i don't want to just cut them off. vite-plugin-svelte logs one, its in the sveltekit docs, and public sites too.

Git, not GitHub. The history would be preserved. If someone is linking directly to one of those files, then it would surely be preferable if the file in question linked to the docs site:

<!-- https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md -->
Moved to [svelte.dev](https://svelte.dev/docs/vite-plugin-svelte/faq).

GitHub does somewhat follow file renames now. It takes an extra click and is a bit annoying, but it's much better than it used to be.

I don't really care which route we go. We could make this work like Docusaurus and support both schemes, but it's extra implementation work on the site side and will make it take longer to get things working and be more complicated. The other compromise option might be to keep the config file, but revert the file renames. We should also loop in @ota-meshi since eslint-plugin-svelte has about 70 docs files (@ota-meshi the question here is if you prefer to have links in the sidebar nav ordered by renaming files to include a prefix or by creating a config file which lists the files in the order that they should appear.)

Whatever we decide, I'm also about to head out on vacation and probably won't have time to make it work before I leave especially if we want to go the Docusaurus route of supporting multiple setups. But maybe @PuruVJ might be interested in keeping the ball rolling on this site setup stuff so Rich and Simon can stay mostly focused on wrapping up Svelte 5?

@PuruVJ your argument about things getting out of sync doesn't really "count", because if you rename a file in a way that doesn't adhere to the omnisite you also break stuff. So you can break stuff with each approach - in other words this is not a good argument in favor or against it.

I still prefer the meta.json file because it's a stable adapter between two moving targets. It's much nicer for me to create a meta.json at https://github.com/sveltejs/language-tools/tree/master/docs rather than reorganizing all that stuff. And what about repositories that only have a readme? I feel like a meta.json offers more flexibility and robustness in the future.

So you can break stuff with each approach - in other words this is not a good argument in favor or against it.

I guarantee we will waste a bunch of time on the slow feedback loop of CI a) failing because things got out of sync, making us spend time figuring out what changed and how to correctly update it, or b) worse, not failing, because a new file was added without a corresponding entry in config.json, which maybe we'll notice in time but maybe not.

And what about repositories that only have a readme?

<!-- @include git:sveltejs/some-package/README.md -->

I feel like we have very different ideas still in our heads about how this all should look like, where is that include coming from now that the docs are controlled by the repositories and they don't live within the svelte.dev repo?

where would that include live? in a markdown file in the omnirepo site or a new /docs/index.md file in the source repo?

Didn't know github now allows you to follow renames, thats cool.

I feel like we have very different ideas still in our heads about how this all should look like, where is that include coming from now that the docs are controlled by the repositories and they don't live within the svelte.dev repo?

I think folks have always had different ideas and that's not new 😆 Both approaches have their benefits and that's why Docusaurus supports both. The question is if it's worth that overhead for us

Didn't know github now allows you to follow renames, thats cool.

To expand on my earlier comment, you can see an example here where it says "Renamed from documentation/docs/11-link-options.md (Browse History)". I'm not sure if that's enough to sway you?

I guarantee we will waste a bunch of time on the slow feedback loop of CI a) failing because things got out of sync, making us spend time figuring out what changed and how to correctly update it, or b) worse, not failing, because a new file was added without a corresponding entry in config.json, which maybe we'll notice in time but maybe not.

We could add linting to prevent this. It does make the setup a bit more complicated for the authors of the individual repos though

And what about repositories that only have a readme?

I think we'll have to handle those a bit differently than docs directories, so I don't think it weighs in favor for or against either proposed setup

unfortunately it looks like it does not link to the new name when hitting a renamed link https://github.com/dominikg/test-rename-link/blob/main/README.md (the file has been renamed to README-renamed.md)

Does that matter that much? I did a search for "vite-plugin-svelte/tree/main/docs" on Google and got 0 results and a search for it on GitHub and didn't find any results that weren't from vite-plugin-svelte

it's blob, not tree. There aren't that many results, thats true but it's not 0, and possibly more for other repos that have been around longer than vite-plugin-svelte.

ultimately if we want the omnisite to be translatable in a friendly way, we'll end up commiting the md files pulled from the source repos (or even the intermediary structure with the output of shiki-twoslash) to the omnisite repo and build from that, so that build job, combined with a discord notification would give us enough attention. And it doesn't even matter if its json or filename scheme for that feedback loop and sync issues. But webhooks and automations give us enough control i believe.

We didn’t have much of these concerns last year, where we pretty much ruined all back links to GitHub. No one complained about broken GitHub links at all, for svelte itself. We’re far less likely to receive complains for the smaller packages

On Fri, 12 Jul 2024 at 9:39 PM, Dominik G. @.***> wrote:

it's blob, not tree. There aren't that many results, thats true but it's not 0, and possibly more for other repos that have been around longer than vite-plugin-svelte.

ultimately if we want the omnisite to be translatable in a friendly way, we'll end up commiting the md files pulled from the source repos (or even the intermediary structure with the output of shiki-twoslash) to the omnisite repo and build from that, so that build job, combined with a discord notification would give us enough attention. And it doesn't even matter if its json or filename scheme for that feedback loop and sync issues. But webhooks and automations give us enough control i believe.

— Reply to this email directly, view it on GitHub #12410 (comment), or unsubscribe https://github.com/notifications/unsubscribe-auth/ALMH4F5UL5SNTZH52326FYDZL75SPAVCNFSM6AAAAABKXNRNFSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMRVHA4TQNJVGE . You are receiving this because you were mentioned.Message ID: @.***>

Most can be updated on GitHub. I think the only two I noticed that people might come across in the future are these two on Reddit below: https://www.reddit.com/r/sveltejs/comments/15iw59w/how_to_debug_svelte_apps/ https://www.reddit.com/r/sveltejs/comments/134m27z/noob_question_documentation_mentions_putting_scss/

It's good we're thinking through how to avoid breaking links, but I wonder if the amount of work required here is worth it when it's just a couple of links. The nice thing is that this problem will pretty much permanently go away soon because in the future people will link to https://svelte.dev/docs/tools/vite-plugin-svelte/faq or whatever the link ends up being and then if it's ever renamed we can properly handle it with a 301 since it will be served via a website we control rather than GitHub

I think I'm coming around to using a file system based convention, like it's currently done for the Svelte/Kit repos. I'm ok with reorganizing the few docs in the other repos.

It seems like that's where the consensus is, so I'll close this