Feat/markdown docs

.env

@@ -1,6 +1,3 @@
 VITE_VERSION=$npm_package_version
 VITE_NAME=$npm_package_name
 VITE_FULL_URL=/
-VITE_SANITY_PROJECT=9y5xmu9m
-VITE_SANITY_DATASET=production
-VITE_SANITY_PREVIEW_DATASET=production

content/de/grundlagen/ausgabe.md

@@ -0,0 +1,32 @@
+---
+name: Ausgabe
+subtitle: Text und Werte in der Konsole anzeigen
+image: ../../images/ausgabe.svg
+---
+
+Mit `print` gibst du Text und Messwerte in der seriellen Konsole aus.
+
+## Text ausgeben
+
+Schreibe den Text in Anführungszeichen:
+
+```python
+print("Hallo senseBox!")
+```
+
+<!-- @details -->
+
+Die Ausgabe siehst du in der **Konsole** unterhalb des Editors, sobald die senseBox verbunden ist.
+
+## Werte ausgeben
+
+<!-- @slug werte-ausgeben -->
+
+Du kannst auch Zahlen und Variablen ausgeben. Mehrere Werte trennst du mit Kommas:
+
+```python
+temperatur = 21.5
+print("Temperatur:", temperatur)
+```
+
+Mehr über Messwerte erfährst du unter [Temperatur](doc:sensoren/temperatur).

content/de/grundlagen/schleifen.md

@@ -0,0 +1,43 @@
+---
+name: Schleifen
+subtitle: Code wiederholen
+image: ../../images/schleifen.svg
+---
+
+Schleifen führen Code mehrfach aus.
+
+## Endlosschleife
+
+Eine `while True`-Schleife läuft für immer. So misst die senseBox z. B. dauerhaft:
+
+```python
+import time
+
+while True:
+    print("Messung ...")
+    time.sleep(1)
+```
+
+## Zählschleife
+
+<!-- @alternatives Anzahl -->
+
+### 3 Mal
+
+```python
+for i in range(3):
+    print(i)
+```
+
+### 10 Mal
+
+<!-- @slug zehn -->
+
+```python
+for i in range(10):
+    print(i)
+```
+
+<!-- @details -->
+
+`range(n)` zählt von 0 bis n - 1.

content/de/projekte/wetterstation.md

@@ -0,0 +1,22 @@
+---
+name: Wetterstation
+image: ../../images/wetterstation.svg
+---
+
+Baue eine einfache Wetterstation, die regelmäßig die Temperatur ausgibt.
+
+![Skizze einer Wetterstation](../../images/wetterstation.svg)
+
+### So funktioniert's
+
+1. Schließe den [Temperatursensor](doc:sensoren/temperatur) an.
+2. Öffne den Code mit dem Button unten.
+3. Übertrage ihn auf die senseBox.
+
+```python
+import time
+
+while True:
+    print("Temperatur: 21.5")
+    time.sleep(10)
+```

content/de/sensoren/temperatur.md

@@ -0,0 +1,30 @@
+---
+name: Temperatur
+subtitle: Temperatur und Luftfeuchtigkeit messen
+image: ../../images/temperatur.svg
+---
+
+Der Temperatur- und Luftfeuchtigkeitssensor wird über I²C angeschlossen.
+
+## Temperatur messen
+
+<!-- @slug temperatur-messen -->
+
+Dieses Beispiel liest den Sensor jede Sekunde aus:
+
+```python
+import time
+import board
+
+i2c = board.I2C()
+
+while True:
+    # Sensor auslesen und Wert ausgeben
+    print("Temperatur messen ...")
+    time.sleep(1)
+```
+
+<!-- @details -->
+
+Die Werte kannst du mit [print](doc:grundlagen/ausgabe) ausgeben.
+Weitere Informationen findest du in der [senseBox-Dokumentation](https://docs.sensebox.de).

content/mapping.json

@@ -0,0 +1 @@
+{}

content/sidebar.json

@@ -0,0 +1,33 @@
+{
+  "fallbackLanguage": "de",
+  "sections": [
+    {
+      "id": "grundlagen",
+      "layout": "reference",
+      "icon": "VscLibrary",
+      "title": { "de": "Grundlagen", "en": "Basics" },
+      "description": {
+        "de": "Die wichtigsten Python-Bausteine für die senseBox.",
+        "en": "The most important Python building blocks for the senseBox."
+      },
+      "order": ["ausgabe", "schleifen"]
+    },
+    {
+      "id": "sensoren",
+      "layout": "reference",
+      "icon": "RiSensorLine",
+      "title": { "de": "Sensoren", "en": "Sensors" }
+    },
+    {
+      "id": "projekte",
+      "layout": "cards",
+      "icon": "RiLightbulbFlashLine",
+      "title": { "de": "Projektideen", "en": "Project ideas" },
+      "description": {
+        "de": "Fertige Projekte zum Ausprobieren und Weiterentwickeln.",
+        "en": "Complete projects to try out and build on."
+      }
+    },
+    { "builtin": "api" }
+  ]
+}

docs/analytics-events.md

@@ -157,7 +157,7 @@ back/forward and typed URLs don't fire it (they are `page_view` only).
 | Param     | Values                                                                                                                                     |
 | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
 | `via`     | `user` (clicked in the sidebar), `search` (picked a search result), `code` (from a code hover/help link), `simulator` (from the simulator) |
-| `surface` | `reference` / `ideas` / `api`                                                                                                              |
+| `surface` | The sidebar section id from `content/sidebar.json` (e.g. `grundlagen`) or `api`                                                            |
 | `id`      | The page slug, e.g. `buttons`; absent when navigating to a tab root                                                                        |
 
 ### `docs_search`
@@ -179,8 +179,9 @@ success rate.
 | `code_copy`  | `surface`, `id` | User used the snippet's copy button                                         |
 | `code_paste` | `surface`, `id` | A copied snippet was pasted into the editor (via our own clipboard context) |
 
-- `surface` — `reference` / `ideas` / `api`.
-- `id` — the documentation slug for Reference / Ideas, or the fully qualified
+- `surface` — `reference` (snippets in a section with the reference layout),
+  `ideas` (snippets in a section with the cards layout) or `api`.
+- `id` — the documentation slug for sections, or the fully qualified
   name for API (e.g. `microbit.display.scroll`). Bounded cardinality, but
   large; expect `(other)` in standard reports and use Explorations.
 

docs/content.md

@@ -0,0 +1,185 @@
+# Documentation content
+
+The documentation tabs in the sidebar and everything in them are read from the
+`content/` folder. Content is written in Markdown and bundled with the app at
+build time. To change it, edit the files and redeploy.
+
+```
+content/
+  sidebar.json            # which tabs exist, in which order
+  mapping.json            # optional: API entries → documentation (editor "Help" links)
+  images/                 # images, referenced relatively from Markdown
+  de/                     # one folder per language
+    grundlagen/           # one folder per section (the section id)
+      ausgabe.md          # reference layout: one file per topic
+      schleifen.md
+    projekte/
+      wetterstation.md    # cards layout: one file per card
+  en/
+    grundlagen/
+      ausgabe.md          # translations use the same file names
+```
+
+## Sidebar (`content/sidebar.json`)
+
+```json
+{
+  "fallbackLanguage": "de",
+  "sections": [
+    {
+      "id": "grundlagen",
+      "layout": "reference",
+      "icon": "VscLibrary",
+      "title": { "de": "Grundlagen", "en": "Basics" },
+      "description": { "de": "…", "en": "…" },
+      "order": ["ausgabe", "schleifen"]
+    },
+    {
+      "id": "projekte",
+      "layout": "cards",
+      "icon": "RiLightbulbFlashLine",
+      "title": "Projekte"
+    },
+    { "builtin": "api" }
+  ]
+}
+```
+
+- Each entry in `sections` is a tab, in this order. The **Project** (files) tab
+  always comes last.
+- **`id`** is the folder name and appears in URLs (`/grundlagen/ausgabe`). Use
+  lowercase letters, digits and `-`. `api` and `project` are reserved.
+- **`layout`**:
+  - `reference`: a list of topics. Each topic has entries with code you can
+    drag into the editor.
+  - `cards`: a grid of cards. Each card opens a page whose code can be opened
+    as a project.
+- **`icon`**: one of the names in `src/documentation/sections/icons.ts`. To
+  use another [react-icons](https://react-icons.github.io/react-icons/) icon,
+  add it there.
+- **`title`** / **`description`**: a string, or an object with a value per
+  language.
+- **`order`** (optional): file names without `.md`. Files that aren't listed
+  come after the listed ones, in alphabetical order.
+- **`{ "builtin": "api" }`** shows the API tab, which is generated from the
+  type stubs. Leave it out to hide the tab and the API search results.
+
+### Languages
+
+For each file, the editor uses the version in the user's language
+(`content/<lang>/…`). If there isn't one, it tries the base language (e.g.
+`pt` for `pt-BR`), then `fallbackLanguage`. Partial translations are fine.
+
+## Reference topics
+
+One Markdown file per topic:
+
+````markdown
+---
+name: Schleifen
+subtitle: Code wiederholen
+image: ../../images/schleifen.svg
+compatibility: [microbitV2]
+---
+
+Introduction shown at the top of the topic.
+
+## Endlosschleife
+
+<!-- @slug endlos -->
+
+Text shown before the code. When an entry has code, this text collapses to
+one line until the user clicks "More".
+
+```python
+while True:
+    pass
+```
+
+<!-- @details -->
+
+Only shown after clicking "More".
+
+## Zählschleife
+
+<!-- @alternatives Anzahl -->
+
+### 3 Mal
+
+```python
+for i in range(3): print(i)
+```
+
+### 10 Mal
+
+```python
+for i in range(10): print(i)
+```
+````
+
+- **Front matter**:
+  - `name`: defaults to the file name.
+  - `slug`: defaults to the file name.
+  - `subtitle`
+  - `image`: the topic icon.
+  - `compatibility`: optional.
+- Everything before the first `##` is the **introduction**.
+- Each **`##` heading starts an entry**. The entry's slug is the heading,
+  lower-cased and with umlauts replaced, e.g. `zaehlschleife`.
+- **Directives** are HTML comments placed after an entry heading:
+  - `<!-- @slug name -->` sets the entry's slug. Placed after a `###`
+    alternative heading, it sets that alternative's slug instead.
+  - `<!-- @compatibility microbitV2 -->`
+  - `<!-- @alternatives Label -->`: the `###` headings that follow become
+    choices in a dropdown labelled "Label".
+  - `<!-- @details -->`: the content that follows is shown only when expanded.
+  - Several directives can share one comment:
+    `<!-- @slug a @compatibility microbitV2 -->`.
+- Slugs must be unique within a section. A duplicate entry slug is
+  automatically prefixed with the topic slug.
+
+## Cards
+
+One Markdown file per card:
+
+```markdown
+---
+name: Wetterstation
+image: ../../images/wetterstation.svg
+---
+
+Page content, including `###` headings, images and code.
+```
+
+## Markdown support
+
+| Markdown                             | Result                                                                                                |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `**bold**`, `*italic*`, `` `code` `` | Inline formatting                                                                                     |
+| Lists (`-`, `1.`), `> quote`, `###`  | Lists, quotes, headings                                                                               |
+| ` ```python ` (or no language)       | Code snippet: drag/copy (reference), open (cards)                                                     |
+| ` ```text ` (any other language)     | Plain code text                                                                                       |
+| `![alt](../../images/x.png)`         | Image (path relative to the `.md` file, or `/images/x.png` for `content/images/x.png`, or a full URL) |
+| `[text](https://…)`                  | External link (opens a new tab)                                                                       |
+| `[text](doc:section/slug)`           | Link to a topic, entry or card in a section                                                           |
+| `[text](doc:slug)`                   | Same, searching all sections for the slug                                                             |
+| `[text](api:time.sleep)`             | Link to an entry in the API tab                                                                       |
+
+Inline HTML and tables aren't supported.
+
+## Help links from the editor (`content/mapping.json`)
+
+The editor's autocomplete and signature help show a "Help" link when an API
+entry is mapped to documentation:
+
+```json
+{
+  "time": {
+    "sleep": "grundlagen/warten",
+    "monotonic": { "reference": "grundlagen/zeit", "alternative": "ms" }
+  }
+}
+```
+
+The target is `section/slug`. The `alternative` field preselects a choice in an
+entry that has `@alternatives`.