---

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://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/`)

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://codeberg.org/uzu/strudel/src/branch/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

<MiniRepl client:idle tune={`note("a3 c#4 e4 a4")`} />

```

- `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

- `punchcard`: if added, a punchcard / pianoroll visualization is renderd

- `drawTime`: time window for drawing, defaults to `[0, 4]`

- `canvasHeight`: height of the canvas, defaults to 100px

See `mini-notation.mdx` for usage examples

## 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

<JsDoc client:idle name="bandf" h={0} />

```

- `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.

- `hideDescription`: if set, the description will be hidden

### 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

How does Strudel do its [Testing](/technical-manual/testing)?