Add sanctuary-def and sanctuary-type-classes

[Shard]

At the moment, it's a bit of a mishmash keeping tabs on the docs between sanctuary,sanctuary-def and sanctuary-type-classes. It would be nice if we could bring the docs for these projects into the site.

One way we could do this is by adding a new "button bar" element fixed to the top right that could be used to toggle between the library docs. We could also put other things like the search from #11 next to it to have it look sort of like:

One thing to consider will be how to handle doclinks. We could build out each repo as it's own static page and just link them together like that, or we can be a bit fancy using javascript and have prefixs for url hashes so that you could link to Z.map with https://sanctuary.js.org/#Z.map.

[davidchambers]

I'm very keen to have the documentation for all the projects on the website! I'm not sure how the links to the various projects should be presented, but I'd like to use the following URL structure:

Function	URL
S.encase	https://sanctuary.js.org/#encase
$.Number	https://sanctuary.js.org/sanctuary-def/#Number
Z.Monoid	https://sanctuary.js.org/sanctuary-type-classes/#Monoid

For consistency we could have /sanctuary/#name redirect to /#name.

How does this sound, @Shard? If we decide to use this URL structure we could even publish documentation for the other projects before solving the UI challenge.

[Shard]

The only thing to consider with such a structure is that it would require server side url rewriting if we wanted to make it single page as opposed to static pages. If we were to move the hash back like:

Function	URL
S.encase	https://sanctuary.js.org/#encase
$.Number	https://sanctuary.js.org/#sanctuary-def/Number
Z.Monoid	https://sanctuary.js.org/#sanctuary-type-classes/Monoid

Makes it so just building out two new static pages won't be viable but it would mean the site could be single page while remaining a static bundle.

I'm personally in favor of integrating the docs as a "single page app" as it would pave the way for a very powerful search functionality that's entirely client side.

[davidchambers]

I'm personally in favor of integrating the docs as a "single page app" as it would pave the way for a very powerful search functionality that's entirely client side.

It seems to me this would still be possible if each project were to have its own index.js. We could create a JSON file for each project containing the names and types of its functions, and have some shared JavaScript code which fetches the JSON files and provides a cross-project search widget.

[Shard]

We could do the search with JSON, I guess I was assuming we would leverage transcribe and use the HTML itself as the datasource.

Although it still leads to that issue of we can do it static now and have them has 3 separate pages, but if we want to make it one page it will need to include some nginx/apache rules to properly handle the routing.

If that's doable then I'm happy to starting look at getting the static pages generated for santucary-def and sanctuary-type-classes at the paths you originally linked and we can look at the OPA changes down the road along with other things such as search/UI.

[davidchambers]

I've realized it's essential for each project to have its own HTML document. Otherwise the projects will share a single namespace for fragment identifiers. This uniqueness constraint would be rather limiting. The Sanctuary source code, for example, currently includes this line:

//. ## API

It is rendered as sanctuary.js.org/#api.

We'd need to change the heading to something like ## Sanctuary API, and the fragment identifier would change from #api to the less elegant #sanctuary-api.

Furthermore, the uniqueness constraint would be difficult to enforce; when working on project X one would need to consider all the headings used in projects V, W, Y, and Z.

[Shard]

I think this issue could be alleviated with a little routing and parsing in a OPA but I can propose something after we get the docs for Type Classes and Def generated as Plain HTML.

For the UI of linking between the docs, I think it would help a lot to have something over nothing so Ill try a couple of solutions and we can review that to see what works and what doesn't.

So does generating two new html files based on your original urls sound good @davidchambers

[davidchambers]

So does generating two new html files based on your original urls sound good

Absolutely. I imagine generate makes assumptions that will no longer be correct once the script is being used to generate HTML documents for multiple projects, so will require tweaking.