Linking to Options API/Composition API not working

[PeppeL-G]

I really like that the website uses the same documentation structure for the Options API and the Composition API, and that one switch between them using the switch in the sidebar (upper left corner):

But the choice in the switch is not reflected in the URL, so helping others by sending a link to the docs is annoying (one also has to explain make sure the switch is set to the XXX API each time).

So would appreciate if the the choice of the switch is reflected in the URL.

Thanks!

[xfq]

The advantage is that sharing it with others can reproduce the page's current state. The disadvantage is that the user (at least for me) may want a "cleaner" URL and doesn't want to get these statuses. Although the parameter can be removed manually (just like the UTM parameters, although the purpose is different), it is a bit troublesome.

Another way is to add a "hidden feature" (like ?api=options), but not enable it by default when switching.

[PeppeL-G]

Thanks for the answer.

IMO it simply works wrong as it is now. When I send the URL in my address bar to a friend, my friend should see the very same page when he opens the URL. That's how the web initially worked, and that's how most (all?) users expect it to work.

I know that with the increased usage of client-side JS, more and more websites unfortunately break this functionality (simply because they aren't aware of it, or because they don't have time to properly implement it), but IMO there is not reason to break this. Cleaner URL might be a justification (outside my area of expertise, I'm not an average user), but a very small one IMO. Users copy-pastes URLs? The only time you need short and easy URLs is when you manually need to type them? And that's rare, and in those rare cases a URL shortener service can be used.

Just sharing my thoughts, hopefully we can get input from more before making a decision.

[xfq]

It may be just me, but I don't want the URL to impose a state (Options/Composition API) on me, especially when it is the default behaviour.

That said, I understand your point of view and won't object if this feature is added.

[tony19]

👍 I've been meaning to open this same feature request.

When writing posts about a specific Composition API (e.g., in Stack Overflow), it would be helpful for readers to be able to link directly to that section in the Vue docs, but that's not possible if the link lands on the docs for the Options API. The post would require a note to manually toggle the Composition API docs in the upper left corner and to search for the intended section, which isn't an ideal experience for the post author and users following the link IMO.

[yyx990803]

This is worth fixing. I'm thinking along the lines of introduction.html?api=composition

The reason I haven't implemented it so far is the complication of the following scenario:

• The user has previously configured preference, e.g. Composition API. This is stored in their localStorage.

• They visit a URL with explicit preference query, which overrides their localStorage preference for that page

• Now, what should happen when they navigate to another page? We have two choices:

  1. Revert to the preference from localStorage. i.e. explicit query only affects the first page visited.
  2. Persist the query preference for the entire browsing session. Use localStorage preference only on page load without explicit queries.

  Either way, we probably need a note when the explicit URL query conflicts with the user's localStorage preference.

Another question is whether the query should always be reflected in the URL. If we do it, URLs will be more cluttered, but it ensures that shared URLs will always have the current preference state encoded. If we hide it, most users probably won't even know that the feature exists.

Also, there is a bug in VitePress since it won't render pages with queries during development. It's an easy fix but we will need to wait for a new VitePress release before we can fix this.