Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 

README.md

Introdução

Esse projeto é baseado no repositório "mixu/markdown-styles".

Se você precisa ou pretende fazer modificações, recomendo fortemente o fork do projeto original. Há outros estilos e layouts nele, bem como orientações de como criar seu prório tema, mas eu foquei em um tema exclusivo pela praticidade, visando simplificar ao máximo o uso.

Pré-requisitos

node / npm

Você precisará ter o "npm" instalado para conseguir executar. Além disso, é necessário ter instalado globalmente o pacote do markdown-styles e localmente o do replace-in-files, porém essas instalações são feitas automaticamente.

Como usar

Baixe o projeto e execute o comando abaixo na pasta:

npm install

Esse comando baixará as dependências do projeto e instalará globalmente (o que permite o comando no console).

A estrutura da solução é enxuta. Basta você escrever seus arquivos markdown (md) dentro da pasta input, conforme o arquivo de exemplo (index.md) e executar o comando abaixo:

npm run generate

Internamente, o comando original sendo executado é o seguinte:

generate-md --layout mixu-bootstrap-2col --input ./input --output ./generated

Caso você precise editá-lo, pode fazê-lo no arquivo package.json ou executando diretamente uma versão alternativa do mesmo no console.

O conteúdo da pasta generated (que só aparece após a geração e não é comitada no repositório) contém o HTML gerado automaticamente à partir dos arquivos markdown (*.md).

Os arquivos não são apagados na pasta numa nova geração, sendo interessante apagá-los manualmente caso a modificação não tenha sido exclusiva em seus conteúdos.

Data da versão

Se o arquivo index.md tiver sido "comitado" no repositório antes da geração (o que é recomendável), a data do commit será apresentada no arquivo (conforme exemplo), no lugar da variável @version.

Sendo assim, é recomendável também que você mantenha toda sua documentação no próprio arquivo index.md, sem alterar seu nome ou pode, é claro, fazer as alterações ou incluir mais arquivos, mas aí precisará customizar o comando de geração.

Para gerar sem executar a atualização da data da versão use:

npm run generate:html

Vantagens

As vantagens de uso dessa ferramenta são:

  • Documentação controlada como código no repositório
  • Disseminação do conhecimento sobre repositórios entre analistas
  • Facilitação da exibição das regras em formato website (publicação)
  • A linguagem markdown é mais simples que HTML
  • Apresentação da data da versão no HTML

About

Gerador de documentação HTML à partir de arquivos markdown

Topics

Resources

Releases

No releases published

Packages

No packages published
You can’t perform that action at this time.