Docsify Docs
Plugin WordPress que transforma uma página do site em documentação feita de arquivos Markdown. Quem lê entra com o login e o papel que já tem no projeto, e a regra de acesso vale para os arquivos .md, não só para a página.
- Papel
- Autor e mantenedor
- Onde
- Projeto open source (GPL-2.0)
- Período
- 06/2025 – atual
- Stack
- PHP · WordPress · Docsify · Swagger UI · Mermaid
Desafio
Documentação de projeto quase nunca é pública, e o projeto já é um WordPress, com usuário, papel e login. Só que trancar a página não bastava: o Docsify busca cada .md por HTTP, direto do servidor, e quem soubesse o caminho lia a documentação sem fazer login.
- O Docsify monta a documentação no navegador, sem etapa de build.
- O pedido de cada .md chega ao Apache sem passar pelo WordPress.
- Plugins de cache e de atraso de JavaScript deixavam a página em branco.
Abordagem
Coloquei o Docsify num template de página e passei a servir os arquivos pelo próprio WordPress, na rota /docsify-docs-files/, com a mesma checagem de papel da página. Ao lado dos arquivos, o plugin grava uma regra que nega o acesso direto à pasta.
- Só sai uma lista fixa de extensões, e caminho que escapa da pasta é recusado.
- Docsify, Swagger UI, Mermaid e as fontes vêm no plugin, sem CDN.
- Com DOCSIFYDOCS_DOCS_DIR, a pasta dos .md fica versionada junto do código.
- Logo, cor do tema e papéis liberados ficam numa tela de configurações.
Resultado
O plugin está na versão 3.6.1, com 15 releases desde junho de 2025. Além das páginas em Markdown, ele mostra a referência de API com Swagger UI e monta guias passo a passo a partir de uma lista numerada.
- Um link chamado swagger numa página vira a documentação interativa da API.
- Uma lista numerada marcada com um comentário HTML vira um guia, um passo por vez.
- Todo pull request roda WordPress Coding Standards, análise estática e checagem de versão.
- Open source, licença GPL-2.0.
