Markdown-Quelle

KI-Tools verarbeiten Markdown effizienter als gerendertes HTML. Jamdesk stellt die rohe Markdown-Quelle jeder Seite bereit, indem Sie .md an eine beliebige URL anhängen. Eine Authentifizierung ist nicht erforderlich.

.md-URL-Erweiterung

Hängen Sie .md an die URL einer beliebigen Dokumentationsseite an, um die rohe Quelle statt des gerenderten HTML abzurufen:

# Rendered page
https://acme.jamdesk.app/getting-started

# Raw Markdown source
https://acme.jamdesk.app/getting-started.md

Dies funktioniert bei jeder Pfadtiefe. So sieht die Antwort aus:

curl https://acme.jamdesk.app/getting-started.md

---
title: Getting Started
description: Set up your first project in 5 minutes.
---

Welcome to the getting started guide.

## Prerequisites

<Note>You'll need Node.js 18 or later.</Note>

Die Antwort ist die exakte Quelldatei aus Ihrem Repository, einschließlich Frontmatter und Komponententags.

Benutzerdefinierte Domains

Rohe Inhalte funktionieren auch auf benutzerdefinierten Domains. Verwenden Sie dieselbe URL, die Ihre Leser sehen, und hängen Sie .md an:

# Docs served at root
curl https://docs.example.com/getting-started.md

# Docs served at /docs subpath
curl https://docs.example.com/docs/getting-started.md

Website-Root und Sprachpfade

Der Website-Root und ein einfacher Sprachpfad exportieren die Seite, die ihre HTML-Versionen anzeigen: die erste Seite in Ihrer Navigation bzw. in der Navigation der jeweiligen Sprache. Es gibt keine Weiterleitung – das Markdown wird bereits bei der ersten Anfrage zurückgegeben.

# All three return the first navigation page's Markdown
curl https://acme.jamdesk.app/index.md
curl -H "Accept: text/markdown" https://acme.jamdesk.app/
curl https://acme.jamdesk.app/fr.md

Ein Projekt mit einer echten index.mdx-Seite stellt diese Seite weiterhin unter /index.md und am Root bereit. Wenn die Datei der ersten Navigationsseite fehlt, gibt der Root wie jede andere fehlende Seite 404 zurück.

Inhaltsformat

Der rohe Inhalt ist Markdown, erweitert um Komponententags wie <Note>, <Steps> und <Tabs>. Standardmäßige Markdown-Parser behandeln Komponententags als rohes HTML. Eine vollständige Syntaxreferenz finden Sie unter Markdown-Grundlagen.

Was eine Endpoint-Seite exportiert

Eine openapi:-Seite hat fast keinen eigenen Inhalt – der Endpoint wird aus Ihrer Spezifikation gerendert –, daher wird ihr Markdown-Export stattdessen aus der Spezifikation erstellt. Ein Agent, der die Seite abruft, erhält Methode und Pfad, die Parameter mit ihren Beschreibungen, die Anfrage- und Antwortschemas sowie einen Abschnitt ## Authentication, in dem die von der Operation benötigten Sicherheitsschemata aufgeführt sind: der Schematyp, der apiKey-Headername, das Bearer-Format und alle OAuth-2-Scopes.

Alternativen werden mit „Any one of“ gekennzeichnet, Schemata, die alle gesendet werden müssen, werden gemeinsam aufgeführt, und eine Operation, die sich mit security: [] ausdrücklich gegen Sicherheit entscheidet, weist darauf hin, statt dazu zu schweigen. Damit ist alles vorhanden, was zum Erstellen einer funktionierenden Anfrage erforderlich ist, ohne die Spezifikation zu öffnen.

OpenAPI-Spezifikationen auf API-Referenzseiten

Wenn Sie das Markdown für eine API-Referenzseite abrufen (eine Seite, deren Frontmatter eine api:- oder openapi:-Spezifikation angibt), fügt Jamdesk einen kurzen Footer hinzu, der KI-Agenten auf jede OpenAPI-Spezifikation in Ihrem Projekt verweist, gebündelt als einzelner Download:

---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://acme.jamdesk.app/api-specs.zip

Es handelt sich um dasselbe api-specs.zip, das von der Aktion API-Spezifikation herunterladen angeboten wird und bei jeder Anfrage neu zusammengestellt wird. Der Vorteil liegt in der Reichweite: Ein Agent, der eine einzelne Endpoint-Seite liest, erfährt, dass er den vollständigen maschinenlesbaren Vertrag mit einer einzigen Anfrage abrufen kann, statt jeden Endpoint einzeln auszulesen. Der Footer erscheint nur auf API-Referenzseiten von Projekten, die mindestens eine Spezifikation haben; reguläre Leitfäden bleiben unverändert.

Antwortdetails

Header

Wenn Sie die kanonische URL einer Seite (ohne .md) mit dem Header Accept: text/markdown anfordern, wird dasselbe Markdown zurückgegeben, jedoch mit Cache-Control: private, no-store. Die Antwort verwendet denselben Cache-Schlüssel wie die HTML-Seite und wird daher niemals zwischengespeichert.

Fehlerantworten

Verwendung mit KI-Tools

URLs mit Markdown-Quellen eignen sich gut für den MCP-Server. Verwenden Sie searchDocs, um Seiten nach Schlüsselwörtern zu suchen, und rufen Sie anschließend die rohe Quelle der gefundenen Seite ab:

# 1. Search for a topic via MCP
curl -X POST https://acme.jamdesk.app/_mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"searchDocs","arguments":{"query":"authentication"}}}'

# 2. Fetch the raw source of the top result
curl https://acme.jamdesk.app/guides/authentication.md

Damit erhalten KI-Tools sowohl Zugriff auf die Suche als auch auf die vollständige Quelle Ihrer Dokumentation. Beide URLs funktionieren auch auf einer aktiven benutzerdefinierten Domain – https://docs.acme.com/_mcp und https://docs.acme.com/guides/authentication.md.

Wie geht es weiter?