Adding custom chart docs (#50)

* adding custom chart docs

* add env variable

* adjusting self hosting config docs

* fixing a few britishisms

docs/get-started/exploring-data/dashboards.mdx

@@ -196,4 +196,4 @@ To learn more about adding filters to your dashboards, check out our guide on [u
 
 ## 6. Share your dashboard
 
-You might want to share your dashboard with other people in your organisation. You can do this by copying the URL (or by pressing on the 🔗 button).
+You might want to share your dashboard with other people in your organization. You can do this by copying the URL (or by pressing on the 🔗 button).

docs/references/custom-charts.mdx

@@ -0,0 +1,143 @@
+import CustomChartsDropDown from './assets/custom-charts-drop-down.png';
+import HeatmapCustomChart from './assets/heatmap-custom-chart.png';
+import BubblePlotCustomChart from './assets/bubble-plot-custom-chart.png';
+
+# Custom charts
+
+Custom charts are available in Beta for those that want additional customization and an extended library of charts. 
+The charts are powered by [vega-lite](https://vega.github.io/vega-lite/examples/) - the link will take you to some example galleries of what you can build using this powerful charting library. 
+This includes heat maps, bubble plots, box plots and more.
+
+:::info
+
+Custom visualizations in Lightdash are a Beta feature which means we have limited documentation and support. We may also change the way these options work in the future.
+
+:::
+
+## Enabling Custom Charts
+
+Custom charts need to be manually enabled in your project. Contact support for help!
+
+## Getting Started
+
+The general steps to create a custom chart are as follows:
+
+1. Return the data you need for your chart as normal using the Lightdash UI to select relevant dimensions and metrics.
+2. Head to the chart configuration options, in the drop down, you should see an option for custom charts as long as it has been enabled.
+
+<img
+  src={CustomChartsDropDown}
+  width="707"
+  height="354"
+  style={{ display: 'block', margin: '0 auto 20px auto' }}
+/>
+
+3. You will see two tabs in the Configure chart section, one for Config, and one for Data. The Data tab should show the data you have in your results table in a JSON format, ready to be ingested by the Vega Lite config you supply in the Config tab.
+4. Add the config you need for your desired chart!
+
+Below are some simple examples to show you how to get started with your first custom charts. 
+
+Note that if you are building from Vega-Lite examples, **remove the `data` object** from the chart config, as Lightdash automatically maps your results table to the visualization.
+
+### Bar chart
+
+You can already do this with presets in Lightdash, but it's a simple example you should be able to get working quickly.
+
+1. Return a dataset including one dimension, alongside a count for that dimension.
+2. Add the below to the Config tab, replacing the fields with the relevant field names from the Data tab.
+
+```json
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
+  "mark": "bar",
+  "encoding": {
+    "y": {
+      "field": "users_unique_users",
+      "type": "quantitative"
+    },
+    "x": {
+      "field": "users_job_title",
+      "type": "ordinal"
+    }
+  }
+}
+```
+
+### Heatmaps
+
+Heatmaps can currently only be created using the Custom Charts feature. The following example shows how to build a simple heatmap that conveys the number of issues created in a Github repository over time.
+
+1. Return a dataset with two dimensions, and one metric.
+2. Add the below to the Config tab, replacing the fields with the relevant field names from the Data tab.
+
+```json
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
+  "mark": "rect",
+  "encoding": {
+    "y": {
+      "field": "github_daily_date_day_of_week_index",
+      "type": "ordinal",
+      "title": "Day of Week"
+    },
+    "x": {
+      "field": "github_daily_date_week",
+      "type": "temporal",
+      "title": "Week"
+    },
+    "color": {
+      "field": "github_daily_issues_created_num_total",
+      "type": "quantitative",
+      "aggregate": "sum",
+      "title": "Issues Created"
+    }
+  }
+}
+```
+
+You should output a heatmap with the standard Vega-Lite settings that looks like the one below:
+
+<img
+  src={HeatmapCustomChart}
+  width="1007"
+  height="354"
+  style={{ display: 'block', margin: '0 auto 5px auto' }}
+/>
+
+### Bubble Plots
+
+Bubble plots build on top of standard scatter plot visualizations, by allowing you to adjust the size of a given point based on the output of a field. Here's one looking at some Healthcare data.
+
+1. Return a dataset with one dimension, and three metrics.
+2. Add the below to the Config tab, replacing the fields with the relevant field names from the Data tab.
+
+```json
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
+  "mark": "point",
+  "encoding": {
+    "x": {
+      "field": "outpatient_charges_sum_total_paid",
+      "type": "quantitative"
+    },
+    "y": {
+      "field": "outpatient_charges_sum_number_services",
+      "type": "quantitative"
+    },
+    "size": {
+      "field": "outpatient_charges_diff_avg_estimate_vs_avg_payment",
+      "type": "quantitative"
+    }
+  }
+}
+```
+
+Below is the Bubble Plot generated from the code above! Experiment with further Vega-Lite settings to adjust things like Bubble size, colour and general formatting.
+
+<img
+  src={BubblePlotCustomChart}
+  width="707"
+  height="354"
+  style={{ display: 'block', margin: '0 auto 20px auto' }}
+/>
+

docs/self-host/customize-deployment/environment-variables.mdx

@@ -26,6 +26,7 @@ This is a reference to all environment variables that can be used to configure a
 | `LIGHTDASH_PIVOT_TABLE_MAX_COLUMN_LIMIT`     | Configure maximum number of columns in pivot table                                                                                                                                                            |           | `60`                                                            |
 | `GROUPS_ENABLED`                             | Enables/Disables groups functionality                                                                                                                                                                         |           | `false`                                                         |
 | `AUTH_ENABLE_OIDC_LINKING`                   | Enables/Disables linking the new OIDC(aka SSO) identity to an existing user if they already have another OIDC with the same email                                                                             |           | `false`                                                         |
+| `CUSTOM_VISUALIZATIONS_ENABLED`              | Enables/Disables custom chart functionality                                                                                                                                                                   |           | `false`                                                         |
 
 Lightdash also accepts all [standard postgres environment variables](https://www.postgresql.org/docs/9.3/libpq-envars.html)
 

docs/snippets/using-explores.mdx

@@ -115,7 +115,7 @@ You can read more about [configuring your charts here](/references/chart-types).
 
 ### Step 5: Save your chart
 
-Saved Charts allow you to save a specific chart or visualisation so you can share it or revisit it again in future.
+Saved Charts allow you to save a specific chart or visualization so you can share it or revisit it again in future.
 
 When you open a saved chart, it will always update to display the latest data in your database.
 

sidebars.js

@@ -232,6 +232,7 @@ module.exports = {
                     },
                     items: [
                         'references/chart-types',
+                        'references/custom-charts',
                         {
                             type: 'doc',
                             id: 'get-started/exploring-data/dashboards',