View Original Text

Hide Table of Contents

On the bottom line

Do que se trata afinal

Eu tenho inúmeros projetos já documentados espalhados pela Internet (ou num backup no meu HD), outros que ainda preciso documentar e publicar antes que um crash aconteça. Por uma questão de sorte, eu começei pela documentação no Bitbucket após migrar tudo o que eu tinha do Github (don't ask, não quero flames por aqui) e neste processo eu pensei em como seria prático se os links nos markdowns do repositório funcionassem do mesmo jeito que na máquina local.

Bom, a idéia era tão boa e tão óbvia que duvidei que já não tivessem feito isso: comitei o código, fui no Bitbucket navegar nele e funcionou como esperado. :-)

Pra quem estiver curioso, táqui o repositório em questão que deu origem à presepada.

FIAT LUX!!! Mas se eu tivesse lido direito a documentação do Bitbucket, eu saberia disso mais cedo. O:-) Old dogs, new tricks, vocês sabem como é. =P

Daí para ter a idéia de usar Markdown num site foi um pulo, e procurando é óbvio que achei centenas de soluções. Este documento é um on going effort sobre as pesquisas para adotar uma ferramenta que atenda aos seguintes requisitos:

Mas também antender aos seguintes "anti-requisitos":

Alguns destes eu vou implantar e brincar aqui no sandbox para ver no que dá.

Em análise

Simple CGI's

Enquanto o CMS não é escolhido, uma solução para servir Markdown direto do server HTML será útil.

E mesmo depois disso, servir um MD ocasional na área HTML não é uma feature que me desagrada.

RenderMarkdown

Esta solução possui uma formação default bem conveniente (você está lendo um texto processado por ele neste momento). Os templates de CSS são fácilmente customizáveis.

Automaticamente cria um Sumário (Table of Contents) no canto superior esquerdo, e também um link para mostrar o raw text no canto superior direito.

Um plus importante é usar UWSGI, permitindo conexões via sockets (menos dor de cabeça no stack TCP/IP) e diminuindo um bocadinho a carga do request.

O ponto agri-doce é que foi implementada em Python 3. Python já é uma carroça de bois :-), e no Python 3 os bois são mancos :-D . A baixa performance da solução foi mitigada usando o cache do NGINX.

Mas o lado bom de ser em Python é que a solução é extremamente simples de ser customizada, já que Python é uma linguagem amplamente suportada por uma comunidade bem coesa (e o raio da linguagem é fácil, fácil de trabalhar - desde que você não queira implementar um sistema complexo).

No frigir dos ovos, a solução Python+Cache se revelou conveniente e eficiente o suficiente, o que acabou me acomodando e adiando os testes das demais alternativas. Foi oficialmente adotado para as páginas estáticas de http://retro.lisias.net .

mdcgi

Numa análise superficial, a solução é sensivelmente menos conveniente que a adotada:

Perl apesar de ser uma linguagem que mais parece uma cifra :-) é estupidamente eficiente e ainda amplamente usada, de forma que mesmo que menos conveniente que Python, eu ainda vou testar na prática esta solução.

Ainda estar amarrado no CGI não é um problema graças so FCGIWrapper, que faz uma ponte entre o protocolo FastCGI suportado pelo NGINX com código legado CGI.

Por outro lado, como estamos servindo páginas estáticas com estas ferramentas, o uso do cache do NGINX na prática nivela a performance das duas soluções - de forma que a conveniência da solução Python possivelmente falará mais alto neste site.

Mas em sites com alta demanda e/ou em que as páginas sejam constantemente atualizadas, a performance do Perl pode inverter a conclusão: Perl é eficiente pra cacete. Ponto.

CMS's (ou perto disso)

werc

Esta solução é do cacete, viu? O maluco implementou um CMS completo (embora mínimo) usando... RC! Sim, o "bash" do Plan9! :-)

A performance do site é supreendentemente aceitável (sério, o RC é o 'bash' do Plan9, não tô de sacanagem não), e para quem sabe administrar sites UNIX como se deve, customizar é relativamente simples (afinal, é um shell script!!) - até porque a 'linguagem' RC é sensivelmente mais sã que o próprio bash. :-)

A solução é muito bem modularizada, permitindo vários "domínios" independentes, cada um customizado à parte. A diagramação do site é um pouco travada, baseada em hierarquia de diretórios. Mas é versátil o suficiente para a maioria dos usos que eu vi em sites que atuam no nicho que pretendo atuar.

Sim, é isso aí: absolutamente nenhum uso de Banco de Dados, todo o conteúdo está no bom e velho file-system. Um efeito colateral benéfico é que você pode gerenciar mudanças usando um Code Management System (aqui eu uso o mercurial) - backups automáticos: duplicar o site em outro servidor é meramente dar um hc checkout. :-)

O lado negativo da solução é que o pacote sys-apps/9base-6-r1 do Gentoo foi deletado do repositório oficial (pacote abandonado). Estou incerto se quero manter eu mesmo uma instalação /opt deste pacote, ou mesmo "herdar" a manutenção do pacote no Gentoo.

Luminos

Declaradamente inspirado no werc, mas focando apenas em funcionalidades mínimas. Sem Wiki, sem Content Management.

A instalação e a configuração é extremamente simples, o layout padrão dos caras é elegante e o treco é bem eficiente (implementado em GO e usando FastCGI).

O lado ruim é que a solução é minimalista - não fornece muitas das funcionalidades do werc que eu quero. =/

Sputnik

O Sputnik promete, tem tudo o que eu quero.

Implementado em Lua, deve ter uma performance bem melhor que Python.

Uma característica interessante é que o Conteúdo pode ser gerido por um repositório GIT - sonho de consumo, vai ser possível rastrear toda e qualquer edição feita por usuários e dar rollback sem dor de cabeça. Mais seguro e eficiente que usar SQL para a tarefa.

Conteúdo este que pode ser construído colaborativamente, bem Wiki style mesmo.

É um CMS de fato e de direito (até um pouco mais do que eu planejo), mas está descontinuado desde 2012. Se acontecer de eu gostar desta joça, terei que assumir a manutenção da bagaça.

O processo de instalação na época era bem simplificado, mas sofreu bit rotting nestes 4 anos, motivo pelo qual ainda não instalei esta solução no sandbox.

Na fila

Aqui vão alguns que ainda parecem promissores, mas por um motivo ou outro eu priorizei outros.

Nesta

Parece fazer tudo o que eu quero, e muito mais. Um pouco demais, numa análise superficial.

WofFS

Outro seguido a proposta do werc e luminos, mas implementado em Perl e com uma proposta interessante (e um bocado perigosa) : as páginas são automaticamente geradas a partir de markdown, e também por scripts bash, php, Perl e cgi (sim, cgi chamando cgi :-) ). E também html, óbvio.

A idéia em si é bacana, mas manter um site WofFS pode se tornar um pesadelo administrativo justamente pela flexibilidade. Se eu chegar a instalar no sandbox, será mais pela curiosidade que outra coisa.

CommonPlace

Um CMS minimalista no estilo do Luminos, implementado em Ruby. Está mencionado aqui justamente por ser em Ruby - será interessante medir performance entre as diversas soluções.

Mas dificilmente vinga - a solução está abandonada, e não planejo o uso de Ruby no meu Portfolio (nada contra Ruby, muito pelo contrário, mas acabou que me voltei para Python e não faz sentido ter as duas em paralelo).

Markdown Tree

Outro no estilo Luminos, também em Ruby.

E aqueles que foram sem nunca terem sido :)

Algumas soluções pareciam promissoras, mas na hora H não deram no couro.

Foram estes:

allmark

O site é bem apresentado, as funcionalidades eram adequadas, e os caras documentaram a criança direitinho.

Mas o allmark não trabalha com FastCGI, só como um server autônomo - o que é um aborrecimento, não um impedimento. Mas o que f*deu a biela foi a falta de suporte para virtual hosts.

De forma que a única forma de integrar isso no meu site é instanciar um serviço para cada vhost e jogá-lo no proxy_pass no nginx. Por este mesmo motivo, é virtualmente impossível instanciá-lo no setup deste sandbox (um só domínio, com as urls redirecionando para o proxy_pass ou fcgi_pass).

Ele também não dá suporte para Unix Sockets. Um tremendo aborrecimento quando tudo o que você quer são FastCGI's e Proxies Reversos com o nginx como front-end.

Eu também não curti muito o esquema de diretórios adotado. Com certeza este esquema deve fazer sentido para os projetos dos autores, mas para os meus propósitos (um Meta-CMS minimalista baseado em Markdown) não serve.

Por outro lado, se tudo o que você quer é um servidor HTTP simples servindo markdown, este carinha foi o mais fácil de fazer setup de todos os em que botei minhas patas sujas.

E foi feito em Go, gera um código binário que executa com eficiência (mas eu achei o binário bem grandinho - presumo que todas as dependências foram linkadas estaticamente).

Caddy Server

Outro full blown server autônomo, com os mesmos impedimentos do allmark para mim. O servidorzinho parece fornecer mais serviços (como interface FastCGI e suporte para mais de um markup language) mas não dar suporte para virtual hosts nem para Unix Sockets é sério aborrecimento (ver acima) de forma que este eu nem tentei usar.

Mas me pareceu uma boa opção se você não tiver os mesmos requisitos que eu.

Outro feito em Go, por sinal. :-)

Hugo et all

Mais uma opção que parece ser excelente, mas morreu na praia (para mim) devido à requisitos conflitantes.

Esta solução foi descrita como um static site generator, o que sem dúvida é a principal razão da ótima performance clamada categoricamente pelos autores. Os templates usados no site da solução também estão muito bons, por sinal - o site é um pouco bloated, mas os caras querem demonstrar a ferramenta e sua competência técnica, não vender seviços de diagramação. :-)

Contudo, a geração das páginas estáticas ocorrem no dev side, o processador roda na máquina do desenvolvedor. É o mesmo princípio do bom e velho JavaDoc, mas para este sandbox eu preciso de algo que também possa ser usado como um WIKI - de forma que a geração da página estática deve ocorrer no server side, após a edição do 'fonte' em Markdown.

Pelos mesmos motivos, Jekyll, Middleman, e similares também não foram nem avaliados.

Urubu

Outro que bateu na trave. Python, Markdown, deploy transparente direto de um repositório GIT, minimalista, páginas estáticas. Só faltou edição in situ (que pode até ter, mas eu parei a pesquisa quando li sobre o que escrevo abaixo).

Mas como o Jekyll, depende de "front matters" - a configuração da página está como markup no próprio arquivo. Isto não é um problema em si (aliás, é uma boa solução para uma porrada de situações), mas para este site, eu preciso de Markdowns genéricos que possam ser transplantados entre containers e serem visualizados corretamente sem esforço - o mesmo markdown deve ser legível sem problemas (e sem poluição visual) no Bitbucket, no Github e neste site.

PHP? PQP!!! =P

Brincadeiras à parte, PHP possui alguns pontos fortes - como uma performance no acesso à Banco de Dados invejável que deixa muito ambiente melhor visto no chinelo.

Minhas objeções à linguagem não me impediram de engolir meu orgulho e desenvolver serviços em PHP onde esta ferramenta se revelou superior às alternativas.

Contudo... :-)

Estrategicamente PHP não acrescenta muito à minha carreira, e como é inevitável que eu acabe mais cedo ou mais tarde dando manutenção na ferramenta que vou adotar no site, soluções em PHP (pelo menos neste momento) não possuem muito apelo - PHP/Noku não me atrai... O:-)

Mas, como sempre, há inúmeras opções em PHP mundo afora.

node.js

Não considero Javascript a pior coisa que já aconteceu na informática, e não é de hoje que se tenta adotar esta solução no server side (sim, eu sou desta época, li este documento em primeira mão!).

Posso não ir muito com a cara de JQUERY e das inúmeras firulas (em detrimento de funcionalidaes) do que se chama Web 2.0, mas usar Ecmascr... digo... Javascript no server side foi algo que considerei desde antes da Internet virar commoditie.

MAS (e é um tremendo de um MAS) "O que é o aço comparado à mão que o empunha?" - Python e Ruby atuam neste mesmo nicho com mais desenvoltura, e recentes acontecimentos na scene tornaram o node.js um risco desnecessário. Players importantes que desenvolvem e mantêm funcionalidades chave neste ambiente simplesmente não possuem a maturidade necessária para que eu implante soluções baseadas em node.js e consiga dormir tranquilo à noite.

Uma pena, a V8 possui uma performance muito satisfatória.