Merge pull request #580 from roipoussiere/music_metadata

Music metadata

website/src/pages/learn/code.mdx

@@ -67,6 +67,9 @@ It is a handy way to quickly turn code on and off.
 Try uncommenting this line by deleting `//` and refreshing the pattern.
 You can also use the keyboard shortcut `cmd-/` to toggle comments on and off.
 
+You might noticed that some comments in the REPL samples include some words starting with a "@", like `@by` or `@license`.
+Those are just a convention to define some information about the music. We will talk about it in the [Music metadata](/learn/metadata) section.
+
 # Strings
 
 Ok, so what about the content inside the quotes (e.g. `"a3 c#4 e4 a4"`)?

website/src/pages/learn/metadata.mdx

@@ -0,0 +1,94 @@
+---
+title: Music metadata
+layout: ../../layouts/MainLayout.astro
+---
+
+import { MiniRepl } from '../../docs/MiniRepl';
+import { JsDoc } from '../../docs/JsDoc';
+
+# Music metadata
+
+You can optionally add some music metadata in your Strudel code, by using tags in code comments:
+
+```js
+// @title Hey Hoo
+// @by Sam Tagada
+// @license CC BY-NC-SA
+```
+
+Like other comments, those are ignored by Strudel, but it can be used by other tools to retrieve some information about the music.
+
+It is for instance used by the [swatch tool](https://github.com/tidalcycles/strudel/tree/main/my-patterns) to display pattern titles in the [examples page](https://strudel.tidalcycles.org/examples/).
+
+## Alternative syntax
+
+You can also use comment blocks:
+
+```js
+/*
+@title Hey Hoo
+@by Sam Tagada
+@license CC BY-NC-SA
+*/
+```
+
+Or define multiple tags in one line:
+
+```js
+// @title Hey Hoo @by Sam Tagada @license CC BY-NC-SA
+```
+
+The `title` tag has an alternative syntax using quotes (must be defined at the very begining):
+
+```js
+// "Hey Hoo" @by Sam Tagada
+```
+
+## Tags list
+
+Available tags are:
+
+- `@title`: music title
+- `@by`: music author(s), separated by comma, eventually followed with a link in `<>` (ex: `@by John Doe <https://example.com>`)
+- `@license`: music license(s)
+- `@details`: some additional information about the music
+- `@url`: web page(s) related to the music (git repo, soundcloud link, etc.)
+- `@genre`: music genre(s) (pop, jazz, etc)
+- `@album`: music album name
+
+## Multiple values
+
+Some of them accepts several values, using the comma or new line separator, or duplicating the tag:
+
+```js
+/*
+@by Sam Tagada
+    Jimmy
+@genre pop, jazz
+@url https://example.com
+@url https://example.org
+*/
+```
+
+You can also add optional prefixes and use tags where you want:
+
+```js
+/*
+song @by Sam Tagada
+samples @by Jimmy
+*/
+...
+note("a3 c#4 e4 a4") // @by Sandy
+```
+
+## Multiline
+
+If a tag doesn't accept a list, it can take multi-line values:
+
+```js
+/*
+@details I wrote this song in February 19th, 2023.
+         It was around midnight and I was lying on
+         the sofa in the living room.
+*/
+```