Vercel

Wenn Ihre Website auf Vercel bereitgestellt wird, können Sie Ihre Jamdesk-Dokumentation unter /docs auf Ihrer eigenen Domain bereitstellen. Dafür gibt es zwei Möglichkeiten, die beide dasselbe Ergebnis liefern:

• Option A: vercel.json-Rewrites — kein Code erforderlich, funktioniert mit jedem Framework. Die meisten Projekte sollten hiermit beginnen.
• Option B: Edge Middleware — für Websites, die bereits Edge Middleware verwenden und Jamdesk in derselben Datei integrieren möchten.

Voraussetzungen

• Ein auf Vercel bereitgestelltes Projekt
• Ihre Jamdesk-Subdomain (in den Dashboard-Einstellungen zu finden), mit aktivierter Option Host at a subpath
• Ihre benutzerdefinierte Domain, die im Dashboard registriert und verifiziert wurde

Option A: vercel.json-Rewrites

Ein Rewrite kann ändern, wohin eine Anfrage weitergeleitet wird, aber keinen Anfrage-Header hinzufügen. Daher enthält jedes Ziel stattdessen einen öffentlichen Marker, ?jd_proxy=1, der Jamdesk mitteilt, dass die Anfrage über Ihren Proxy eingegangen ist. Jamdesk entfernt ihn vor dem Rendern; Ihre Besucher sehen ihn nie.

Erstellen oder bearbeiten Sie vercel.json im Stammverzeichnis Ihres Projekts und ersetzen Sie YOUR_SLUG durch Ihre Jamdesk-Subdomain:

{
  "rewrites": [
    { "source": "/docs", "destination": "https://YOUR_SLUG.jamdesk.app/docs?jd_proxy=1" },
    { "source": "/docs/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/docs/:path*?jd_proxy=1" },
    { "source": "/_next/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_next/:path*" },
    { "source": "/_jd/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_jd/:path*?jd_proxy=1" }
  ]
}

/_next/:path* benötigt keinen Marker – es handelt sich um einen Pfad für statische Assets, den Jamdesk niemals schützt. Wenn Ihre Website keine Next.js-App ist, enthält sie keine eigenen /_next/-Dateien. Das Rewrite ist daher weiterhin korrekt: Jede Anfrage unter diesem Pfad wird einfach an Jamdesk weitergeleitet.

Dieselben vier Regeln funktionieren bei Next.js-Projekten auch in next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  async rewrites() {
    return [
      { source: "/docs", destination: "https://YOUR_SLUG.jamdesk.app/docs?jd_proxy=1" },
      { source: "/docs/:path*", destination: "https://YOUR_SLUG.jamdesk.app/docs/:path*?jd_proxy=1" },
      { source: "/_next/:path*", destination: "https://YOUR_SLUG.jamdesk.app/_next/:path*" },
      { source: "/_jd/:path*", destination: "https://YOUR_SLUG.jamdesk.app/_jd/:path*?jd_proxy=1" },
    ];
  },
};

export default nextConfig;

Leiten Sie auch Ihre Dateien im Stammverzeichnis weiter

robots.txt, sitemap.xml, llms.txt und llms-full.txt befinden sich im Stammverzeichnis der Domain außerhalb von /docs. Ohne diese Dateien können Suchmaschinen und KI-Agenten Ihre Dokumentation nicht entdecken. Wenn Jamdesk das Stammverzeichnis Ihrer Domain verwaltet, fügen Sie vier weitere Regeln hinzu:

{
  "rewrites": [
    { "source": "/robots.txt", "destination": "https://YOUR_SLUG.jamdesk.app/robots.txt?jd_proxy=1" },
    { "source": "/sitemap.xml", "destination": "https://YOUR_SLUG.jamdesk.app/sitemap.xml?jd_proxy=1" },
    { "source": "/llms.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms.txt?jd_proxy=1" },
    { "source": "/llms-full.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms-full.txt?jd_proxy=1" }
  ]
}

Bereitstellen und überprüfen

Stellen Sie das Projekt mit vercel --prod bereit (oder pushen Sie es in Ihr verbundenes Git-Repository). Öffnen Sie anschließend https://yoursite.com/docs und sehen Sie sich den Seitenquelltext an. Überprüfen Sie zwei Punkte:

1. <link rel="canonical"> verweist auf Ihre Domain, nicht auf YOUR_SLUG.jamdesk.app
2. Es gibt kein <meta name="robots" content="noindex">

Wenn einer der Punkte nicht stimmt, fehlt einem Rewrite der Marker ?jd_proxy=1 – siehe Warum der Marker wichtig ist.

Option B: Edge Middleware

Wenn Sie bereits Edge Middleware verwenden, setzen Sie dort den Anfrage-Header X-Jamdesk-Forwarded-Host, anstatt den Marker zu verwenden. Die beiden Signale sind gleichwertig. Wählen Sie diese Option nur, wenn Sie die Routing-Logik lieber in bereits von Ihnen gepflegtem Code behalten möchten.

Erstellen Sie eine Datei middleware.ts im Stammverzeichnis Ihres Projekts und ersetzen Sie YOUR_SLUG durch Ihre Jamdesk-Subdomain:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const JAMDESK_HOST = 'YOUR_SLUG.jamdesk.app';

export function middleware(request: NextRequest) {
  const url = request.nextUrl;
  const destination = new URL(url.pathname + url.search, `https://${JAMDESK_HOST}`);

  // Clone headers and tell Jamdesk which domain the visitor actually used.
  const headers = new Headers(request.headers);
  headers.set('X-Jamdesk-Forwarded-Host', url.hostname);

  return NextResponse.rewrite(destination, {
    request: { headers },
  });
}

export const config = {
  matcher: ['/docs', '/docs/:path*', '/_jd/:path*'],
};

Die Datei muss middleware.ts heißen und eine Funktion namens middleware exportieren. Next.js 16 schlägt vor, sie in proxy.ts umzubenennen. Die Vercel-Produktion ruft proxy.ts jedoch noch nicht auf – eine Umbenennung deaktiviert die Middleware daher stillschweigend.

Assets und Dateien im Stammverzeichnis in vercel.json weiterleiten

Die Seiten von Jamdesk laden ihre Bundles aus /_next/, während Dateien im Stammverzeichnis wie robots.txt außerhalb des obigen Matchers liegen. Leiten Sie beide mit Rewrites weiter. Rewrites werden nach der Dateisystemprüfung ausgeführt, sodass Ihre eigenen Build-Ausgaben immer Vorrang haben und nur Anfragen, die Ihre Website nicht bedienen kann, an Jamdesk weitergeleitet werden:

{
  "rewrites": [
    { "source": "/_next/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_next/:path*" },
    { "source": "/robots.txt", "destination": "https://YOUR_SLUG.jamdesk.app/robots.txt?jd_proxy=1" },
    { "source": "/sitemap.xml", "destination": "https://YOUR_SLUG.jamdesk.app/sitemap.xml?jd_proxy=1" },
    { "source": "/llms.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms.txt?jd_proxy=1" },
    { "source": "/llms-full.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms-full.txt?jd_proxy=1" }
  ]
}

Die Dateien im Stammverzeichnis enthalten ?jd_proxy=1, weil die Middleware für sie nicht ausgeführt wird und ein Rewrite den Header nicht setzen kann. Fügen Sie sie nur hinzu, wenn Jamdesk das Stammverzeichnis Ihrer Domain verwaltet. Wenn Ihre Website eine eigene robots.txt oder sitemap.xml bereitstellt, führen Sie die Dateien stattdessen zusammen.

Bereitstellen und überprüfen

Stellen Sie das Projekt mit vercel --prod bereit (oder pushen Sie es in Ihr verbundenes Git-Repository). Öffnen Sie anschließend https://yoursite.com/docs und sehen Sie sich den Seitenquelltext an. Überprüfen Sie zwei Punkte:

1. <link rel="canonical"> verweist auf Ihre Domain, nicht auf YOUR_SLUG.jamdesk.app
2. Es gibt kein <meta name="robots" content="noindex">

Wenn einer der Punkte nicht stimmt, erreicht der Header X-Jamdesk-Forwarded-Host Jamdesk nicht. Überprüfen Sie, dass /docs im Matcher enthalten ist.

Warum der Marker wichtig ist

Jamdesk benötigt ein Signal, dass eine Anfrage über Ihren Proxy eingegangen ist und nicht direkt auf Ihrer *.jamdesk.app-Subdomain aufgerufen wurde. Der Marker ?jd_proxy=1 und der Header X-Jamdesk-Forwarded-Host übermitteln dieses Signal. Jamdesk behandelt beide als gleichwertig. Jedes der beiden Signale bestätigt Ihre registrierte Domain, verweist bei Canonical-, Open-Graph- und Sitemap-Links auf diese Domain und ermöglicht es Nur benutzerdefinierte Domain, Proxy-Anfragen von direkten Aufrufen zu unterscheiden.

Ein fehlendes Signal führt nicht zu einem offensichtlichen Fehler. Die Seiten werden weiterhin gerendert, jedoch mit noindex und Canonicals auf die Subdomain, wenn keine benutzerdefinierte Domain registriert ist, oder mit einem fehlschlagenden Check für „Nur benutzerdefinierte Domain“, wenn eine registriert ist. Ein 403 weist auf das umgekehrte Problem hin: Das Signal ist vorhanden, benennt jedoch eine Domain, die für dieses Projekt nicht registriert und aktiv ist.

Fehlerbehebung

Wie geht es weiter?