Fonte Markdown

As ferramentas de IA processam Markdown com mais eficiência do que HTML renderizado. O Jamdesk disponibiliza o código-fonte Markdown bruto de todas as páginas adicionando .md a qualquer URL. Não é necessária autenticação.

Extensão de URL .md

Adicione .md à URL de qualquer página de 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 com qualquer profundidade de caminho. Veja como é 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-fonte exato do seu repositório, incluindo o frontmatter e as tags de componentes.

Domínios personalizados

O conteúdo bruto também funciona em domínios personalizados. Use a mesma URL que seus leitores veem, adicionando .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

Raiz do site e raízes de idioma

A raiz do site e uma raiz de idioma sem caminho exportam a página exibida pelas versões HTML: a primeira página da sua navegação ou da navegação desse idioma. Não há redirecionamento: o Markdown é retornado na primeira solicitaçã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 disponibilizando essa página em /index.md e na raiz. Se o arquivo da primeira página da navegação estiver ausente, a raiz retornará 404, como qualquer outra página ausente.

Formato do conteúdo

O conteúdo bruto é Markdown estendido com tags de componentes como <Note>, <Steps> e <Tabs>. Os analisadores Markdown padrão tratarão as tags de componentes como HTML bruto. Consulte Fundamentos de Markdown para obter a referência completa da sintaxe.

O que uma página de endpoint exporta

Uma página openapi: quase não tem conteúdo próprio: o endpoint é renderizado a partir da sua especificação. Por isso, sua exportação Markdown é nivelada a partir da especificação. Um agente que a busca obtém o método e o caminho, os parâmetros com suas descrições, os esquemas de solicitação e resposta e uma seção ## Authentication que identifica os esquemas de segurança exigidos pela operação: o tipo de esquema, o nome do cabeçalho apiKey, o formato bearer e quaisquer escopos OAuth 2.

As alternativas são identificadas como "Any one of", os esquemas que precisam ser enviados juntos são listados em conjunto e uma operação que desativa explicitamente a segurança com security: [] informa isso em vez de ficar em silêncio. Isso é tudo o que é necessário para criar uma solicitação funcional sem abrir a especificação.

Especificações OpenAPI em páginas de referência de API

Quando você busca o Markdown de uma página de referência de API — uma página cujo frontmatter declara uma especificação api: ou openapi: — o Jamdesk acrescenta um rodapé curto que direciona os agentes de IA para todas as especificações OpenAPI do seu projeto, agrupadas em 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 oferecido pela ação Baixar especificação da API, montado do zero a cada solicitação. O objetivo é ampliar o alcance: um agente que lê uma página de endpoint descobre que pode obter o contrato completo legível por máquina em uma única solicitação, em vez de extrair cada endpoint individualmente. O rodapé aparece somente em páginas de referência de API de projetos que têm pelo menos uma especificação; os guias comuns não são alterados.

Detalhes da resposta

Cabeçalhos

Solicitar a URL canônica de uma página (sem .md) com o cabeçalho Accept: text/markdown retorna o mesmo Markdown, mas com Cache-Control: private, no-store. Ela compartilha uma chave de cache com a página HTML, portanto essa resposta nunca é armazenada em cache.

Respostas de erro

Uso com ferramentas de IA

As URLs de código-fonte Markdown funcionam bem com o servidor MCP. Use searchDocs para encontrar páginas por palavra-chave e, em seguida, busque o código-fonte bruto da página correspondente:

# 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 fornece às ferramentas de IA acesso tanto à pesquisa quanto ao código-fonte completo da documentação. As duas URLs também funcionam em um domínio personalizado ativo: https://docs.acme.com/_mcp e https://docs.acme.com/guides/authentication.md.

O que vem a seguir?