Markdown de origem
Acesse o código-fonte Markdown de qualquer página da documentação adicionando .md à URL. Texto estruturado para ferramentas de IA, scripts e pipelines de conteúdo.
Ferramentas de IA processam Markdown com mais eficiência do que HTML renderizado. Adicione .md a qualquer URL de página para obter seu código-fonte Markdown bruto. Nenhuma autenticação é necessária.
Extensão de URL .md
Adicione .md a qualquer URL de página da documentação para obter o código-fonte bruto em vez do HTML renderizado:
# Rendered page
https://acme.jamdesk.app/getting-started
# Raw Markdown source
https://acme.jamdesk.app/getting-started.md
Isso funciona para qualquer profundidade de caminho. Veja como fica a resposta:
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>
A resposta é o arquivo de origem exato do seu repositório, incluindo o frontmatter e as tags de componentes.
Domínios personalizados
Adicione .md à URL de domínio personalizado que seus leitores veem:
# 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
Raiz do site e raízes de idioma
A raiz do site e uma raiz de idioma sem caminho exportam a página que suas versões HTML exibem: a primeira página da sua navegação, ou da navegação daquele idioma. Não há redirecionamento. O Markdown é retornado já na primeira requisição.
# 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
Um projeto com uma página index.mdx real continua servindo essa página em /index.md e na raiz. A raiz retorna 404 quando o arquivo da primeira página da navegação está ausente, como acontece com qualquer outra página inexistente.
Formato do conteúdo
O conteúdo bruto é Markdown estendido com tags de componentes como <Note>, <Steps> e <Tabs>. Analisadores Markdown padrão tratam as tags de componentes como HTML bruto. Consulte Fundamentos de Markdown para a referência completa da sintaxe.
O que uma página de endpoint exporta
Uma página openapi: quase não tem corpo próprio. O Jamdesk renderiza o endpoint a partir da sua especificação. Sua exportação em Markdown é achatada a partir da especificação. Um agente que a busca recebe o método e o caminho, os parâmetros com suas descrições, os esquemas de requisição e resposta, e uma seção ## Authentication que nomeia os esquemas de segurança exigidos pela operação: o tipo do esquema, o nome do cabeçalho apiKey, o formato do bearer e quaisquer escopos OAuth 2.
Alternativas são rotuladas como "Any one of". Esquemas que precisam ser enviados todos juntos são listados em conjunto. Uma operação que opta por não usar segurança com security: [] informa isso. É tudo que um agente precisa para montar uma requisição funcional sem abrir a especificação.
Especificações OpenAPI em páginas de referência de API
O Markdown de uma página de referência de API (aquela cujo frontmatter declara uma especificação api: ou openapi:) termina com um rodapé curto. Ele aponta agentes de IA para todas as especificações OpenAPI do seu projeto, empacotadas como um único download:
---
📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://acme.jamdesk.app/api-specs.zip
É o mesmo api-specs.zip da ação Download API spec, gerado novamente a cada requisição. Um agente que lê uma página de endpoint descobre que pode buscar o contrato completo legível por máquina em uma única requisição, sem precisar raspar cada endpoint. O rodapé aparece apenas em páginas de referência de API de projetos com pelo menos uma especificação.
Detalhes da resposta
Cabeçalhos
| Cabeçalho | Valor | Finalidade |
|---|---|---|
Content-Type | text/markdown; charset=utf-8 | Identifica o conteúdo como Markdown |
Cache-Control | public, max-age=3600, s-maxage=86400 | Em cache no navegador por 1 hora, no CDN por 1 dia (URLs .md) |
Vary | Accept | A mesma URL serve HTML ou Markdown conforme o cabeçalho Accept da requisição |
X-Robots-Tag | noindex, nofollow | Impede a indexação por mecanismos de busca |
Content-Disposition | inline | Exibe no navegador em vez de baixar |
X-Frame-Options | DENY | Impede a incorporação em iframes |
Content-Security-Policy | default-src 'none' | Bloqueia a execução de scripts |
Requisitar a URL canônica de uma página (sem .md) com o cabeçalho Accept: text/markdown retorna o mesmo Markdown com Cache-Control: private, no-store. Essa resposta compartilha uma chave de cache com a página HTML. Ela nunca é armazenada em cache.
Respostas de erro
| Status | Significado |
|---|---|
308 | Redirecionamento por barra final (por exemplo, /intro.md/ redireciona para /intro.md) |
404 | A página não existe (retorna um erro curto em texto simples, não Markdown). A raiz do site e as raízes de idioma resolvem para a primeira página da navegação e só retornam 404 quando o arquivo dessa página também está ausente |
500 | Erro do servidor (retorna uma página de erro HTML) |
Uso com ferramentas de IA
Use searchDocs no servidor MCP para encontrar páginas por palavra-chave. Em seguida, busque o código-fonte bruto da página encontrada:
# 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
Isso dá às ferramentas de IA acesso à busca e ao código-fonte completo da sua documentação. As URLs também funcionam em um domínio personalizado ativo: https://docs.acme.com/_mcp e https://docs.acme.com/guides/authentication.md.
