Sorgente Markdown

Gli strumenti AI elaborano il Markdown in modo più efficiente rispetto all'HTML renderizzato. Jamdesk rende disponibile il sorgente Markdown di ogni pagina aggiungendo .md a qualsiasi URL. Non è richiesta alcuna autenticazione.

Estensione URL .md

Aggiungi .md all'URL di qualsiasi pagina della documentazione per ottenere il sorgente anziché l'HTML renderizzato:

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

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

Funziona per percorsi di qualsiasi profondità. Ecco come appare la risposta:

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 risposta è il file sorgente esatto del repository, inclusi il frontmatter e i tag dei componenti.

Domini personalizzati

Il contenuto raw funziona anche sui domini personalizzati. Usa lo stesso URL visualizzato dai lettori, aggiungendo .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

Radice del sito e radici delle lingue

La radice del sito e una radice della lingua senza percorso esportano la pagina mostrata dalle rispettive versioni HTML: la prima pagina nella navigazione oppure, per la radice della lingua, la prima pagina nella navigazione di quella lingua. Non viene eseguito alcun reindirizzamento: il Markdown viene restituito alla prima richiesta.

# 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 progetto con una vera pagina index.mdx continua a fornire quella pagina in /index.md e alla radice. Se manca il file della prima pagina nella navigazione, la radice restituisce 404, come qualsiasi altra pagina mancante.

Formato del contenuto

Il contenuto raw è Markdown esteso con tag di componenti come <Note>, <Steps> e <Tabs>. I parser Markdown standard trattano i tag dei componenti come HTML raw. Consulta Nozioni di base su Markdown per il riferimento completo alla sintassi.

Cosa esporta una pagina endpoint

Una pagina openapi: ha un corpo quasi interamente vuoto: l'endpoint viene renderizzato dalla tua specifica, quindi l'esportazione Markdown viene invece appiattita a partire dalla specifica. Un agente che la recupera riceve il metodo e il percorso, i parametri con le relative descrizioni, gli schemi della richiesta e della risposta e una sezione ## Authentication che indica gli schemi di sicurezza richiesti dall'operazione: il tipo di schema, il nome dell'header apiKey, il formato bearer e gli eventuali scope OAuth 2.

Le alternative sono etichettate "Any one of", mentre gli schemi che devono essere inviati tutti insieme sono elencati nello stesso gruppo; un'operazione che rinuncia esplicitamente alla sicurezza con security: [] lo comunica invece di restare in silenzio. Questo è tutto ciò che serve per creare una richiesta funzionante senza aprire la specifica.

Specifiche OpenAPI nelle pagine di riferimento API

Quando recuperi il Markdown di una pagina di riferimento API, ovvero una pagina il cui frontmatter dichiara una specifica api: o openapi:, Jamdesk aggiunge un breve piè di pagina che indirizza gli agenti AI a ogni specifica OpenAPI del progetto, raccolta in un unico download:

---

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

È lo stesso api-specs.zip offerto dall'azione Scarica la specifica API, assemblato da zero a ogni richiesta. Lo scopo è facilitare l'accesso: un agente che legge una pagina endpoint scopre di poter recuperare l'intero contratto leggibile dalle macchine con una singola richiesta, invece di analizzare ogni endpoint. Il piè di pagina compare solo nelle pagine di riferimento API dei progetti che contengono almeno una specifica; le guide normali non vengono modificate.

Dettagli della risposta

Header

Richiedendo l'URL canonico di una pagina, senza .md, con l'header Accept: text/markdown, ottieni lo stesso Markdown, ma con Cache-Control: private, no-store. Condivide una chiave di cache con la pagina HTML, quindi la risposta non viene mai memorizzata nella cache.

Risposte di errore

Utilizzo con gli strumenti AI

Gli URL del sorgente Markdown si abbinano bene al server MCP. Usa searchDocs per trovare pagine per parola chiave, quindi recupera il sorgente raw della pagina trovata:

# 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

In questo modo gli strumenti AI hanno accesso sia alla ricerca sia al sorgente completo della documentazione. Entrambi gli URL funzionano anche su un dominio personalizzato attivo: https://docs.acme.com/_mcp e https://docs.acme.com/guides/authentication.md.

Cosa fare dopo?