docs: create a docs config #12410
docs: create a docs config #12410
Conversation
|
|
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 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 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 |
|
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 |
|
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. |
|
happy to add an |
|
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 |
It scales a hell of a lot better than manually keeping stuff in sync!
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 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 |
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
<!-- @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 |
|
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 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
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?
We could add linting to prevent this. It does make the setup a bit more complicated for the authors of the individual repos though
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 |
|
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: 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 |
@dummdidumm and @dominikg both preferred this setup. It's probably a bit easier to ask folks like
eslint-plugin-svelte,vite-plugin-svelte, etc. to add this new file than rename all their existing files especially when their directory structure doesn't necessarily match how they'd like to group links in the sidebar. This is what vitepress does. Docusaurus supports both ways. The inspiration for this file format was taken from vitepress. You could specify sidebar text for a page here, but if not defined we can look for it in the frontmatter