+
diff --git a/website/src/config.ts b/website/src/config.ts
index d00e293e..273dc511 100644
--- a/website/src/config.ts
+++ b/website/src/config.ts
@@ -61,6 +61,8 @@ export const SIDEBAR: Sidebar = {
{ text: 'Patterns', link: 'technical-manual/patterns' },
{ text: 'REPL', link: 'technical-manual/repl' },
{ text: 'Pattern Alignment', link: 'technical-manual/alignment' },
+ { text: 'Docs', link: 'technical-manual/docs' },
+ { text: 'Testing', link: 'technical-manual/testing' },
],
},
};
diff --git a/website/src/pages/technical-manual/docs.mdx b/website/src/pages/technical-manual/docs.mdx
index 1333ed77..229b9a63 100644
--- a/website/src/pages/technical-manual/docs.mdx
+++ b/website/src/pages/technical-manual/docs.mdx
@@ -1 +1,71 @@
-TODO
+---
+title: Docs
+layout: ../../layouts/MainLayout.astro
+---
+
+# Docs
+
+The docs page is built ontop of astro's [docs site](https://github.com/withastro/astro/tree/main/examples/docs).
+
+## Adding a new Docs Page
+
+1. add a `.mdx` file in a path under `website/src/pages/`, e.g. [website/src/pages/learn/code.mdx](https://raw.githubusercontent.com/tidalcycles/strudel/main/website/src/pages/learn/code.mdx) will be available under https://strudel.tidalcycles.org/learn/code (or locally under `http://localhost:3000/learn/code`)
+2. make sure to copy the top part of another existing docs page. Adjust the title accordingly
+3. To add a link to the sidebar, add a new entry to `SIDEBAR` to [`config.ts`](https://github.com/tidalcycles/strudel/blob/main/website/src/config.ts)
+
+## Using the Mini REPL
+
+To add a Mini REPL, make sure to import:
+
+```js
+import { MiniRepl } from '../../docs/MiniRepl';
+```
+
+add a mini repl with
+
+```jsx
+
+```
+
+- `client:idle` is required to tell astro that the repl should be interactive, see [Client Directive](https://docs.astro.build/en/reference/directives-reference/#client-directives)
+- `tune`: be any valid pattern code
+- `withCanvas`: If set, a canvas will be rendered below that shows a pianoroll (WIP)
+
+## In-Source Documentation
+
+You can add the in-source documentation for a function by using the `JsDoc` component. Import:
+
+```js
+import { JsDoc } from '../../docs/JsDoc';
+```
+
+Usage:
+
+```jsx
+
+```
+
+- `name`: function name, as named with `@name` in jsdoc
+- `h`: level of heading. `0` will hide the heading. Hiding it allows using a manual heading which results in a nav link being generated in the right sidebar.
+
+### Writing jsdoc
+
+Documentation is written with [jsdoc](https://jsdoc.app/) comments. Example:
+
+```js
+/**
+ * Select a sound / sample by name.
+ *
+ * @name s
+ * @param {string | Pattern} sound The sound / pattern of sounds to pick
+ * @example
+ * s("bd hh")
+ *
+ */
+// implementation of s function
+```
+
+- Before each build, these comments will be rendered into `doc.json` using [jsdoc-json](https://www.npmjs.com/package/jsdoc-json) as a template
+- To regenerate the `doc.json` file manually, run `npm run jsdoc-json`
+- The file is used by the `JsDoc` component to find the documentation by name
+- Also, it is used for the `examples.test.mjs` snapshot test
diff --git a/website/src/pages/technical-manual/testing.mdx b/website/src/pages/technical-manual/testing.mdx
new file mode 100644
index 00000000..eda2fbe0
--- /dev/null
+++ b/website/src/pages/technical-manual/testing.mdx
@@ -0,0 +1,27 @@
+---
+title: Testing
+layout: ../../layouts/MainLayout.astro
+---
+
+# Testing
+
+Strudel uses [vitest](https://vitest.dev/) for testing, with 2 types of testing strategies:
+
+- unit tests for fine grained testing
+- automated snapshot tests for broader testing
+
+## Unit Tests
+
+Each package has a `test` folder where tests are written on a file by file basis, e.g. `util.test.mjs` implements all tests for `util.mjs`.
+
+## Snapshot Tests
+
+Snapshot tests allow testing larger chunks of data. Strudel uses snapshot tests for:
+
+- Example Snippets: `examples.test.mjs`, using snippets under `@example` inside jsdoc comments
+- Example Tunes: `tunes.test.mjs`, using all patterns in `tunes.mjs`
+
+The snapshot (`.snap`) files contain all haps within a certain number of cycles for each tested pattern.
+They allow testing for breaking changes on a larger scale.
+If breaking changes are intentional, the snapshots can be updated with `npm run snapshot`.
+Just make sure to verify that all affected patterns behave as expected.
diff --git a/website/src/pages/technical-manual/tests.mdx b/website/src/pages/technical-manual/tests.mdx
deleted file mode 100644
index 1333ed77..00000000
--- a/website/src/pages/technical-manual/tests.mdx
+++ /dev/null
@@ -1 +0,0 @@
-TODO