stencila/designa

Component for inter-page navigation

Opened this issue · 2 comments

nokome commented

Issue #13 proposes to add a Javascript TOC component for a within-page navigation. When a CreativeWork is part of a Collection then it would be useful to have cross-page navigation.

The dir codec in Encoda generates a root.json file at the top level - this includes all the properties for the works in the collection (including nested collections ie directories) except for content (which is encoded as HTML). This file could be fetched and used to

{
  "type": "Collection",
  "parts": [
    {
      "name": "CHANGELOG",
      "type": "Article",
      "title": "Untitled",
      "authors": [],
      "meta": {
        "depth": 0
      }
    },
    {
      "name": "CONTRIBUTING",
      "type": "Article",
      "title": "Untitled",
      "authors": [],
      "meta": {
        "depth": 0
      }
    },
    {
      "name": "README",
      "type": "Article",
      "title": "Untitled",
      "authors": [],
      "meta": {
        "depth": 0,
        "main": true
      }
    },
    {
      "type": "Collection",
      "name": "src",
      "parts": [
        {
          "type": "Collection",
          "name": "codecs",
          "parts": [
            {
              "type": "Collection",
              "name": "csv",
              "parts": [
                {
                  "name": "README",
                  "type": "Article",
                  "title": "Untitled",
                  "authors": [],
                  "meta": {
                    "depth": 3,
                    "main": true
                  }

Each HTML file also includes the meta data for the parts of the collection, including the depth attribute. This would allow some Javascript to know where to fetch root.json relative to the current page e.g.

  <head>
    <title>Untitled</title>
    <meta charset="utf-8">
    <script type="application/ld+json">
      {
        "@context": "http://stencila.github.io/schema/stencila.jsonld",
        "name": "CONTRIBUTING",
        "type": "Article",
        "authors": [],
        "meta": {
          "depth": 0
        }
      }
    </script>
nokome commented

Just to clarify the intent here. We need a tree nav for getting between pages as is often seen on the left of documentation sites e.g. this one in the Gatsby docs

image

nokome commented

Just to point out that the encoda docs are now being self-generated (ie. getting generated by encoda itself) and producing a root.json file: https://stencila.github.io/encoda/root.json and JSON-LD in <meta> as above. You can click through to the docs for individual codecs from the "Formats" table. Should be useful for testing this, and other components.