gosling-lang · etowahadams · Sep 27, 2023 · Sep 27, 2023 · Sep 27, 2023 · Sep 27, 2023
diff --git a/.github/workflows/deploy_action.yml b/.github/workflows/deploy_action.yml
@@ -16,7 +16,7 @@ jobs:
           submodules: 'true'
       - uses: actions/setup-node@v1
         with:
-          node-version: '14.x'
+          node-version: '16.x'
       - name: Test Build
         run: |
           if [ -e yarn.lock ]; then
@@ -36,7 +36,7 @@ jobs:
             submodules: true
       - uses: actions/setup-node@v1
         with:
-          node-version: '14.x'
+          node-version: '16.x'
       - name: Test Build
         run: |
           if [ -e yarn.lock ]; then

diff --git a/docs/composition.mdx b/docs/composition.mdx
@@ -1,11 +1,18 @@
 ---
 title: Composition
+description: Visualizations organized into tracks and views. 
 ---
 
 import {TableWrapper} from '@site/react-components/DocComponments/table'
 import GoslingSchema from './assets/gosling.schema.json'
 
-A **`track`** is a unit building block in Gosling which can be represented as a bar chart, a line chart, or an ideogram. For the concurrent analysis of multiple datasets, multiple tracks can be grouped into **`views`** and navigated synchronously. In other words, a view defines the genomic location for all the tracks it contains, and the tracks define the data to be visualized.
+Gosling visualizations are composed from **tracks** and **views**. 
+
+<img src='/img/doc_images/track-view.png' />
+
+A **`track`** is a unit building block in Gosling which can be represented as a bar chart, a line chart, or an ideogram. 
+Multiple tracks can be grouped into together into a **`view`**. A view defines the genomic location for all the tracks it 
+contains, and the tracks define the data to be visualized.
 
 <!-- :pushpin: `mark + channel` :arrow_forward: `one track` :arrow_forward:`tracks` :arrow_forward: `one view` :arrow_forward: `views` :arrow_forward: `a multi-view visualization` -->
 

diff --git a/docs/data.mdx b/docs/data.mdx
@@ -1,5 +1,6 @@
 ---
 title: Data
+description: CSV, GFF3, VCF, BED, JSON, BAM and more!
 ---
 
 import GoslingSchema from './assets/gosling.schema.json';
@@ -27,7 +28,7 @@ including [CSV](#csv-no-higlass-server), [JSON](#json-no-higlass-server), [BigWi
 
 2. **Pre-aggregated Datasets** (HiGlass Server): These datasets are preprocessed for the scalable data exploration and require a HiGlass server to access them in Gosling,
 including [Vector](#vector-require-higlass-server), [Multivec](#multivec-require-higlass-server), and [BEDDB](#beddb-require-higlass-server).
-To learn more about preprocessing your data and setting up the server, please visit the [HiGlass website](https://docs.higlass.io/).
+To learn more about preprocessing your data and setting up the [server](https://github.com/higlass/higlass-server), please visit the [HiGlass website](https://docs.higlass.io/). 
 
 
 ### CSV (No HiGlass Server)

diff --git a/docs/genome-builds.md b/docs/genome-builds.md
@@ -1,7 +1,11 @@
 ---
-title: Genome Builds
+title: Genome 
+description: Specify the the genome your visualization uses. 
 ---
-You can specify genome builds through an `assembly` property (default: `"hg38"`).
+For Gosling to show the correct genomic axis range for your data, you must specify what genome or human genome assembly Gosling should use. 
+
+## Human genome 
+You can specify which human genome assembly your data uses using the `assembly` property (default: `"hg38"`).
 
 ```typescript
 {
@@ -14,4 +18,30 @@ You can specify genome builds through an `assembly` property (default: `"hg38"`)
 ```
 
 Gosling currently supports the following six genome builds: `"hg38"`, `"hg19"`, `"hg17"`, `"hg16"`, `"mm10"`, `"mm9"`, and `"unknown"`.  
+
+## Non-human genomes
+For non-human genomes, you can specify custom chromosome sizes. For example, the E. coli genome has a single chromosome, which has a length of 4641652 bases. 
+``` typescript
+{
+  "assembly": [["chr1", 4641652], ["chr2", 323132]], // two chromosomes, one with length 4641652 nt, one with length 323132
+  "tracks": [{
+    ...,
+  }],
+  ...
+}
+```
+
+You can also specify multiple chromosomes! 
+
+``` typescript
+{
+  "assembly": [["U00096.3", 4641652], []], // The E. coli chromosome name is U00096.3
+  "tracks": [{
+    ...,
+  }],
+  ...
+}
+```
+
+
 When `{"assembly": "unknown"}`, the genomic axes do not display `chrN:` in labels.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -2,99 +2,22 @@
 title: Getting Started
 slug: /
 ---
-We currently support the following ways of using Gosling.
-- [Create Your Visualization in Gosling Online Editor](#create-your-visualization-in-gosling-online-editor)
-- [Load a Gosling Spec From Your Github Gist](#load-a-gosling-spec-from-your-github-gist)
-- [Embed Gosling Component in a HTML File](#embed-gosling-component-in-a-html-file)
-- [Use Gosling.js with React](#use-goslingjs-with-react)
-- [Resources](#resources)
 
-## Create Your Visualization in Gosling Online Editor
-You can visit [Online Editor](https://gosling.js.org) to visualize your data directly in the website.
+Gosling.js is a declarative grammar for interactive (epi)genomics visualization on the Web.
 
-## Load a Gosling Spec From Your Github Gist
-1. To load a spec you first have to create a gist with a file named gosling.js* that specifies the spec.
-1. You can additionally specify a readme.md file to describe your spec.
-1. Also be sure to give your gist a fabulous title. It'll be shown in the gosling editor.
-You can then open your visualization at <a>http://<editor_url>/?gist=<github_username>/<gist_id></a>. 
-<!-- For example, https://gosling.js.org/?gist=flekschas/e6e388332814886d4d714efd0e88093b -->
-For example, https://gosling.js.org/?gist=wangqianwen0418/1cc79f00990806f07b379ae6a7c7b7b3
+To get started with Gosling, we recommend going through the [Create Single Track Visualization Tutorial](/tutorials). Then, you can explore examples in the [online editor](https://gosling.js.org), and start building your own Gosling visualizations using the the grammar and Javascript API parts of the documentation as a reference. 
 
-## Embed Gosling Component in a HTML File
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <link rel="stylesheet" href="https://unpkg.com/higlass@1.11/dist/hglib.css">
-  <script src="https://unpkg.com/react@17/umd/react.production.min.js"></script>
-  <script src="https://unpkg.com/react-dom@17/umd/react-dom.production.min.js"></script>
-  <script src="https://unpkg.com/pixi.js@6/dist/browser/pixi.min.js"></script>
-  <script src="https://unpkg.com/higlass@1.11/dist/hglib.js"></script>
-  <script src="https://unpkg.com/gosling.js@0.9.17/dist/gosling.js"></script>
-</head>
-<body>
-  <div id="gosling-container"/>
-  <script>
-    gosling.embed(
-      document.getElementById('gosling-container'),
-      {
-        "tracks": [{
-          "data": {
-            "url": "https://server.gosling-lang.org/api/v1/tileset_info/?d=cistrome-multivec",
-            "type": "multivec",
-            "row": "sample",
-            "column": "position",
-            "value": "peak",
-            "categories": ["sample 1"]
-          },
-          "mark": "rect",
-          "x": { "field": "position", "type": "genomic" },
-          "color": { "field": "peak", "type": "quantitative", "legend": true },
-          "width": 600,
-          "height": 130
-        }]
-      }
-    );
-  </script>
-</body>
-</html>
-```
+## What is a grammar for visualization?
+Words are combined together into a sentences based on their parts of speech and grammar rules. In a similar way, visual components (such as a coordinate axis, plot markers, and legend) have specific roles and are combined according to certain rules. You probably know these rules without realizing it! People have tried making these rules explicit in what they call a "visual grammar."
 
-## Use Gosling.js with React
+Similarly, *genomic* data visualizations can be understood as being made up of components which follow a set of rules. The **Gosling grammar** formalizes these rules for genomic data visualizations. 
 
-Please visit [gosling-react](https://github.com/gosling-lang/gosling-react) to find detailed instruction on using React.
+How is the Gosling grammar used in practice? A Gosling visualization is defined using a **Gosling specification**, which is a JSON object. The structure and values within this JSON object are determined by the Gosling grammar. See the example below to see how parts of a Gosling specification corresponds to its visualization. 
 
+<img src='/img/spec-vis.png'/>
 
-Beginning with version 0.9.30, Gosling now supports React v18 (You can still use React v16 or v17).
-If you are using a Gosling version prior to 0.9.30, please continue to use React v16.
-
-Install `gosling.js` and its dependent libraries:
+## Javascript API 
 
-```sh
-yarn add gosling.js higlass pixi.js react@16.13.1 react-dom@16.13.1
-```
+**Gosling.js** takes the Gosling specification as an input and creates the visualization defined by it. You can programmatically interact with this visualization using **Javascript API functions**. 
 
-Add the following stylesheet to your base `html` file:
-```html
-<head>
-  <link rel="stylesheet" href="https://unpkg.com/higlass@1.11.3/dist/hglib.css">
-</head>
-```
-
-Use the Gosling.js' react component to visualize your data:
-
-```js
-import { GoslingComponent } from "gosling.js";
-function App() {
-  return (
-    <GoslingComponent spec={yourSpec}/>
-  );
-}
-```
-
-## Resources
-- How to set up your own HiGlass server for private data exploration?
-   - HiGlass Server: https://github.com/higlass/higlass-server
-   - HiGlass Docker: https://github.com/higlass/higlass-docker
-- How to prepare your own HiGlass data?
-   - HiGlass docs for data preparation: https://docs.higlass.io/data_preparation.html
+For example, you can use an API function to make the visualization zoom to a particular genomic position, or you can subscribe to click events in the visualization. This is useful to building your own interactive visualizations with Gosling! 
diff --git a/docs/mark.mdx b/docs/mark.mdx
@@ -1,5 +1,6 @@
 ---
 title: Mark
+description: Basic elements like point, line, bar, text, triangle. 
 ---
 
 

diff --git a/docs/semantic-zoom.mdx b/docs/semantic-zoom.mdx
@@ -1,12 +1,11 @@
 ---
 title: Semantic Zoom
+description: Dynamically switch between different representations
 ---
 
 import {TableWrapper} from '@site/react-components/DocComponments/table'
 import GoslingSchema from './assets/gosling.schema.json'
 
-[:link: source code](https://github.com/gosling-lang/gosling.js/blob/43626eaf21417bf36128a405dceeaa6ee00d0851/src/core/gosling.schema.ts#L278)
-
 ## Why Semantic Zoom
 
 Advanced zooming technique, called Semantic Zooming, allows users to dynamically switch between visual representations upon zooming in and out. 

diff --git a/docs/visual-channel.mdx b/docs/visual-channel.mdx
@@ -1,5 +1,6 @@
 ---
 title: Visual Channel
+description: Associate marks to data and change how marks look. 
 ---
 
 import {TableWrapper} from '@site/react-components/DocComponments/table'

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -19,20 +19,8 @@ module.exports = {
     },
     colorMode: {
       defaultMode: 'light',
-      disableSwitch: true,
+      disableSwitch: false,
       respectPrefersColorScheme: false,
-      switchConfig: {
-        darkIcon: '🌙',
-        lightIcon: '🌞',
-        // React inline style object
-        // see https://reactjs.org/docs/dom-elements.html#style
-        darkIconStyle: {
-          marginLeft: '2px',
-        },
-        lightIconStyle: {
-          marginLeft: '1px',
-        },
-      }
     },
     algolia: {
       appId: 'BH4D9OD16A',
@@ -57,6 +45,7 @@ module.exports = {
           position: 'left',
         },
         { to: 'tutorials/', label: 'Tutorials', position: 'left' },
+        { to: 'usage/', label: 'Usage', position: 'left' },
         { to: 'examples/', label: 'Examples', position: 'left' },
         { to: 'themes/', label: 'Themes', position: 'left' },
         { to: 'about/', label: 'About', position: 'left' },
@@ -141,22 +130,12 @@ module.exports = {
       ],
       copyright: `Copyright © ${new Date().getFullYear()} Harvard. Built with Docusaurus.`,
     },
-    metadatas: [
+    metadata: [
       { name: 'twitter:card', content: 'summary' },
       { name: "twitter:title", content: "Gosling" },
       { name: 'twitter:description', content: 'A Grammar-based Toolkit for Scalable and Interactive Genomics Data Visualization' },
       { name: 'twitter:image', content: 'https://user-images.githubusercontent.com/9922882/109852545-e05f3400-7c22-11eb-90f3-7371e4ddeb42.png' }
     ],
-    gtag: {
-      trackingID: 'UA-96954979-4',
-      // Optional fields.
-      anonymizeIP: true, // Should IPs be anonymized?
-    },
-    googleAnalytics: {
-      trackingID: 'UA-96954979-4',
-      // Optional fields.
-      anonymizeIP: true, // Should IPs be anonymized?
-    },
   },
   presets: [
     [
@@ -179,6 +158,16 @@ module.exports = {
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
         },
+        gtag: {
+          trackingID: 'UA-96954979-4',
+          // Optional fields.
+          anonymizeIP: true, // Should IPs be anonymized?
+        },
+        googleAnalytics: {
+          trackingID: 'UA-96954979-4',
+          // Optional fields.
+          anonymizeIP: true, // Should IPs be anonymized?
+        },
       },
     ],
   ],

diff --git a/package.json b/package.json
@@ -15,10 +15,10 @@
     "tag_version": "docusaurus docs:version"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.0.0-beta.3",
-    "@docusaurus/plugin-google-analytics": "^2.0.0-beta.3",
-    "@docusaurus/plugin-google-gtag": "^2.0.0-beta.3",
-    "@docusaurus/preset-classic": "^2.0.0-beta.3",
+    "@docusaurus/core": "2.4.3",
+    "@docusaurus/plugin-google-analytics": "2.4.3",
+    "@docusaurus/plugin-google-gtag": "2.4.3",
+    "@docusaurus/preset-classic": "2.4.3",
     "@mdx-js/react": "^1.6.21",
     "antd": "^4.19.5",
     "clsx": "^1.1.1",

diff --git a/sidebarDocs.js b/sidebarDocs.js
@@ -7,13 +7,20 @@ module.exports = {
     {
       type: 'category',
       label: 'Grammar',
-      collapsed: false,
+      link: {
+        type: 'generated-index',
+        title: 'Grammar',
+        description:
+          'This is the documentation for the Gosling grammar. If this is your first time looking at the docs, we recommend starting with Composition, Mark, and Visual Channel.',
+        keywords: ['guides'],
+      },
+      collapsed: true,
       items: [
+        'composition',
         'data',
-        'genome-builds',
         'mark',
         'visual-channel',
-        'composition',
+        'genome-builds',
         'user-interaction',
         'semantic-zoom',
       ],