Dokumentationsintegrationsleitfaden

Übersicht

Die Workspace-Dokumentationswebsite stellt ein maschinenlesbares Manifest (hub-links.json) bereit, das Hub-Dashboard-Bildschirme relevanten Dokumentationsseiten zuordnet. Dies ermöglicht es dem Hub-Frontend, kontextbezogene Hilfelinks direkt in der Dashboard-Benutzeroberfläche anzuzeigen.

Funktionsweise

Das Manifest /hub-links.json ist eine statische JSON-Datei, die von der Dokumentationswebsite bereitgestellt wird. Jeder Eintrag ordnet eine Hub-Bildschirmkennung einer Liste relevanter Dokumentationslinks mit Titeln und Beschreibungen zu.

Manifeststruktur

Das Manifest folgt diesem Schema:

{
  "$schema": "hub-links-schema",
  "version": "1.0.0",
  "screens": {
    "<screen-id>": {
      "title": "Screen Title",
      "description": "What this screen does",
      "links": [
        {
          "title": "Link Title",
          "url": "/path/to/docs-page/",
          "description": "Brief description of the linked page"
        }
      ]
    }
  }
}

Verfügbare Bildschirm-IDs

Bildschirm-ID	Hub-Bildschirm	Links
organizations	Organisationsverwaltung	HUB-Einführung, erste Schritte, Ressourcenzuordnung
tss-list	TSS-Liste (Deutschland)	Deutschland-Übersicht, Neukunden, Schnellstart
clients	Client-Verwaltung	Technische Details, SIGN DE API
transactions	Transaktionsanzeige	Fehlerbehandlung, Fehlercodes
exports	Exportverwaltung	DSFinV-K Einführung, Dashboard-Handbuch
api-keys	API Keyverwaltung	Schnellstart, zu LIVE wechseln
cash-registers	Kassengeräte (Österreich)	Österreich-Übersicht, Schnellstart, SIGN AT API
signers	Unterzeichner (Spanien)	Spanien-Übersicht, Schnellstart

Integration in Hub

Verwendung der HubNavCard-Komponente

Die React-Komponente HubNavCard rendert Dokumentationslinks für einen bestimmten Bildschirm. Sie ruft zur Laufzeit hub-links.json ab und zeigt passende Links mit Hover-Zuständen und Beschreibungen an.

import { HubNavCard } from "@workspace/docs/components";

// In Ihrer Hub-Seitenleiste oder im Hilfepanel:
<HubNavCard hubScreen="tss-list" />

Live-Beispiele

Hier ist die TSS-Verwaltungskarte:

Und die API Key-Karte:

Direkter Abruf (ohne Komponente)

Wenn Sie das Manifest lieber direkt im Hub-Frontend abrufen möchten:

const BASE_URL = "https://workspace.fiskaly.com";

async function getHubLinks(screenId: string) {
  const res = await fetch(`${BASE_URL}/hub-links.json`);
  const manifest = await res.json();
  return manifest.screens[screenId] || null;
}

// Verwendung
const links = await getHubLinks("tss-list");
if (links) {
  links.links.forEach((link) => {
    console.log(`${link.title}: ${BASE_URL}${link.url}`);
  });
}

Neue Bildschirmzuordnungen hinzufügen

Um Dokumentationslinks für einen neuen Hub-Bildschirm hinzuzufügen:

1. Bearbeiten Sie public/hub-links.json im Workspace-Docs-Repository
2. Fügen Sie einen neuen Eintrag unter screens mit einer eindeutigen Bildschirm-ID hinzu
3. Fügen Sie title, description und ein Array von links hinzu
4. Jeder Link benötigt title, url (relativer Pfad) und description
5. Senden Sie einen PR — das Manifest wird automatisch mit der Dokumentationswebsite bereitgestellt

📘URL-Format

Alle url-Werte im Manifest sind relative Pfade (z. B. /hub/introduction/). Beim Einbetten in Hub fügen Sie die Docs-Basis-URL (https://workspace.fiskaly.com) vorangestellt.

💡Lokal testen

Führen Sie den Docs-Entwicklungsserver mit npm run dev aus und greifen Sie auf http://localhost:4321/hub-links.json zu, um Ihre Manifeständerungen zu testen, bevor Sie einen PR einreichen.