Hospede o grafo em qualquer lugar: okf render

A melhor forma de ler um bundle OKF é como um grafo. O okf server abre essa visão no navegador: conceitos como nós, links como arestas, cada corpo renderizado do disco a cada clique. Mas um servidor é um processo, e um processo precisa de algum lugar para rodar. Para um bundle que você quer publicar uma vez e deixar no ar, isso é um pedido de verdade: uma máquina, uma porta, algo para manter vivo.

O grafo precisava de um servidor, e nem todo mundo tem um

O GitHub Pages não roda o seu Ruby. Um bucket de object storage também não, nem uma página de artefato de CI, nem o arquivo que você joga num chat para mostrar a um colega o que documentou. Cada um deles serve arquivos estáticos e nada mais, e até agora o grafo não podia morar ali. Você podia enviar o bundle, mas não a visão dele. O único lugar onde o grafo era fácil de alcançar era o único lugar onde você já tinha um servidor.

Um arquivo, o bundle inteiro

O okf 1.6.0 adiciona o okf render. Ele escreve exatamente a página que o okf server serve, como um único arquivo HTML autocontido com o bundle embutido:

okf render docs/ > public/index.html

Esse é o passo de publicação inteiro. Faça commit do arquivo numa branch gh-pages, ou suba num bucket, e o grafo vira uma URL. Abra do seu disco com um duplo clique e ele se comporta igual, sem nenhum processo por trás. O que o okf server te mostra, o arquivo te mostra, offline desde a primeira renderização. Busca, os filtros de tipo e diretório, o mapa de índice, o log de atualizações, os diagramas Mermaid: tudo isso, de um arquivo só.

A mesma página, a um interruptor de distância

O truque é que não existe uma segunda página. render e server são o mesmo template, e a única coisa que muda é de onde o navegador lê. No servidor, a página busca cada corpo, descrição, catálogo, índice e log ao vivo por HTTP a cada clique. No render não há servidor para responder essas leituras, então o bundle inteiro vai dentro do arquivo, e as mesmas leituras são resolvidas a partir desse payload embutido em vez da rede. Um interruptor escolhe a fonte; cada getter da página o respeita. É por isso que os dois modos nunca divergem: são uma implementação com dois backends, não dois visualizadores para manter em sincronia.

Nada mais frouxo que o servidor ao vivo

Embutir um bundle numa página levanta a pergunta óbvia: um corpo Markdown hostil agora consegue rodar script em quem abrir o arquivo? Não, e pelos mesmos motivos que tornam o servidor seguro. Os dados embutidos são escapados para que não consigam sair da tag de script, e cada corpo ainda passa pelo DOMPurify antes de chegar à página. As duas defesas que protegem o servidor ao vivo protegem o arquivo estático também. Um grafo renderizado é um retrato do bundle, não uma nova porta de entrada.

O único trade-off honesto é o peso. Cada corpo é embutido, então um bundle grande gera um arquivo grande, e para um bundle grande demais para enviar inteiro o okf server, que manda os corpos sob demanda, continua sendo a ferramenta certa. A maioria dos bundles não é tão grande, e para eles um único arquivo que você hospeda em qualquer lugar é a resposta mais simples.

Também na 1.6.0: a imagem Docker oficial

A mesma versão traz outra forma de alcançar o okf sem configurar nada: a imagem oficial em ghcr.io/serradura/okf, a CLI inteira sem Ruby para instalar, construída a partir do código e publicada multi-arch a cada tag de release. Ela tem o próprio texto em Rode o okf em qualquer lugar. O resumo é que, entre a imagem e o okf render, tanto a ferramenta quanto o grafo dela agora vão a lugares que antes pediam um passo de configuração primeiro.