Buch Konfiguration

In deinem neuen Hyperbook-Projekt findest du eine hyperbook.json Datei. Diese Datei wird verwendet, um dein Hyperbook zu konfigurieren. Hier ist eine Liste von Optionen, die du definieren kannst. Optionen mit einem "*" müssen gesetzt werden.

Hier ist eine Beispielkonfiguration:

{
  "name": "Hyperbook Documentation",
  "description": "Documentation for Hyperbook created with Hyperbook",
  "search": true,
  "qrcode": false,
  "author": {
    "name": "OpenPatch",
    "url": "https://openpatch.org"
  },
  "font": "/fonts/my-font.woff2:90%",
  "logo": "/logo.png",
  "license": "CC-BY-SA",
  "language": "en",
  "basePath": "/hyperbook-github-pages",
  "repo": "https://github.com/mikebarkmin/hyperbook-github-pages/edit/main",
  "colors": {
    "brand": "#FF0000"
  },
  "cloud": {
    "url": "https://cloud.example.com",
    "id": "my-hyperbook"
  },
  "elements": {
    "bookmarks": false
  },
  "links": [
    {
      "label": "Contact",
      "links": [
        {
          "label": "Mail",
          "icon": "📧",
          "href": "mailto:contact@openpatch.org"
        },
        {
          "label": "Twitter",
          "icon": "🐦",
          "href": "https://twitter.com/openpatchorg"
        },
        {
          "label": "Mastodon",
          "icon": "🐘",
          "href": "https://fosstodon.org/@openpatch"
        },
        {
          "label": "Matrix (Chat)",
          "icon": "👨‍💻",
          "href": "https://matrix.to/#/#hyperbook:matrix.org"
        }
      ]
    },
    {
      "label": "OpenPatch",
      "href": "https://openpatch.org"
    }
  ]
}

Lokale Dateien und CDNs

PyIDE verwendet standardmäßig das Pyodide-CDN, weil die vollständige Distribution sehr groß ist. Andere Elemente laden ihre großen Laufzeitumgebungen beim ersten Bedarf herunter und kopieren sie in den Build. Mit cdn kannst du dieses Verhalten ausdrücklich festlegen:

{
  "name": "Mein Hyperbook",
  "elements": {
    "pyide": { "cdn": false },
    "typst": { "cdn": "https://assets.example.com/directive-typst/" },
    "geogebra": { "cdn": true },
    "openscad": { "cdn": false }
  }
}

Diese Option gibt es für pyide, typst, geogebra, openscad, excalidraw, onlineide, sqlide und blockflow. Die Einstellung blockflow gilt für den Player und den Editor. Kiri:Moto verwendet weiterhin seinen externen Dienst.

Die Standard-CDNs sind jsDelivr für Pyodide und Typst, der GeoGebra-Server für GeoGebra, die gehostete Blockflow-App unter blockflow.openpatch.org für Blockflow, die eigenen Pakete von Excalidraw auf UNPKG für Excalidraw und cdn.openpatch.org für OpenSCAD, die Online-IDE und die SQL-IDE. Diese Openpatch-Laufzeitumgebungen verwenden festgelegte Releases, die direkt aus ihrem jeweiligen Repository veröffentlicht werden. Die kleinen Integrationsskripte und Styles von Hyperbook bleiben im Build.

Die Hyperbook-Erweiterung für VS Code enthält diese Laufzeitumgebungen nicht. Ihre Vorschau verhält sich wie ein Build: Elemente mit cdn laden von diesem CDN, die anderen verwenden die Laufzeitumgebungen aus dem Asset-Cache der CLI, den die Erweiterung mitbenutzt. Eine noch nicht heruntergeladene Laufzeitumgebung lädt vom Standard-CDN. Mit Hyperbook: Download Element Runtimes... oder Hyperbook: Download All Element Runtimes lädst du Laufzeitumgebungen in VS Code für die Offline-Vorschau herunter. Setze bei PyIDE zusätzlich elements.pyide.cdn auf false, um die heruntergeladene Laufzeitumgebung zu verwenden.

Eine eigene URL muss auf den Inhalt des Verzeichnisses __hyperbook_assets/directive-<element>/ aus einem lokalen Build zeigen. Behalte die Unterverzeichnisse bei. Bei pyide muss die URL direkt auf die Pyodide-Distribution mit pyodide.js und pyodide-lock.json zeigen, zum Beispiel https://assets.example.com/pyodide/.

Wenn eine eigene CDN-URL eine andere Origin als das Buch hat (andere Domain, anderer Port oder anderes Protokoll), muss der Server für die Laufzeitdateien Anfragen von dieser Origin erlauben, zum Beispiel mit Access-Control-Allow-Origin: *. Lokal eingebundene Dateien und eigene URLs auf derselben Origin wie das Buch benötigen keine zusätzlichen CORS-Header. Wenn das Buch HTTPS verwendet, müssen auch seine CDN-URLs HTTPS verwenden.

hyperbook assets fetch überspringt Laufzeitumgebungen mit aktiviertem CDN. Für hyperbook build --offline müssen diese nicht im Cache liegen. Zum Lesen des Buchs ist weiterhin Zugriff auf das konfigurierte CDN nötig. hyperbook assets fetch --all lädt unabhängig von der Elementkonfiguration alle Laufzeitumgebungen herunter.

Siehe Hosting und Caching, um Downloads zwischen CI-Builds aufzubewahren und Cache-Header für das exportierte Buch festzulegen.