Pular para conteúdo

Procedimento 000 - Migração de WordPress para MkDocs na HostGator

Objetivo

Descrever o procedimento utilizado pela Milk of Stone para substituir uma instalação WordPress por uma infraestrutura de publicação baseada em Markdown, MkDocs e Material for MkDocs, preservando o conteúdo anterior e minimizando riscos operacionais.

Contexto

Após a validação da hipótese de que o MkDocs poderia substituir adequadamente uma instalação WordPress para publicação de conhecimento técnico, decidiu-se realizar a migração do ambiente de produção do blog da Milk of Stone.

A migração teve como objetivo:

  • reduzir a complexidade operacional;
  • eliminar dependências de PHP e banco de dados;
  • simplificar backup e restauração;
  • adotar Markdown como formato principal de publicação;
  • alinhar a infraestrutura de publicação aos princípios utilizados nos demais projetos da MOS.

Ambiente Original

Domínio

blog.milkofstone.com

Plataforma

WordPress

Hospedagem

HostGator

Diretório

/home3/milkofst/blog.milkofstone.com

Levantamento Inicial

Antes da migração foi realizado levantamento do ambiente existente.

Verificação do tamanho da instalação

du -sh blog.milkofstone.com

Resultado aproximado:

725M

Inspeção da estrutura

ls -lah blog.milkofstone.com

Foram identificados:

  • WordPress;
  • temas;
  • plugins;
  • uploads;
  • arquivos de configuração;
  • banco de dados associado.

Backup Completo

Antes de qualquer alteração foi criado backup integral da instalação.

Geração do backup

Exemplo:

tar -czvf \
blog.milkofstone.com.backup.YYYYMMDD-HHMMSS.tgz \
blog.milkofstone.com/

Resultado obtido:

blog.milkofstone.com.backup.20260615-210402.tgz

Tamanho aproximado:

443 MB

Preservação do Ambiente Legado

A instalação original não foi removida.

Foi preservada integralmente.

Renomeação do diretório

mv \
blog.milkofstone.com \
blog.milkofstone.com-legado

Resultado:

/home3/milkofst/blog.milkofstone.com-legado

Criação do Novo Ambiente

Após a preservação do legado foi criado um novo diretório vazio.

mkdir blog.milkofstone.com

Verificação:

ls -lah blog.milkofstone.com

Resultado esperado:

total 8
drwxr-x--- ...
.
..

Preparação do Ambiente MkDocs

O ambiente MkDocs foi preparado localmente.

Criação do ambiente virtual

python3 -m venv .venv

Ativação

source .venv/bin/activate

Instalação

pip install mkdocs-material

Geração do Site Estático

Durante o desenvolvimento:

mkdocs serve

Para geração do site:

mkdocs build

Resultado:

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

Publicação

A publicação foi realizada utilizando SSH e rsync.

Comando

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

Exemplo genérico:

rsync -avz \
site/ \
-e "ssh -p XXXX" \
usuario@servidor:/home/usuario/site/

Validações Pós-Migração

Após a publicação foram realizados testes de:

  • página inicial;
  • artigos;
  • estudos;
  • imagens;
  • menu de navegação.

Busca

Verificação do índice gerado pelo MkDocs.

Integridade

Verificação de:

  • links internos;
  • imagens;
  • URLs permanentes.

Resultado Obtido

O WordPress deixou de ser utilizado em produção.

A infraestrutura passou a operar com:

  • Markdown;
  • MkDocs;
  • Material for MkDocs;
  • SSH;
  • rsync.

Sem dependência de:

  • PHP;
  • MySQL;
  • plugins WordPress;
  • painel administrativo.

Estrutura Final

Markdown
    ↓
MkDocs
    ↓
Site Estático
    ↓
rsync
    ↓
Servidor Web

Lições Aprendidas

  1. A migração pode ser realizada sem reinstalar software na hospedagem.
  2. O servidor web existente pode servir conteúdo estático diretamente.
  3. O backup completo do WordPress deve ser preservado.
  4. A publicação torna-se mais simples e auditável.
  5. O conteúdo passa a existir como arquivos versionáveis e independentes da plataforma.

Referências

  • MkDocs
  • Material for MkDocs
  • Markdown
  • Obsidian

Documento derivado do:

Estudo 000 — Avaliação do MkDocs como Infraestrutura de Publicação