1---
2title: Docs
3layout: ../../layouts/MainLayout.astro
4---
5
6# Docs
7
8The docs page is built ontop of astro's [docs site](https://github.com/withastro/astro/tree/main/examples/docs).
9
10## Adding a new Docs Page
11
121. add a `.mdx` file in a path under `website/src/pages/`, e.g. [website/src/pages/learn/code.mdx](https://codeberg.org/uzu/strudel/src/branch/main/website/src/pages/learn/code.mdx) will be available under https://strudel.cc/learn/code/ (or locally under `http://localhost:4321/learn/code/`)
132. make sure to copy the top part of another existing docs page. Adjust the title accordingly
143. To add a link to the sidebar, add a new entry to `SIDEBAR` to [`config.ts`](https://codeberg.org/uzu/strudel/src/branch/main/website/src/config.ts)
15
16## Using the Mini REPL
17
18To add a Mini REPL, make sure to import:
19
20```js
21import { MiniRepl } from '../../docs/MiniRepl';
22```
23
24add a mini repl with
25
26```jsx
27<MiniRepl client:idle tune={`note("a3 c#4 e4 a4")`} />
28```
29
30- `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)
31- `tune`: be any valid pattern code
32- `punchcard`: if added, a punchcard / pianoroll visualization is renderd
33- `drawTime`: time window for drawing, defaults to `[0, 4]`
34- `canvasHeight`: height of the canvas, defaults to 100px
35
36See `mini-notation.mdx` for usage examples
37
38## In-Source Documentation
39
40You can add the in-source documentation for a function by using the `JsDoc` component. Import:
41
42```js
43import { JsDoc } from '../../docs/JsDoc';
44```
45
46Usage:
47
48```jsx
49<JsDoc client:idle name="bandf" h={0} />
50```
51
52- `name`: function name, as named with `@name` in jsdoc
53- `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.
54- `hideDescription`: if set, the description will be hidden
55
56### Writing jsdoc
57
58Documentation is written with [jsdoc](https://jsdoc.app/) comments. Example:
59
60```js
61/**
62 * Select a sound / sample by name.
63 *
64 * @name s
65 * @param {string | Pattern} sound The sound / pattern of sounds to pick
66 * @example
67 * s("bd hh")
68 *
69 */
70// implementation of s function
71```
72
73- Before each build, these comments will be rendered into `doc.json` using [jsdoc-json](https://www.npmjs.com/package/jsdoc-json) as a template
74- To regenerate the `doc.json` file manually, run `npm run jsdoc-json`
75- The file is used by the `JsDoc` component to find the documentation by name
76- Also, it is used for the `examples.test.mjs` snapshot test
77
78How does Strudel do its [Testing](/technical-manual/testing)?