Source Markdown

Les outils IA traitent Markdown plus efficacement que le HTML rendu. Jamdesk rend la source Markdown brute de chaque page disponible 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, frontmatter et balises de composants compris.

Domaines personnalisés

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

# 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

Racine du site et racines de langue

La racine du site et une racine de langue seule exportent la page que montrent leurs versions HTML : la première page de votre navigation, ou de la navigation de cette langue. Il n'y a pas de redirection — le Markdown est renvoyé dès la première requête.

# 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

Un projet disposant d'une véritable page index.mdx continue de servir cette page à /index.md et à la racine. Si le fichier de la première page de navigation est manquant, la racine renvoie 404 comme n'importe quelle autre page manquante.

Format du contenu

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

Ce qu'exporte une page endpoint

Une page openapi: n'a presque pas de contenu propre — l'endpoint est généré à partir de votre spec — son export Markdown est donc aplati à partir de la spec à la place. Un agent qui la récupère obtient la méthode et le chemin, les paramètres avec leurs descriptions, les schémas de requête et de réponse, ainsi qu'une section ## Authentication nommant les schémas de sécurité requis par l'opération : le type de schéma, le nom de l'en-tête apiKey, le format du bearer, et les éventuels scopes OAuth 2.

Les alternatives sont libellées « Any one of » (une seule parmi ces options), les schémas qui doivent tous être envoyés sont regroupés, et une opération qui se désactive explicitement avec security: [] l'indique clairement plutôt que de rester silencieuse. C'est tout ce qu'il faut pour construire une requête fonctionnelle sans ouvrir la spec.

Specs OpenAPI sur les pages de référence API

Lorsque vous récupérez le Markdown d'une page de référence API (dont le frontmatter déclare une spec api: ou openapi:), Jamdesk ajoute un court pied de page qui oriente les agents IA vers 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

C'est le même api-specs.zip que propose l'action Télécharger la spec API, assemblé à nouveau à chaque requête. L'objectif est la portée : un agent qui lit une page d'endpoint apprend qu'il peut récupérer le contrat complet lisible par machine en une seule requête, au lieu de scraper chaque endpoint. Le pied de page n'apparaît que sur les pages de référence API des projets ayant au moins une spec ; 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 des 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 trouvée :

# 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 à la fois la recherche et l'accès à la source complète de votre documentation. Les deux URL fonctionnent aussi sur un domaine personnalisé actif — https://docs.acme.com/_mcp et https://docs.acme.com/guides/authentication.md.

Et ensuite ?