Executando verificação de segurança...
8
cyp
2 min de leitura ·

[PITCH] Crie documentações diretamente do seu Github

Olá!

Nessa semana de férias, eu trabalhei em um projetinho pessoal para testar o mini-templating engine que fiz em C#, chamado TinyComponents, junto com meu Framework web Sisk e o pré-processador XCSS Cascadium, que é um dialeto do SCSS.

Ou seja, fiz um appzinho inteiramente com experimentos meus. Exceto o Sisk que já é um pouco mais conceituado, o TinyComponents e o Cascadium foram minhas escolhas para aprimorar meus estudos e quis criar um simples app que cria documentações a partir do Github.

Basicamente, você cria um repositório com arquivos markdown dentro, define um layout da documentação com um arquivo schema.json, e voilà! Sua documentação está pronta.

Olhe por exemplo essa documentação, criada a partir deste repositório. Também tem essa documentação que fiz para o Sisk, mas usando o tema da Microsoft.

Alguns recursos do md.proj.pw incluem:

  • Suporte à versionamento: cada branch é uma documentação separada. Você pode criar quantas documentações quiser para cada branch que for precisar. Use branches para separar versões, linguas ou outros artefatos interessantes da documentação. Toda alteração no Github reflete aqui, sem precisar editar sua documentação em dois lugares diferentes.
  • Customização: você pode customizar cada parte da sua documentação diretamente do seu repositório do Github. A partir do arquivo schema.json você define:
    • Links: edite os links que aparece no menu de navegação ao lado, editando sua ordem, categoria e apontamentos.
    • Cores: edite as cores primárias do seu projeto, tema e aplique um CSS adicional caso queira.
    • Botões: mostre ou oculte certos botões, como botão de editar acima dessa página, botões de navegação no rodapé e botão de versionamento.
    • Links automáticos: essa documentação interpreta links e associa eles à seu repositório conforme necessitar. Links relativos são suportados e não tiram você dessa documentação. Links externos abrem em outras guias e imagens obtém o conteúdo diretamente do repositório.
    • Título, descrição e ícone: edite o título, descrição e ícone da sua documentação por lá também.
  • Sincronia: tudo o que é exibido aqui é obtido diretamente do seu repositório. Somente repositórios públicos são suportados, pois são acessados pela API do Github. Além disso, pode ser que algumas informações levem até 10 minutos para atualizar, pois usamos cache para evitar flood na API do Github.
  • Para todas as telas: abra sua documentação no celular, tablet, computador ou TV. (quase) todas as telas são suportadas.

O código fonte do proje

Testem o projeto! Está em um alpha, preciso de testes e opiniões. O que você acha?

Carregando publicação patrocinada...
1
1
cyp
Autor
Autor

O site é só um visualizador. Pretendo fazer ele open source, mas ele não builda nada a partir do seu github, sequer clona algum arquivo. Ele lê diretamente a árvore do repositório e conteúdo dos arquivos via API.

Também não precisa buildar sempre que alterar um arquivo. O site reflete a árvore atual da branch que você está vendo, ou seja, se subir um commit, automaticamente atualiza no app.

1
cauachagas

Xuvê se entendi ... Pelo o que eu entendi, ele se parece um pouco com Mkdocs, conhecido pelo pessoal do Python. Só que a sua solução não é fazer um processo de build e hospedar em outro local a documentação (pessoal que utiliza Mkdocs utiliza github pages, por exemplo), mas sim ficar olhandos os arquivos markdown do repositório diretamente (ou seja, não faz build pra atualizar o contéudo. Atualizou um arquivo Markdown já aparece atualizado na aplicação).

Se for isso, é show de bola.

1
cyp
Autor
Autor

É exatamente isso.

Esse app não baixa nada, não builda, somente lê o conteúdo do seu repositório e transforma em uma documentação interagível.

Pretendo tornar código aberto nas próximas semanas. Preciso ajustar alguns códigos, remover umas chaves de API, então você poderá hospedar sua própria documentação, ou se quiser, usar o aplicativo já hospedado.

2