Use jekyll-rtd-theme and split 1.1-DRAFT into files per section

[stain]

As suggested in #65 we need a better theme that shows the examples well/wide, and that has good navigation between sections.

This pull request changes the RO-Crate website to use the jekyll-rtd-theme by https://rundocs.io/

It has the same look-and-file as https://readthedocs.org/ with a table of content on the left - but working with Jekyll/Markdown instead of transitioning to Python/Sphinx/RST. It seems like quite an improvement for RO-Crate in terms of readability and navigation:

You can try it on https://stain.github.io/ro-crate/1.1-DRAFT/

[stain]

To improve navigation I split out into multiple files with section numbering in TOC. For instance root data entity is a separate page.

Some caveats with this theme:

1. index.md / README.md in a folder is used mainly to add top-level categories and only navigable from the breadcrumbs - I therefore added an about page which is kind of repeated as abstract on the top-level 1.1/ root but including a list of subpages.
2. All folders are shown in sidebar, including old drafts. This would get messy, so I added an exclude: true patch
3. One of the jekyll plugins is adding github links like @stain to text starting with @ - obviously @graph is not meaning a github user! Work-around - using `` backtick quotes
4. I seem to have to copy that bit [RFC1234]: http://example.com/RFC1234 URL list at bottom into every Markdown file. Obviously each of the pages only refer to a couple of those links but I've not trimmed them down.

I had to rearrange some of the section headings as before it was all under a massive Contextual entities. I tried to update all internal links that now go across pages now, but I may have got some wrong. Check if it makes sense.

I only restructured the new 1.1-DRAFT/ (to be 1.1/) so the question is what to do with the older single-page 0.2 and 1.0 - it seems they render kind-of OK, and I found a way to exclude them from the side-bar, so I suggest leaving them as-is. An alternative would be to is to save them as HTML with the old theme from https://stain.github.io/ro-crate/1.0/ - One important thing is to ensure the 1.0 permalinks and internal links still work - therefore I would not want to split up these as the section #headings would then move.

In this style we could also move some of the frontpage homepage stuff to subpages, e.g. "Implementations" and "Community". I would also add "Specifications" to list the older versions there.

Now we should not really merge this PR until we are agreed to release 1.1 as this would "promote" the "1.1-DRAFT" to the top-level menu. I would use that exclude mechanism again to hide all except the current version.

[stain]

In #65 @ljgarcia suggested trying just-the-docs which looks really nice and modern in comparison:

However I found this a bit cumbersome. I have to annotate parent in each of the "child" pages - the navigation hierarchy does not have to match file system. (In screenshot only "RO-Crate structure" page appear correctly). This is arguably more flexible, e.g. the exclude thing is built in, and you can add additional sidebar links.

Biggest drawback for me was that the internal section headings don't appear on the left and has to be added with a classical {:toc} as in the screenshot. This is a great feature of readthedocs-style themes that we need, at least for the contextual entities pages which we would otherwise have to split into even smaller pages, but that would ruin some of the flow (e.g. Organization is after Person)

[ljgarcia]

It looks nice, indeed an improvement. I tried the testing version provided by @stain and all links I tried worked for me. I like the previous and next buttons at the end of the page. What I am not so sure is the pencil icon on the top right. Do you want to encourage editions (via fork/PR) that directly? I do not expect much people will use this option, not sure if needed.

There is also a sort of blink when navigating with the menu. When changing to another menu item, the page is re-loaded and I can see like a shadow of the logo. I guess it goes to the top of the menu but then immediately moves to where the menu was clicked. It is not a real issue so if it comes from the template I would leave it but maybe worth to have a quick look at it.

I tried it out in Windows 10, Firefox and Chrome.

[ptsefton]

Agree with @ljgarcia - looks good. IS there a way to get it as a single file without the navigation chopping it up into pages? Not sure if this is an issue?

[stain]

Discussed in call 2020-09-24 where it was agreed with @ptsefton @dgarijo @CaroleGoble @stain and the silent majority to change the theme.

1.1 is however in review for another week (see #97), so I'll merge this so reviewers can edit the splitted files; after setting the "exclude" flags so 1.1-DRAFT does not dominate and merging #93