Markdown-Quelltext

KI-Tools verarbeiten Markdown effizienter als gerendertes HTML. Jamdesk stellt den rohen Markdown-Quelltext 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 den rohen Quelltext 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 unabhängig von der 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 Komponenten-Tags.

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

Inhaltsformat

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

OpenAPI-Spezifikationen auf API-Referenzseiten

Wenn Sie das Markdown einer API-Referenzseite abrufen (also einer Seite, deren Frontmatter eine api:- oder openapi:-Spezifikation enthält), hängt Jamdesk eine kurze Fußzeile an, die KI-Agenten auf jede OpenAPI-Spezifikation in Ihrem Projekt verweist, gebündelt als ein einziger 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 dieselbe api-specs.zip, die von der Aktion API-Spezifikation herunterladen angeboten wird und bei jeder Anfrage neu zusammengestellt wird. Der Zweck ist eine größere 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. Die Fußzeile erscheint nur auf API-Referenzseiten von Projekten mit mindestens einer Spezifikation; reguläre Anleitungen bleiben unverändert.

Details zur Antwort

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 nie zwischengespeichert.

Fehlerantworten

Verwendung mit KI-Tools

Markdown-Quelltext-URLs eignen sich gut in Verbindung mit dem MCP-Server. Verwenden Sie searchDocs, um Seiten nach Schlüsselwörtern zu finden, und rufen Sie anschließend den rohen Quelltext 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 den vollständigen Quelltext 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?