Sorgente Markdown
Accedi al sorgente Markdown grezzo di qualsiasi pagina aggiungendo .md all'URL. Testo strutturato per strumenti AI, script e pipeline di contenuti.
Gli strumenti AI elaborano il Markdown in modo più efficiente rispetto all'HTML renderizzato. Aggiungi .md all'URL di qualsiasi pagina per ottenerne il sorgente Markdown grezzo. Non è richiesta alcuna autenticazione.
Estensione URL .md
Aggiungi .md all'URL di qualsiasi pagina della documentazione per ottenere il sorgente grezzo invece dell'HTML renderizzato:
# Rendered page
https://acme.jamdesk.app/getting-started
# Raw Markdown source
https://acme.jamdesk.app/getting-started.mdFunziona per qualsiasi profondità del percorso. 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 tuo repository, inclusi frontmatter e tag dei componenti.
Domini personalizzati
Aggiungi .md all'URL del dominio personalizzato che vedono i tuoi lettori:
# 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.mdRadice del sito e radici delle lingue
La radice del sito e una radice di lingua semplice esportano la pagina che mostrano le loro versioni HTML: la prima pagina della tua navigazione, oppure della navigazione di quella lingua. Non c'è alcun reindirizzamento. Il Markdown viene restituito già 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.mdUn progetto con una vera pagina index.mdx continua a servire quella pagina su /index.md e sulla radice. La radice restituisce 404 quando manca il file della prima pagina di navigazione, come per qualsiasi altra pagina mancante.
Formato del contenuto
Il contenuto grezzo è Markdown esteso con tag di componenti come <Note>, <Steps> e <Tabs>. I parser Markdown standard trattano i tag dei componenti come HTML grezzo. Consulta Nozioni base di Markdown per il riferimento completo della sintassi.
Cosa esporta una pagina endpoint
Una pagina openapi: ha quasi nessun corpo proprio. Jamdesk renderizza l'endpoint dalla tua specifica. Il suo esporto in Markdown viene invece appiattito dalla specifica. Un agente che lo richiede ottiene il metodo e il percorso, i parametri con le relative descrizioni, gli schemi di richiesta e 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 del bearer e gli eventuali scope OAuth 2.
Le alternative sono etichettate "Any one of". Gli schemi che devono essere inviati tutti insieme sono elencati insieme. Un'operazione che si esclude con security: [] lo dichiara esplicitamente. È tutto ciò che un agente deve sapere per costruire una richiesta funzionante senza aprire la specifica.
Specifiche OpenAPI nelle pagine di riferimento API
Il Markdown di una pagina di riferimento API (una il cui frontmatter dichiara una specifica api: o openapi:) termina con un breve piè di pagina. Indirizza gli agenti AI verso ogni specifica OpenAPI del tuo progetto, raggruppata 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 dell'azione Scarica specifica API, generato ogni volta alla richiesta. Un agente che legge una singola pagina endpoint scopre di poter scaricare l'intero contratto leggibile dalle macchine con una sola richiesta, senza dover analizzare ogni endpoint. Il piè di pagina compare solo sulle pagine di riferimento API dei progetti con almeno una specifica.
Dettagli della risposta
Header
| Header | Valore | Scopo |
|---|---|---|
Content-Type | text/markdown; charset=utf-8 | Identifica il contenuto come Markdown |
Cache-Control | public, max-age=3600, s-maxage=86400 | Cache del browser per 1 ora, cache CDN per 1 giorno (URL .md) |
Vary | Accept | Lo stesso URL serve HTML o Markdown a seconda dell'header Accept della richiesta |
X-Robots-Tag | noindex, nofollow | Impedisce l'indicizzazione da parte dei motori di ricerca |
Content-Disposition | inline | Visualizza nel browser invece di scaricare |
X-Frame-Options | DENY | Impedisce l'incorporamento negli iframe |
Content-Security-Policy | default-src 'none' | Blocca l'esecuzione di script |
Richiedere l'URL canonico di una pagina (senza .md) con l'header Accept: text/markdown restituisce lo stesso Markdown con Cache-Control: private, no-store. Questa risposta condivide una chiave di cache con la pagina HTML. Non viene mai memorizzata nella cache.
Risposte di errore
| Stato | Significato |
|---|---|
308 | Reindirizzamento per slash finale (es. /intro.md/ reindirizza a /intro.md) |
404 | La pagina non esiste (restituisce un breve errore in testo semplice, non Markdown). La radice del sito e le radici di lingua risolvono nella prima pagina di navigazione e restituiscono 404 solo quando anche il file di quella pagina manca |
500 | Errore del server (restituisce una pagina di errore HTML) |
Utilizzo con gli strumenti AI
Usa searchDocs sul server MCP per trovare pagine tramite parola chiave. Poi recupera il sorgente grezzo 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.mdQuesto offre agli strumenti AI ricerca e accesso al sorgente completo della tua documentazione. Gli URL funzionano anche su un dominio personalizzato attivo: https://docs.acme.com/_mcp e https://docs.acme.com/guides/authentication.md.