Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support lowercase /current to resolve to current version of library without redirecting #160

Closed
danielcompton opened this issue Oct 18, 2018 · 9 comments

Comments

@danielcompton
Copy link
Contributor

@danielcompton danielcompton commented Oct 18, 2018

There are several use cases for cljdoc URLs. Sometimes you would like to refer to a specific version of the docs, and other times you want to link to whatever happens to the current version of the docs. My gut is that most of the time people want to see what the latest is, though that could be wrong.

My suggestion is that there is a new /current version which is added to the set of version schemes and possibly set it as the default (and canonical #159) URL when you search for it. If you wanted to get a permalink you could still do that as you would now, by picking a different version.

A good example of this is what Postgres does: https://www.postgresql.org/docs/current/static/sql-altertable.html. I actually preferred their previous layout, but this is not too bad either.

screenshot of safari 19-10-18 9-35-51 am

@martinklepsch

This comment has been minimized.

Copy link
Member

@martinklepsch martinklepsch commented Oct 18, 2018

There is https://cljdoc.xyz/d/re-frame/re-frame/CURRENT — but it redirects to the latest version instead of rendering with a canonical attribute. Is that roughly what you had in mind?

@danielcompton

This comment has been minimized.

Copy link
Contributor Author

@danielcompton danielcompton commented Oct 18, 2018

Yeah, I think so, although I'd maybe make it "current" so it's not so in-your-face.

@martinklepsch

This comment has been minimized.

Copy link
Member

@martinklepsch martinklepsch commented Oct 18, 2018

I picked CURRENT to mark it's not an actual version but rather something special.
Happy to also support /current though.

@martinklepsch martinklepsch changed the title Add a /current version for docs? Support lowercase /current to resolve to current version of library Oct 18, 2018
@martinklepsch

This comment has been minimized.

Copy link
Member

@martinklepsch martinklepsch commented Oct 19, 2018

I think in the light of #163 and cljdoc already supporting /CURRENT this can probably be closed?

@danielcompton

This comment has been minimized.

Copy link
Contributor Author

@danielcompton danielcompton commented Oct 19, 2018

They’re related, but separate issues I think?

The action items on this issue (if you agree with the issue) are

  • rename CURRENT to current
  • make current serve the same docs as the latest release version
  • add another version to the version selection page called current
@martinklepsch

This comment has been minimized.

Copy link
Member

@martinklepsch martinklepsch commented Oct 19, 2018

make current serve the same docs as the latest release version

Do you mean without redirecting to the respective version's URL?

They’re related, but separate issues I think?

I'm thinking if we do the /d/group/artifact to current version redirect any /d/group/artifact/current URLs would effectively be succeeded/soft-deprecated by that URL.

@danielcompton

This comment has been minimized.

Copy link
Contributor Author

@danielcompton danielcompton commented Oct 22, 2018

Here's my grand unified theory of URLs that I imagined:

  • /d/group/artifact/current is set as the rel=canonical url base. It serves the same content as whatever is the latest version of the docs, but without redirecting. (1)

  • /d/group/artifact/version serves the docs for that version

  • /d/group/artifact redirects to /d/group/artifact/current

  • On /versions/group/artifact there would be another link for current so that people could get a link to the latest stable version

  • Searches for projects on the homepage would show the latest version, but link to /current

  • On the docs pages for the latest version show "(current)" next to the version in the header.

    If you were on /current then the link to 0.10.6 would take you to the same page but with the versioned URL base. If you were on /0.10.6 then clicking "(current)" would take you to the same page but with the /current URL base. Clicking on whichever link matched the page you were on would take you to the /versions page. (2)

screenshot of safari 23-10-18 8-59-48 am

(1) Note on canonicalization:

It isn't the end of the world if you used the latest version as the canonical URL instead of current, but it does mean that your long tail of documentation is likely to be slightly out of date if Google doesn't crawl you for a while. Using current means that all of your URLs will show up in Google as https://cljdoc.org/d/bidi/bidi/current/api/bidi.router instead of https://cljdoc.org/d/bidi/bidi/2.1.4/api/bidi.router which communicates the intent better to my eyes.

(2) Note on showing "(current):"

I think it would definitely be useful to see at a glance that you're on the current version when you're looking at the docs. This would be the corollary of the warning when you're on the outdated version. Giving links for the opposite page to what you're on (current or version) seems a bit more of tricky UI design challenge to make something that is predictable for users. I'm going for something similar to what Postgres does, but they include the version selection on the same page which makes things a bit easier.

screenshot of safari 23-10-18 9-08-44 am

@martinklepsch

This comment has been minimized.

Copy link
Member

@martinklepsch martinklepsch commented Oct 22, 2018

Ah interesting, I didn't consider you'd actually keep the current bit in the URL.

I'll think a bit more about it but one issue I'm seeing immediately is that the contents may change between versions and so if the bidi.router namespace is deleted this link would 404: https://cljdoc.org/d/bidi/bidi/current/api/bidi.router.

For namespaces this probably isn't going to happen often but articles could be moved around quite a bit.

@martinklepsch martinklepsch changed the title Support lowercase /current to resolve to current version of library Support lowercase /current to resolve to current version of library without redirecting Nov 9, 2018
@martinklepsch

This comment has been minimized.

Copy link
Member

@martinklepsch martinklepsch commented Nov 13, 2018

I'll close this issue for now. I think having /current as URL segment trades link stability for SEO improvements and I'm not sure that's a tradeoff I'm willing to make for now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.