Docs: Redirects for subpages implemented #10948

jostschmithals · 2017-03-07T13:07:55Z

Related to #10937

Pages reached from outside (for instance via google) are now correctly displayed (with navigation panel and working links),

by redirecting pages with URLs such as the following ones …

... docs/api/objects/SkinnedMesh.html
... docs/manual/introduction/Detecting-WebGL-and-browser-compatibility.html
... docs/api/core/BufferGeometry.html
... docs/manual/introduction/Animation-system.html
... docs/api/renderers/webgl/plugins/LensFlarePlugin.html
... docs/examples/loaders/OBJLoader.html
... docs/api/animation/tracks/QuaternionKeyframeTrack.html

… to their corresponding iframe-URLs (using docs/list.js for mapping):

... docs/#Reference/Objects/SkinnedMesh
... docs/#Manual/Getting_Started/Detecting_WebGL_and_browser_compatibility
... docs/#Reference/Core/BufferGeometry
... docs/#Manual/Next_Steps/Animation_System
... docs/#Developer_Reference/WebGLRenderer.Plugins/LensFlarePlugin
... docs/#Examples/Loaders/OBJLoader
... docs/#Reference/Animation.Tracks/QuaternionKeyframeTrack

looeee · 2017-03-08T11:13:04Z

docs/page.js

+
+                    if ( page[ 1 ] === section + '/' + path ) {  
+
+                        redirectUrl = 'index.html#' 


redirectUrl = 'index.html#'

To be consistent with links from the sidebar this should just be

redirectUrl = '#'

Of course index.html is redundant. Seems that I didn’t see the forest for the trees ;-)

Thanks!

mrdoob · 2017-03-21T20:19:29Z

Test page:
https://rawgit.com/jostschmithals/three.js/redirectDocs/docs/api/objects/SkinnedMesh.html

mrdoob · 2017-03-21T20:20:28Z

Rather than redirecting... How about changing the links so when you click them you end up in the docs?

jostschmithals · 2017-03-21T21:23:15Z

I am not sure whether I understand you correctly(?)

Putting myself in the situation of a programmer searching for “three.js SkinnedMesh” on google I would expect, that a link which leads to a subpage of threejs.org (in this case https://threejs.org/docs/api/objects/SkinnedMesh.html) would work correctly (which is currently not the case).

But I would not have the expectation that a link from forked repositories would automagically work in the same way. So this was not the use case I had in mind.

mrdoob · 2017-03-21T23:12:10Z

But I would not have the expectation that a link from forked repositories would automagically work in the same way. So this was not the use case I had in mind.

No no...

Say that the user ends up in https://threejs.org/docs/api/objects/SkinnedMesh.html. What I'm saying is to change the code so when the user clicks on 'Object3D` on the top-left, the link goes to https://threejs.org/docs/#Reference/Core/Object3D.

jostschmithals · 2017-03-22T13:32:24Z

Thanks for your clarification. I hope that I now understand the direction in which you wanted to point me (but I am not yet sure).

Your suggestion is to make no redirection at all, but to change the links on the subpages level only?

1. Version with redirection

Say that the user ends up in https://threejs.org/docs/api/objects/SkinnedMesh.html.

With my implementation the user should never “end up” in https://threejs.org/docs/api/objects/SkinnedMesh.html, since he is immediately directed to https://threejs.org/docs/#Reference/Objects/SkinnedMesh.

In this way all links (and the “Edit”-button) should work correctly, and the additional advantage would be that coming from google&Co. the navigation panel is always immediately available (collapsed to a hamburger button on small devices) – I guess this is the “normal” behavior a user (who doesn’t need to know about the internal iframes structure) would expect from a modern website.

Since the forwarding to the higher level is done with location.replace() and not with location.href= the browser’s back button should work as expected, too.

Is there a disadvantage/problem with this forwarding solution I have not yet realized?

2. Version without redirection

If we would go without this redirection and “only” fix the links (wouldn’t that be more complicated anyway?), the user would miss the full possibilities of the navigation panel, until he has the idea to click on a link that takes him away from this particular subpage (iframe). This would remind me in an unpleasant way of old fashion HTML frame architectures.

I don’t know, what could be the advantage of doing it without forwarding to the higher level?

mrdoob · 2017-03-22T16:05:07Z

I think my worry is that we're dragging a design mistake...

Currently we have:

https://threejs.org/docs/api/objects/SkinnedMesh.html
https://threejs.org/docs/#Reference/Objects/SkinnedMesh

I think this should just be:

https://threejs.org/docs/api/objects/SkinnedMesh.html
https://threejs.org/docs/#api/objects/SkinnedMesh

This way the redirection code will be much simpler.

jostschmithals · 2017-03-22T19:31:09Z

I think this should just be:
https://threejs.org/docs/api/objects/SkinnedMesh.html
https://threejs.org/docs/#api/objects/SkinnedMesh

I absolutely agree.

As far as I can see there are (at least) two problems with the docs which are existing separately (but the final solution of No.1 depends on whether and how No.2 is solved):

The broken links and missing navigation when coming to a subpage from outside.
The two concurrent link structures which made the existing mapping in index.html much more complex than it should/could be (and which are now also complicating the solution of No.1).

Being new to three.js, I thought that there must be some kind of mystic reason for No.2 which my mind couldn’t grasp 😉 ; therefore I didn’t want to change this all at once and focused on an isolated solution for No.1 instead.

@mrdoob If you want, I would close this issue and work on a solution for No.2 first (synchronizing the two structures and cleaning up the existing code in index.html). After this the solution for No.1 would be indeed much simpler.

@looeee Of course I am also very interested in your opinion and advice, since you have broad experience with the docs.

mrdoob · 2017-03-22T20:50:16Z

Being new to three.js, I thought that there must be some kind of mystic reason for No.2 which my mind couldn’t grasp 😉 ; therefore I didn’t want to change this all at once and focused on an isolated solution for No.1 instead.

Yep yep! I appreciate that.

@mrdoob If you want, I would close this issue and work on a solution for No.2 first (synchronizing the two structures and cleaning up the existing code in index.html). After this the solution for No.1 would be indeed much simpler.

Yes! That would be great! 👍

jostschmithals · 2017-03-23T18:21:36Z

It seems to be much easier than I thought (no synchronizing of the two present structures needed):

If we simply use in index.html the original urls of the iframe-pages and completely forget the conversion into the second url format, all seems to work perfectly, in and from all directions - without any other changes (besides a very simple redirection from the subpages).

There must have been a reason why this second url track with the complex conversion was invented some centuries ago, but it seems that this reason is no longer existent ;)

But now I would like to take the time to make a thorough refactoring (and simplification) of this index.html first before making a new PR.

redirect docs subpages if not in iframe

bcab8a5

looeee reviewed Mar 8, 2017

View reviewed changes

docs redirection, redundant index.html in url removed

fc03da2

jostschmithals mentioned this pull request Mar 21, 2017

documentation #11042

Closed

13 tasks

jostschmithals closed this Mar 23, 2017

This was referenced Mar 24, 2017

Docs: 1. Browser navigation not working; 2. Query strings needed? #11052

Closed

Docs: refactor code to follow style guide #11073

Closed

Docs: index.html refactored #11078

Merged

jostschmithals deleted the redirectDocs branch April 27, 2017 14:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Docs: Redirects for subpages implemented #10948

Docs: Redirects for subpages implemented #10948

Uh oh!

jostschmithals commented Mar 7, 2017 •

edited

Loading

Uh oh!

looeee Mar 8, 2017

Uh oh!

jostschmithals Mar 8, 2017

Uh oh!

mrdoob commented Mar 21, 2017

Uh oh!

mrdoob commented Mar 21, 2017

Uh oh!

jostschmithals commented Mar 21, 2017

Uh oh!

mrdoob commented Mar 21, 2017

Uh oh!

jostschmithals commented Mar 22, 2017 •

edited

Loading

Uh oh!

mrdoob commented Mar 22, 2017 •

edited

Loading

Uh oh!

jostschmithals commented Mar 22, 2017

Uh oh!

mrdoob commented Mar 22, 2017

Uh oh!

jostschmithals commented Mar 23, 2017 •

edited

Loading

Uh oh!

Uh oh!


		if ( page[ 1 ] === section + '/' + path ) {

		redirectUrl = 'index.html#'

Uh oh!

Docs: Redirects for subpages implemented #10948

Docs: Redirects for subpages implemented #10948

Uh oh!

Conversation

jostschmithals commented Mar 7, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

looeee Mar 8, 2017

Choose a reason for hiding this comment

Uh oh!

jostschmithals Mar 8, 2017

Choose a reason for hiding this comment

Uh oh!

mrdoob commented Mar 21, 2017

Uh oh!

mrdoob commented Mar 21, 2017

Uh oh!

jostschmithals commented Mar 21, 2017

Uh oh!

mrdoob commented Mar 21, 2017

Uh oh!

jostschmithals commented Mar 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mrdoob commented Mar 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jostschmithals commented Mar 22, 2017

Uh oh!

mrdoob commented Mar 22, 2017

Uh oh!

jostschmithals commented Mar 23, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jostschmithals commented Mar 7, 2017 •

edited

Loading

jostschmithals commented Mar 22, 2017 •

edited

Loading

mrdoob commented Mar 22, 2017 •

edited

Loading

jostschmithals commented Mar 23, 2017 •

edited

Loading