Hipótese 01 — MkDocs como Infraestrutura de Publicação de Conhecimento

Um experimento prático na construção de uma plataforma de publicação baseada em Markdown

Hipótese 01 — MkDocs como infraestrutura de publicação

Introdução

Este laboratório teve como objetivo avaliar uma hipótese simples:

Seria possível substituir uma instalação tradicional de WordPress por uma infraestrutura de publicação baseada exclusivamente em arquivos Markdown e páginas estáticas?

A motivação surgiu durante a investigação de ferramentas para leitura, organização e publicação de documentos produzidos em Markdown.

O experimento foi conduzido utilizando:

Markdown;
MkDocs;
Material for MkDocs;
Python;
SSH;
rsync;
Hospedagem Linux convencional.

O objetivo não era apenas publicar conteúdo, mas avaliar aspectos como:

simplicidade;
auditabilidade;
rastreabilidade;
reprodutibilidade;
facilidade de manutenção.

A Hipótese

A hipótese investigada foi:

Um site baseado em MkDocs pode fornecer uma infraestrutura mais simples, transparente e sustentável para publicação de conhecimento técnico do que uma instalação tradicional de WordPress.

Arquitetura do Experimento

A arquitetura adotada foi composta por cinco etapas.

Markdown
    ↓
MkDocs + Material
    ↓
Site Estático
    ↓
Deploy via SSH
    ↓
Servidor Web

O conteúdo é produzido em arquivos Markdown.

O MkDocs transforma esses arquivos em:

HTML;
CSS;
JavaScript;
índice de busca.

O resultado é um site completamente estático.

Estrutura do Projeto

Estrutura simplificada utilizada durante o experimento:

mos-blog/
├── docs/
│   ├── index.md
│   ├── artigos/
│   │   └── zettelkasten-e-unix.md
│   └── imagens/
│       └── Zettelkasten_Unix.png
│
├── mkdocs.yml
│
└── .venv/

Preparação do Ambiente

Criando ambiente virtual

python3 -m venv .venv
source .venv/bin/activate

Instalando MkDocs Material

pip install mkdocs-material

Criando o projeto

mkdocs new .

Estrutura criada:

docs/
└── index.md

mkdocs.yml

Configuração Inicial

Arquivo:

site_name: MOS Blog

theme:
  name: material

nav:
  - Início: index.md

  - Artigos:
      - Zettelkasten e Unix: artigos/zettelkasten-e-unix.md

Desenvolvimento do Conteúdo

O primeiro artigo publicado foi:

Zettelkasten e Unix:
uma nova forma de construir conhecimento e software

O artigo foi produzido integralmente em Markdown.

Inclusão de Imagens

Uma imagem foi adicionada ao artigo.

Estrutura:

docs/
└── imagens/
    └── Zettelkasten_Unix.png

Referência utilizada:

![Relação entre Zettelkasten e Unix](../imagens/Zettelkasten_Unix.png)

Posteriormente foi adotada uma versão HTML para melhor controle de largura:

<p align="center">
  <img src="../imagens/Zettelkasten_Unix.png"
       alt="Zettelkasten e Unix"
       width="100%">
</p>

Visualização Local

Durante a edição dos documentos:

mkdocs serve

O servidor de desenvolvimento é iniciado localmente.

Sempre que um arquivo é salvo:

Markdown é recompilado;
navegador é atualizado;
alterações tornam-se imediatamente visíveis.

Essa característica produziu um ciclo de trabalho extremamente rápido.

Geração do Site Estático

Após a conclusão dos conteúdos:

mkdocs build

Resultado:

site/
├── index.html
├── artigos/
├── assets/
├── imagens/
└── search/

Todo o site passa a existir como arquivos estáticos.

Nenhum banco de dados é utilizado.

Nenhum código PHP é necessário.

Publicação

A publicação foi realizada por sincronização via SSH.

Exemplo genérico:

rsync -avz \
  site/ \
  -e "ssh -p PORTA_SSH" \
  usuario@servidor:/caminho/do/site/

Após a sincronização:

site local
      ↓
rsync
      ↓
servidor web
      ↓
site publicado

Comparação com WordPress

WordPress

Editor
   ↓
PHP
   ↓
Banco de Dados
   ↓
Plugins
   ↓
Tema
   ↓
Servidor
   ↓
Visitante

MkDocs

Markdown
   ↓
MkDocs
   ↓
HTML Estático
   ↓
Deploy
   ↓
Servidor Web
   ↓
Visitante

Observações do Laboratório

Algumas descobertas surgiram rapidamente.

Simplicidade

A infraestrutura é muito menor.

Auditabilidade

Todo conteúdo é texto.

Tudo pode ser:

versionado;
revisado;
comparado.

Reprodutibilidade

O ambiente pode ser reconstruído a partir de:

pip install -r requirements.txt

ou

pip install mkdocs-material

Transparência

Não existem componentes ocultos.

Toda a lógica do site está:

nos arquivos Markdown;
no mkdocs.yml.

Relação com a Filosofia Unix

Durante o experimento surgiu uma observação interessante.

A arquitetura do MkDocs possui forte afinidade com princípios clássicos do Unix.

Princípios observados:

arquivos de texto como unidade fundamental;
ferramentas pequenas e especializadas;
composição por etapas;
automação simples;
separação clara de responsabilidades.

A publicação deixa de ser uma aplicação monolítica e passa a ser um pipeline.

Markdown
    ↓
Build
    ↓
Artefato
    ↓
Deploy

Conclusão

O experimento confirmou a hipótese inicial.

Para publicação de conhecimento técnico, documentação, pesquisas, hipóteses e artigos, uma infraestrutura baseada em:

Markdown;
MkDocs;
Material for MkDocs;
SSH;

mostrou-se extremamente eficiente.

Além de reduzir a complexidade operacional, essa abordagem aproxima o processo de publicação dos princípios de:

engenharia de software;
versionamento;
rastreabilidade;
construção incremental do conhecimento.

Em outras palavras:

O conteúdo deixa de depender de uma plataforma específica e passa a existir como um conjunto de artefatos simples, auditáveis e duradouros.

Essa característica torna o modelo particularmente atraente para laboratórios de pesquisa, documentação técnica e gestão do conhecimento.