Source Markdown

Les outils IA traitent le Markdown plus efficacement que le HTML rendu. Jamdesk met à disposition la source Markdown brute de chaque page en ajoutant .md à n'importe quelle URL. Aucune authentification requise.

Extension d'URL .md

Ajoutez .md à l'URL de n'importe quelle page de documentation pour obtenir la source brute au lieu du HTML rendu :

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

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

Cela fonctionne quelle que soit la profondeur du chemin. Voici à quoi ressemble la réponse :

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>

La réponse est le fichier source exact de votre dépôt, y compris le frontmatter et les balises de composants.

Domaines personnalisés

Le contenu brut fonctionne aussi sur les domaines personnalisés. Utilisez la même URL que celle vue par vos lecteurs, avec .md ajouté à la fin :

# 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

Format du contenu

Le contenu brut est du Markdown étendu avec des balises de composants telles que <Note>, <Steps> et <Tabs>. Les analyseurs Markdown standards traiteront les balises de composants comme du HTML brut. Consultez Bases du Markdown pour la référence complète de la syntaxe.

Spécifications OpenAPI sur les pages de référence API

Lorsque vous récupérez le Markdown d'une page de référence API (une page dont le frontmatter déclare une spécification api: ou openapi:), Jamdesk ajoute un court pied de page qui indique aux agents IA l'emplacement de chaque spécification OpenAPI de votre projet, regroupées en un seul téléchargement :

---

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

Il s'agit du même fichier api-specs.zip proposé par l'action Télécharger la spécification API, généré à nouveau à chaque requête. L'objectif est la portée : un agent qui lit la page d'un seul endpoint apprend qu'il peut récupérer le contrat complet lisible par machine en une seule requête, au lieu d'explorer chaque endpoint un par un. Le pied de page n'apparaît que sur les pages de référence API des projets comportant au moins une spécification ; les guides classiques restent inchangés.

Détails de la réponse

En-têtes

Demander l'URL canonique d'une page (sans .md) avec l'en-tête Accept: text/markdown renvoie le même Markdown, mais avec Cache-Control: private, no-store. Elle partage une clé de cache avec la page HTML, donc cette réponse n'est jamais mise en cache.

Réponses d'erreur

Utilisation avec les outils IA

Les URL de source Markdown se combinent bien avec le Serveur MCP. Utilisez searchDocs pour trouver des pages par mot-clé, puis récupérez la source brute de la page correspondante :

# 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

Cela donne aux outils IA un accès à la fois à la recherche et à la source complète de votre documentation. Les deux URL fonctionnent également sur un domaine personnalisé actif — https://docs.acme.com/_mcp et https://docs.acme.com/guides/authentication.md.

Et ensuite ?