Cabal website

Bardur Arantsson spam at
Sun Jun 17 16:15:10 UTC 2018

(Sorry for the duplicate, forgot to send to the list.)

On 2018-06-17 17:37, Imants Cekusins wrote:
>> doesn't seem to be any particular reason to
> require JS for basic functionality on a documentation site.)
> Js is widely used these days. E.g., ReadTheDocs use Js [1].

AFAICT this is only for progressive enhancement, NOT basic "can I read
the text of this website?" functionality. That is the point I'm trying
to make -- there's no need for JS for the basic rendering of a text
website. (However, it's fine to use JS to *enhance* the existing text
website with non-essential, but nice functionality. For example, I
believe ReadTheDocs uses a bit of JS for searching the docs so that you
don't have to have a server do that. That's fine because it's

> Users without Js in the browser may be redirected to a static html
> version of the website.

... which has to be written and maintained separately. So now you have
*two* sites to maintain.

This is why I hinted at using a build-time step to generate static HTML
and re-hydrating the page from there. Please read up on

	ReactDOM.hydrate(element, container[, callback])

if you don't know what hydration/re-hydration is or does.

> This version uses the material design [2] concept. CSS - although
> minimal - came with the library which allowed for faster coding time,
> focusing on the content and functionality.
> For someone with basic React knowledge the website is easy to maintain.

I'm sorry, what's the relevance of this? Documentation written in Sphinx
is ReST or Markdown (which doesn't even require *any* programming
knowledge) and *surely* the content is the primary thing for a
documentation site?!?

(Just FYI, I do know React very well up to and including having
implemented a complex SPA with server-side rendering for the initial
page load. Granted that's with Scala.JS + React, but it's not
substantially different from "plain" React+JS.)

I also know about all the arguments in favor or a SPA-style, so please
spare me the lecture.

> SPA arch allows for faster navigation between the pages. Client side
> rendering frees up the server.

Re-read the bit about hydrating the page from a statically built version
of the page. You have to figure out how to handle sub-pages and links
properly, but this is all doable at build time.

However, the complexity of doing it right is high enough that I don't
see the point over just using e.g. ReadTheDocs, plain Sphinx or whatever.

> The content largely follows the content from the existing website, with
> an attempt at improving content organisation and navigation.

No comment.


More information about the cabal-devel mailing list