Skip to content

Create page for deeplinking to a definition #12

@Bartvds

Description

@Bartvds
Collaborator

Create an info page to show info and instructions for a specific definition.

  1. Needs a permanent URL
  2. Can be client side with some JavaScript
  3. Future ready for when we add a browsable content list

Activity

sebastian-lenz

sebastian-lenz commented on Jul 28, 2014

@sebastian-lenz
Member

We somehow forgot this issue while discussing #14. With an index on the homepage we won't get no deeplinks. However there are still the docs floating around. Also on the demo the dependencies of each module are listed but not clickable - mainly cause it's difficult to link to another tab within the list.

My first tryout with the DocPad plugin produced individual pages for each module but was dismissed due to the update problem. Same goes for the documentation update process, see DefinitelyTyped/docs#2.

We could remove the readme page of the documentation and replace it with something like we have in the packe list accordion so we would have both a deeplink for each project and the documentation. But we still have a problem with updating everything. Maybe we should "Find some real hosting" for definitelytyped.github.io?

Bartvds

Bartvds commented on Jul 28, 2014

@Bartvds
CollaboratorAuthor

Ok, long one because it is complicated (as always :)

For the deeplinking we could consider using a hash, like http://definitelytyped.org/#!/foo/bar.d.ts. Maybe do some trickery with pushState API to have it on a dedicated page? (using an index.html in a subfolder).

Main thing is they should be permanent so we don't break inbound links easily.

For hosting we got a new option: I use free hosting on OpenShift for some experiments, it is slowish for serving sites, but it could probably handle a periodic docpad build+publish if we need it; we'd use a webhook on both the main def repo and the site content itself. Then we could still use the github.io hosting for the free & fast bandwidth.

That'd mean we could actually use real pages instead of a #hash. I'll see if I can do a test run for docpad on OpenShift, just to see how long it takes the crummy free gear (unlike Travis it is persistent so saves a lot on reinstalling docpad/grunt from npm each time).

But a problem with the /docs is it takes quite a lot of raw power to generate them, even at 24 cores on Travis it takes many minutes and a shitload of disk space (I think we can cut down a lot by using shared assets and some compression, but still it'll be a far chunk of html). I think the OpenShift hosting will melt-down.

It has been mentioned on an earlier email that we should just get some company to sponsor us. I think we have a good chance a platform like Azure could be hustled for one or two node hosts (small one for a simple express-like webserver, and maybe a fat one for heavy data rebuilds). We sort of left that open while we were looking for candidates to beg stuff from.

sebastian-lenz

sebastian-lenz commented on Jul 28, 2014

@sebastian-lenz
Member

The pushState API would require some server setup (mod_rewrite or similar) we cannot access on GitHub pages I guess, so only the hash/query string option remains. For permanent links real urls seem preferable somehow.

Also delivering the pages through some javascript application will turn the pages invisible for search engines. If I get your idea right for http://definitelytyped.org/#!/foo/bar.d.ts to be indexed we must supply a page http://definitelytyped.org/?_escaped_fragment_=/foo/bar.d.ts (according to this) which would also require server side logic or a page to be rendered beforehand.

The performance required to generate docs could be greatly lowered if we only rebuild the docs that have actually changed. Most of the time we properly won't need to recompile and rebuild every package. Also I've changed TypeDoc to consume less disc space and less CPU cycles. I would like to build a theme that matches the new design of definitelytyped.org, that shares the assets of the website and that renders the package info to the index page.

Azure seems to suggests itself 😉 But you seem to be very talented in using services like Travis and OpenShift for your own purpose, so as long as we can squeeze the pages onto the GitHub server and add some optimizations to the generator we maybe can go with those too.

changed the title [-]Create page for deepinking to a definition[/-] [+]Create page for deeplinking to a definition[/+] on Aug 10, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @Bartvds@sebastian-lenz

        Issue actions

          Create page for deeplinking to a definition · Issue #12 · DefinitelyTyped/definitelytyped.github.io