text/markdown, do mesmo jeito que já pode responder com JSON.
O que este tutorial aborda
- Responder a uma requisição
.mdcomtext/markdown. - O método
to_markdownque o renderer espera no seu objeto. - Renderizar Markdown como HTML, que é uma tarefa separada para uma gem separada.
Requisitos
Responder com Markdown
Adicione um formatomd ao bloco respond_to da action:
format.md corresponde a uma requisição para a extensão .md. render markdown: é o novo renderer.
Defina to_markdown
O renderer chamato_markdown em tudo o que você entregar a ele. Sem esse método, a requisição falha com undefined method 'to_markdown'.
Quando o Markdown já está em um atributo, delegue a ele:
/posts/3.md agora retorna o Markdown bruto, com um Content-Type de text/markdown; charset=utf-8.
Esse header é o ponto central do recurso. Qualquer client que faz negociação de conteúdo agora recebe Markdown da sua aplicação como uma representação de primeira classe. Ele não recebe mais HTML que precisa remover.
Renderizando Markdown como HTML
Para exibir Markdown para uma pessoa no navegador, você ainda precisa de um parser de Markdown.commonmarker é uma opção padrão razoável, e oferece suporte ao Markdown no formato GitHub.
O motivo deste recurso
A motivação são os modelos de linguagem. Markdown é o formato para o qual os documentos são convertidos antes de serem passados a um modelo como contexto. Uma aplicação que fornecetext/markdown diretamente evita que cada client precise fazer parsing do HTML de volta para algo utilizável.
É pelo mesmo motivo que a documentação do AppSignal está disponível como Markdown. Cada página aqui é servida como Markdown puro na sua URL com a extensão .md. Cada página na navegação também é indexada no llms.txt. Um agente que lê esta documentação recebe o texto, não os elementos visuais da página. Adicionar format.md à sua própria aplicação a torna legível para agentes da mesma forma.
Para dar a um agente acesso aos seus próprios dados de monitoramento, veja AppSignal para agentes de IA.
Monitorando respostas em Markdown
Duas coisas merecem atenção quando a sua aplicação passa a trabalhar com Markdown:- Custo de renderização. Converter Markdown em HTML em cada requisição é trabalho real, e isso acontece dentro da view. Os traces de performance do AppSignal dividem uma requisição em events. Uma renderização lenta aparece como seu próprio segmento, não como tempo inexplicado. Se o parsing se mostrar significativo, faça cache do HTML em vez do Markdown.
- Tráfego de agentes. Endpoints de Markdown geralmente são requisitados por ferramentas em vez de navegadores. Seu padrão de tráfego é diferente: em picos, e muitas vezes bastante repetitivo. Dê ao formato seu próprio nome de action ou tag para manter esse tráfego separável das suas requisições HTML. Assim, nenhum dos dois distorce os tempos de resposta do outro.
Transcrição
Transcrito a partir do vídeo e levemente editado. As legendas automáticas entenderam errado vários nomes de produtos e de API, que foram corrigidos.Ler a transcrição
Ler a transcrição
0:02 Pessoal, neste episódio vamos falar sobre o novo tipo MIME e renderer de Markdown do Rails 8.1, como funciona e como usar isso nas suas aplicações Rails. Tenho aqui uma aplicação Rails bem simples, com um scaffold para posts. Eles têm um título, têm um body. Vamos escrever algo como Hello World, e vamos usar Markdown aqui e escrever algo como GoRails, https, gorails.com, is awesome. Vamos escrever um pouco de Markdown ali, e deixar isso renderizado.0:35 Mas isso é só uma string, Markdown é só texto, e precisamos conseguir renderizar isso na UI com HTML de verdade. Esse novo recurso do Rails 8.1 não serve para renderizar em HTML. Na verdade, ele serve para renderizar Markdown como um tipo MIME e como tipo de resposta nas suas views. Então, para renderizar isso corretamente, vamos usar uma gem chamada Commonmarker, que basicamente pega seu texto em Markdown, converte para HTML e renderiza. Eu já tenho essa gem instalada, mas você pode adicioná-la ao seu Gemfile e rodar bundle para instalá-la.1:14 Depois, podemos ir até nossa view, no lugar onde o body do post é renderizado, e escrever Commonmarker.to_html, passar aquele conteúdo, e então marcar como html_safe depois. Existem também várias opções que você pode adicionar aqui, que você pode ver na documentação do Commonmarker, mas vamos usar os padrões aqui. Atualizamos nossa página, e agora temos GoRails is awesome, em que GoRails é o link vindo do Markdown, e awesome está em itálico, porque o Markdown converteu isso em uma tag de âncora e uma tag EM. Isso é ótimo. Funciona como esperávamos. Agora, o recurso do Rails 8.1 de Markdown como tipo MIME e como renderer se refere, na verdade, ao renderer nos seus controllers.2:02 Então, quando temos uma action como essa, em que podemos responder com HTML ou com a versão em JSON, agora podemos escrever format.md. Isso vai procurar pela extensão de arquivo .md na URL, e então podemos escrever render markdown, que é o renderer de Markdown. Esse .md é o atalho para esse tipo MIME. Depois temos um render markdown, e podemos passar o post para ele. E se tentarmos fazer isso no navegador e visitarmos 3.md, vamos receber um erro interno do servidor, que será uma chamada de método indefinido para uma instância de post.2:41 O que está acontecendo aqui é basicamente que o renderer de Markdown vai tentar chamar to_markdown no nosso model, e então podemos delegar isso para o atributo body, onde está nosso texto em Markdown. E se atualizarmos no navegador, obtemos o conteúdo em Markdown bruto, como esperado. E se abrirmos a aba de rede do navegador e atualizarmos, podemos ver essa requisição, e o content type vai ser text/markdown com charset UTF-8. Então esse é o tipo MIME sendo usado para o content type da nossa resposta. E isso é algo útil na era da IA: como o DHH menciona, Markdown é o que usamos para entregar às nossas LLMs, para que elas leiam isso e usem como contexto na sua requisição.3:32 Então isso é muito útil para isso, mas na verdade não faz a renderização de Markdown para HTML. E é aí que algo como o Commonmarker entra em cena. É o que eu passei a usar para praticamente tudo hoje em dia. Ele tem várias opções, muitos dos mesmos recursos de Markdown no formato GitHub, e funciona muito bem. E é isso que podemos usar para realmente renderizar como HTML no navegador.3:59 Mas agora temos o tipo MIME format.md registrado, assim como o renderer de Markdown. E tudo o que precisamos fazer é definir esse método to_markdown. E está tudo certo. Então qualquer uma das nossas views agora pode responder com Markdown como content type. Isso é bem interessante.4:20 É basicamente isso. Não é um recurso grande. Sei que muita gente ficou super animada com isso. Acho que muita gente presumiu que seria algo como o Commonmarker sendo adicionado ao Rails, mas não é: na verdade é só o content type, o tipo MIME e o renderer, e essa é a parte confusa, eu acho.4:37 O renderer só significa que o helper render entende que sim, esse tipo MIME deve buscar e retornar esse conteúdo. Então é isso que há para saber, realmente. Não há muita coisa para falar aqui, mas isso é tudo o que você precisa fazer nos seus models para que eles sejam renderizados como Markdown. Isso é bem interessante.