doc: add section about metadata

website/src/config.ts

@@ -70,6 +70,7 @@ export const SIDEBAR: Sidebar = {
       { text: 'Patterns', link: 'technical-manual/patterns' },
       { text: 'Pattern Alignment', link: 'technical-manual/alignment' },
       { text: 'Strudel vs Tidal', link: 'learn/strudel-vs-tidal' },
+      { text: 'Music metadata', link: 'learn/metadata' },
     ],
     Development: [
       { text: 'REPL', link: 'technical-manual/repl' },

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 `@title` or `@license`.
+Those are just a convention to define some information about the music. We will talk about it in the *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,30 @@
+---
+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 like this:
+
+```
+// @license: CC BY-NC-SA 4.0 https://creativecommons.org/licenses/by-nc-sa/4.0/
+// @author: Felix Roos
+// @details: Inspired by Friendship - Let's not talk about it (1979) :)
+```
+
+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/).
+
+Available tags are:
+- `@title`: music title
+- `@by`: music author(s), separated with comma, eventually followed with a link in `<>` (ex: `@author john doe <https://example.com>`)
+- `@license`: music license
+- `@details`: some additional information about the music
+- `@url`: web page related to the music (git repo, soundcloud link, etc.)
+- `@genre`: music genre (pop, jazz, etc)
+- `@album`: music album name