(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 non-essential.)
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. Regards,