diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 24494523a2..19fa25b60f 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -19,5 +19,7 @@ go.sum @antekresic @paulfantom
 /pkg/tests/testdata/ @timescale/o11y-data-platform
 /pkg/tests/upgrade_tests/ @timescale/o11y-data-platform
 
+/docs/mixin @paulfantom 
+
 # helm and kubernetes related parts
 /deploy @cevian @paulfantom @JamesGuthrie
diff --git a/.github/workflows/mixin.yml b/.github/workflows/mixin.yml
index af0934e341..91fa930a4c 100644
--- a/.github/workflows/mixin.yml
+++ b/.github/workflows/mixin.yml
@@ -10,6 +10,10 @@ on:
 env:
   golang-version: 1.18.0
 
+defaults:
+  run:
+    working-directory: docs/mixin
+
 jobs:
   check-mixin:
     runs-on: ubuntu-latest
@@ -31,9 +35,13 @@ jobs:
       run: |
         make generate-helm --always-make
         git diff --exit-code
+      working-directory: .
+
+    - name: download mixtool
+      run: go install -a github.com/monitoring-mixins/mixtool/cmd/mixtool@latest
 
-    - name: download dashboard linter
-      run: go install -a github.com/grafana/dashboard-linter@latest
+    - name: download jsonnetfmt
+      run: go install -a github.com/google/go-jsonnet/cmd/jsonnetfmt@latest
 
     - name: download promtool
       run: |
@@ -43,10 +51,16 @@ jobs:
     - name: download gojsontoyaml
       run: go install github.com/brancz/gojsontoyaml@latest
 
-    - name: check alerts
+    - name: lint
+      run: make lint
+      
+    - name: fmt
+      run: make fmt && git diff --exit-code
+
+    - name: build
+      run: make build
+
+    - name: test alerts
       run: |
         PATH="${PATH}:${GITHUB_WORKSPACE}"
-        make check-alerts
-
-    - name: check dashboards
-      run: make check-dashboards
+        make test
diff --git a/Makefile b/Makefile
index b058cf33d0..19a76b9ac5 100644
--- a/Makefile
+++ b/Makefile
@@ -50,22 +50,5 @@ generate-helm: deploy/helm-chart/templates/prometheus-rule.yaml
 deploy/helm-chart/templates/prometheus-rule.yaml:
 	./scripts/generate-helm-alerts.sh
 
-.PHONY: check-alerts
-check-alerts:
-	# If you don't have promtool, install it with
-	# go install -a github.com/prometheus/prometheus/cmd/promtool@latest
-	promtool check rules docs/mixin/alerts/alerts.yaml
-
-	# If you don't have gojsontoyaml, install it with
-	# go install -a github.com/brancz/gojsontoyaml@latest
-	gojsontoyaml -yamltojson < docs/mixin/alerts/alerts.yaml | jq -e '.groups[].rules[].annotations | has("runbook_url")' 
-
-
-.PHONY: check-dashboards
-check-dashboards:
-	# If you don't have promtool, install it with
-	# go install -a github.com/grafana/dashboard-linter@latest
-	find docs/mixin/dashboards -name '*.json' -print0 | xargs -n 1 -0 dashboard-linter lint
-
 .PHONY: all
 all: build test go-fmt go-lint
diff --git a/docs/mixin/.gitignore b/docs/mixin/.gitignore
new file mode 100644
index 0000000000..09905cd0c3
--- /dev/null
+++ b/docs/mixin/.gitignore
@@ -0,0 +1,3 @@
+/alerts.yaml
+/rules.yaml
+dashboards_out/
\ No newline at end of file
diff --git a/docs/mixin/.lint b/docs/mixin/.lint
new file mode 100644
index 0000000000..0d0e5f6458
--- /dev/null
+++ b/docs/mixin/.lint
@@ -0,0 +1,4 @@
+# Those exclusions are needed due to usage of newer dashboard schema
+exclusions:
+  template-datasource-rule:
+  panel-datasource-rule:
diff --git a/docs/mixin/Makefile b/docs/mixin/Makefile
new file mode 100644
index 0000000000..f9a2689760
--- /dev/null
+++ b/docs/mixin/Makefile
@@ -0,0 +1,32 @@
+JSONNET_FMT := jsonnetfmt -n 2 --max-blank-lines 2 --string-style s --comment-style s
+
+default: build
+
+all: fmt lint build clean
+
+fmt:
+	find . -name 'vendor' -prune -o -name '*.libsonnet' -print -o -name '*.jsonnet' -print | \
+		xargs -n 1 -- $(JSONNET_FMT) -i
+
+lint:
+	find . -name 'vendor' -prune -o -name '*.libsonnet' -print -o -name '*.jsonnet' -print | \
+		while read f; do \
+			$(JSONNET_FMT) "$$f" | diff -u "$$f" -; \
+		done
+
+	mixtool lint mixin.libsonnet
+
+build:
+	mixtool generate all mixin.libsonnet
+
+clean:
+	rm -rf dashboards_out alerts.yaml rules.yaml
+
+test: build
+	# If you don't have promtool, install it with
+	# go install -a github.com/prometheus/prometheus/cmd/promtool@latest
+	promtool check rules alerts.yaml
+
+	# If you don't have gojsontoyaml, install it with
+	# go install -a github.com/brancz/gojsontoyaml@latest
+	gojsontoyaml -yamltojson < alerts/alerts.yaml | jq -e '.groups[].rules[].annotations | has("runbook_url")' 
diff --git a/docs/mixin/README.md b/docs/mixin/README.md
index 00630254bb..46b41cf166 100644
--- a/docs/mixin/README.md
+++ b/docs/mixin/README.md
@@ -1,17 +1,38 @@
 # Promscale Mixin
 
-This file contains instructions on how to use Promscale mixins.
+_This is a work in progress. We aim for it to become a good role model for alerts and dashboards eventually, but it is not quite there yet._
+
+The Promscale Mixin is a set of configurable, reusable, and extensible alerts and dashboards based on the metrics exported by the Promscale. The mixin creates recording and alerting rules for Prometheus and suitable dashboard descriptions for Grafana.
 
 We recommend monitoring your Promscale deployments and include the mixins in this package
 as part of your alerting environment.
 
-## How to use
+## Using pre-built mixin
+
+### How to use
 Promscale alerts are defined [here](alerts/alerts.yaml). Copy the context into a file
 say `promscale_alerts.yaml`.
 
-## Configuring Prometheus
+### Configuring Prometheus
 In the Prometheus configuration file, add `promscale_alerts.yaml` under `rule_files` like
 ```yaml
 rule_files:
   - promscale_alerts.yaml
 ```
+
+## Building mixin
+
+To build it, you need to have mixtool and jsonnetfmt installed. If you have a working Go development environment, it's easiest to run the following:
+
+```console
+$ go install github.com/monitoring-mixins/mixtool/cmd/mixtool@latest
+$ go install github.com/google/go-jsonnet/cmd/jsonnetfmt@latest
+```
+
+You can then build the Prometheus rules files alerts.yaml and rules.yaml and a directory dashboard_out with the JSON dashboard files for Grafana:
+
+```
+$ make build
+```
+
+For more advanced uses of mixins, see https://github.com/monitoring-mixins/docs.
\ No newline at end of file
diff --git a/docs/mixin/alerts/alerts.libsonnet b/docs/mixin/alerts/alerts.libsonnet
new file mode 100644
index 0000000000..6ce4bf55dc
--- /dev/null
+++ b/docs/mixin/alerts/alerts.libsonnet
@@ -0,0 +1,5 @@
+{
+  prometheusAlerts+:: {
+    groups+: std.parseYaml(importstr 'alerts.yaml').groups,
+  },
+}
diff --git a/docs/mixin/config.libsonnet b/docs/mixin/config.libsonnet
new file mode 100644
index 0000000000..48abf5287c
--- /dev/null
+++ b/docs/mixin/config.libsonnet
@@ -0,0 +1,4 @@
+{
+  // This is left to allow possible customization in the future
+  _config+:: {},
+}
diff --git a/docs/mixin/dashboards/dashboards.libsonnet b/docs/mixin/dashboards/dashboards.libsonnet
new file mode 100644
index 0000000000..3cbe8a4d99
--- /dev/null
+++ b/docs/mixin/dashboards/dashboards.libsonnet
@@ -0,0 +1,10 @@
+{
+  grafanaDashboards+:: {
+    'apm-dependencies.json': (import 'apm-dependencies.json'),
+    'apm-home.json': (import 'apm-home.json'),
+    'apm-service-dependencies-downstream.json': (import 'apm-service-dependencies-downstream.json'),
+    'apm-service-dependencies-upstream.json': (import 'apm-service-dependencies-upstream.json'),
+    'apm-service-overview.json': (import 'apm-service-overview.json'),
+    'promscale.json': (import 'promscale.json'),
+  },
+}
diff --git a/docs/mixin/mixin.libsonnet b/docs/mixin/mixin.libsonnet
new file mode 100644
index 0000000000..119d2cdde4
--- /dev/null
+++ b/docs/mixin/mixin.libsonnet
@@ -0,0 +1,3 @@
+(import 'alerts/alerts.libsonnet') +
+(import 'dashboards/dashboards.libsonnet') +
+(import 'config.libsonnet')