PT | EN

Docsify: o que é e passo a passo completo para usar

Por 13/09/2022 03/10/2024 12 minutos

Neste post

Você em algum momento já observou documentações em sistemas ou sites, e logo após parou para pensar: como eu poderia fazer algo assim de uma forma simples, rápida e que seja tão bonita quanto? Com o docsify, saiba que isso é possível.

Mas antes de começar a falar sobre essa ferramenta, é importante explicar que a documentação de sistemas ou sites é, em si, qualquer material de texto que os times envolvidos no desenvolvimento utilizam para realizar o seu trabalho. 

Na prática, ela serve para descrever um produto digital e contribui para o seu status de autoridade.

Nesse sentido, se você quer desenvolver documentações de maneira fácil e prática, confira as informações desse conteúdo e veja como usar o docsify passo a passo!

O que é docsify e como ele funciona?

Docsify é um gerador de documentação que transforma arquivos Markdown (extensão .md) em uma interface web interativa, sem a necessidade de um processo de construção de arquivos HTML estáticos. 

Ele é projetado para ser leve e intuitivo, permitindo que Desenvolvedores e Programadores criem documentações atraentes e funcionais de forma simples.

O interessante dessa ferramenta é que ela gera seu site em tempo real. Assim, você pode editar seus documentos e ver as alterações refletidas instantaneamente.

De maneira resumida, este é o funcionamento do docsify:

  • Primeiramente, você escreve a sua documentação em arquivos Markdown;
  • Em seguida, o docsify analisa os seus arquivos e começa a gerar as páginas do seu site dinamicamente, à medida que são solicitadas.

Na prática, o docsify cria uma estrutura de navegação para o seu site de forma automática, facilitando a organização e a busca por informações.

Além dessa questão, você pode personalizar a aparência do seu site usando temas e plugins.

Ainda sobre a ferramenta, é válido destacar a sua fácil integração com o GitHub Pages, um serviço de hospedagem oferecido pelo GitHub.

Configure seu primeiro projeto com docsify 

Agora que você já sabe o que é e como funciona o docsify, aprenda a configurar o seu primeiro produto ou sistema nessa ferramenta. Para essa tarefa, é necessário seguir seis etapas específicas. Veja:

  1. Instale o docsify;
  2. Faça a configuração inicial do produto;
  3. Crie o arquivo index.html;
  4. Escreva sua primeira página em Markdown;
  5. Personalize sua documentação;
  6. Crie a estrutura de pastas para a documentação.

Nos tópicos a seguir, saiba mais sobre cada uma dessas etapas! 

1. Instale o docsify 

O docsify pode ser instalado de duas maneiras principais: via Node Package Manager (npm) e por meio de um script tag.

A primeira opção é ideal para quem já possui um ambiente Node.js configurado e deseja ter mais controle sobre a instalação.

Você pode conferir se já possui essa instalação digitando o comando $ node -v em seu terminal. Se estiver tudo certo, ele retornará uma mensagem como essa:

A imagem demonstra como verificar se o Node.js está instalado em sua máquina.

Após realizar a verificação, instale o docsify na sua máquina com o comando $ npm install docsify-cli -g:

A imagem demonstra um passo a passo de como instalar o docsify em sua máquina

Já o script tag é uma alternativa mais simples e rápida, caso não queira se preocupar com a instalação do Node.js.

Para fazer a sua instalação, abra seu editor de texto e crie um arquivo chamado “index.html”. Em seguida, insira o seguinte código nele: 

<!DOCTYPE html>

<html>

<head>

  <meta charset=”UTF-8″>

  <title>Docsify Site</title>

</head>

<body>

  <div id=”app”></div>

  <script>

    window.$docsify = {

      name: ”,

      repo: ”

    }

  </script>

  <script src=”//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js”></script>

</body>

</html>

No mesmo diretório do “index.html”, crie uma pasta chamada “docs” e adicione seus arquivos Markdown (por exemplo, README.md).

Por fim, basta abrir o index.html em um navegador para visualizar a sua documentação.

2. Faça a configuração inicial

Após instalar o docsify, você deve configurar o ambiente inicial do produto para utilizá-lo.

Para isso, basta criar uma pasta com o nome desejado, ir até ela e executar o comando $ docsify init. No exemplo abaixo, foi utilizado softdesign-doc:

A imagem demonstra o passo a passo para iniciar um novo projeto com o docsify.

No local onde perguntam se você deseja reescrever a pasta, apenas confirme com o ok (Y) e prossiga. Se o procedimento for um sucesso, você terá uma estrutura de arquivos igual a essa:

exemplo prático sobre um procedimento necessário para instalar o docsify.

Por fim, entre na pasta e execute o comando $ docsify serve como solicitado para acessar o localhost pelo seu navegador. Assim, você visualizará o produto rodando na porta 3000.

3. Crie o arquivo index.html

Ao concluir o processo anterior, você deve criar o arquivo index.html, conforme mostrado na explicação sobre o uso do script tag. Ao concluir todo o processo acima, passamos para a parte mais interessante do projeto: as configurações do docsify.

Para isso, basta abrir o projeto em qualquer editor de código de sua preferência. Acesse o arquivo index.html e lá você terá todas as configurações iniciais. É nessa etapa que a mágica acontece, dentro do objeto window.$docsify:

Passo a passo do código para criar o arquivo index

4. Escreva sua primeira página em Markdown

Agora que você configurou o seu produto no docsify e criou o arquivo index.html, é hora de adicionar conteúdo à sua documentação. Para essa tarefa, você usará o Markdown.

No diretório do seu produto, vá para a pasta onde você inicializou o docsify e crie um arquivo chamado README.md. Em seguida, abra ele no seu editor de texto e comece a escrever. 

A seguir, veja algumas dicas importantes sobre a sintaxe básica de Markdown que você pode usar:

  • Títulos e subtítulos: use o símbolo de hashtag “#” para criar títulos e subtítulos. O número de # indica o nível do título;
  • Parágrafos: são criados simplesmente escrevendo texto separados por uma linha em branco;
  • Ênfase: utilize *texto* ou _texto_ para itálico, e **texto** ou __texto__ para negrito; 
  • Listas: use – ou * para listas não ordenadas, e números seguidos por um ponto para listas ordenadas;
  • Links: utilize [texto do link](URL) para criar links;
  • Imagens: use ![texto alternativo](URL da imagem) para inserir imagens.

5. Personalize sua documentação

Além das opções anteriores, é válido destacar que existem diferentes formas de personalizar a sua documentação. 

Você pode muito bem criar seu próprio CSS sem problema algum, mas também é possível utilizar um tema já existente. Confira a lista. 

No exemplo abaixo, foi escolhido o theme simple dark. Para importar o seu tema basta remover o atual, que por padrão está associado ao link de CSS “//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css”. 

Depois, é só colocar o link que você escolheu. Feito isso, basta acessar o sistema no navegador que a modificação já estará lá.

Passo a passo para personalizar sua documentação no docsify

6. Crie a estrutura de pastas para a documentação

Também é importante criar a estrutura de pastas para a documentação, visando torná-la mais organizada. Para isso, o primeiro passo é deletar o arquivo README.md na raiz do produto. 

Depois, crie as pastas components e pages. Dentro de components adicione o arquivo sidebar.md, e na pages crie os arquivos home.md e about.md. Sua estrutura deve ficar exatamente assim:

Passo a passo de como criar o menu lateral para a documentação

O segundo passo é abrir o sidebar e criar o menu lateral, como na imagem abaixo:

Passo a passo de como como criar o menu lateral para a documentação

Essa configuração irá renderizar um menu chamado Começando e seus sub-menus Início e Sobre. Na página about, foi renderizado apenas um título:

Nessa imagem, você irá compreender como renderizar o menu Começando.

Já na home, coloque um pouco mais de informações, por exemplo, as tabs e o copy:

Nessa imagem, está o passo a passo de como adicionar informações no docsify.

Após terminar todas essas configurações, veja como fica o resultado:

Integração do docsify com plugins, ferramentas e plataformas

Além de saber como utilizar o docsify, personalizar e configurar a sua documentação, vale conhecer as possibilidades de integração da ferramenta.

Nela, é possível integrar, por exemplo, editores de código e sistemas de controle de versão, para criar um fluxo de trabalho de documentação mais eficiente.

O docsify funciona bem com editores de código populares, como o Visual Studio Code (VS Code), permitindo que você edite arquivos Markdown facilmente.

Além disso, o docsify se integra precisamente com sistemas de controle de versão, como o GitHub.

Ainda, a ferramenta permite a integração com diversos plugins que podem estender suas funcionalidades. Saiba mais sobre esse assunto no tópico a seguir!

Importando plugins na documentação

Para deixar a sua documentação mais fluida, é interessante importar algumas bibliotecas JavaScript. Abaixo, veja alguns plugins que você pode utilizar: 

  • Pagination: necessário para quando houver mais de uma página no sistema;
  • Search: plugin que realiza a busca em toda a documentação. Ideal para os usuários não precisarem acessar página por página para visualizarem apenas uma informação;
  • Copy Code: ao gerar os blocos de códigos, ele cria um atalho de cópia rápida de todo o conteúdo;
  • Tabs: gerador de abas para criar uma navegação entre informações na mesma seção;
  • Prism: biblioteca para ajudar na marcação e identificação da linguagem e sintaxe, que está localizada em determinado bloco de conteúdo. Nos exemplos deste artigo, foi utilizado apenas JavaScript, mas você pode encontrar mais opções.

Confira a seguir a lista necessária para realizar a importação:

<script src=”//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js”></script>

<script src=”//unpkg.com/docsify/lib/plugins/search.min.js”></script>

<script src=”//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js”></script>

<script src=”https://cdn.jsdelivr.net/npm/docsify-tabs@1″></script>

<script src=”//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js”></script>

<script src=”//cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js”></script>Vale ressaltar que você deve realizar a importação dos scripts antes de fechar a tag </body> no arquivo index.html, conforme a imagem abaixo:

Nessa imagem está a lista de importação do docsify.

Configurando os plugins da documentação

É válido destacar que, no tópico anterior, os plugins foram apenas importados. Agora, é preciso realizar a sua configuração geral. Para isso, você irá adicionar as seguintes opções no window.$docsify:

Nessa imagem, você encontra o passo a passo da configuração de plugins.

Veja para que serve cada uma delas:

  • HomePage: é para onde será apontado a página inicial do seu produto, por default ela fica no arquivo README.md da raiz;
  • LoadSideBar: esse booleano é necessário para renderizar o menu lateral;
  • RouterMode: adicionado para não ficar a famosa hashtag na URL da documentação;
  • Name/NameLink: nome e URL de redirecionamento que será renderizado no menu lateral;
  • Auto2top: volta sempre para o início da página;
  • Pagination: como o próprio nome já diz, é um plugin para paginação;
  • Search: é o plugin de busca. Possui a mesma função do pagination, mas é preciso fazer algumas modificações;
  • Tabs: é o tipo de tema para renderizar as abas. Neste caso, foi escolhido o material design.

Vantagens do docsify para empresas

Com base nas informações apresentadas até aqui, você já sabe os principais pontos sobre o docsify. Agora, veja as vantagens do uso dessa ferramenta para empresas:

  • Facilidade de manutenção: a documentação em Markdown permite atualizações rápidas e intuitivas, garantindo que as informações estejam sempre atualizadas;
  • Escalabilidade: a estrutura flexível do docsify facilita a adição de novas páginas e seções, tornando-o ideal para companhias em crescimento que precisam expandir sua documentação conforme necessário;
  • Melhoria na colaboração: a integração com plataformas como GitHub permite que os times trabalhem simultaneamente na documentação, melhorando a qualidade e promovendo uma maior colaboração;
  • Sistema de busca eficiente: o sistema em tempo real ajuda os usuários a encontrar informações relevantes rapidamente, melhorando a navegação e a experiência do usuário.

Conclusão

O docsify, como você viu ao longo deste artigo, é uma ferramenta leve e prática, que não requer bancos de dados ou arquivos HTML estáticos. Assim, ele facilita a criação e a manutenção de documentações. 

Ainda, a sua integração com GitHub Pages oferece uma hospedagem simples e eficaz, permitindo que a sua documentação esteja sempre acessível e atualizada.

Por conta desses e de outros benefícios citados, vale a pena adotar essa ferramenta para otimizar os seus processos de documentação.

Quer melhorar os processos da sua empresa? Conheça a consultoria em agilidade e práticas de desenvolvimento da SoftDesign! Se preferir, entre em contato com nossos especialistas diretamente!

Perguntas frequentes

Confira a seguir algumas perguntas comuns sobre o docsify.

O que é docsify e para que serve?

Docsify é uma ferramenta que gera sites de documentação a partir de arquivos Markdown. Ele é utilizado para criar e manter documentações de forma simples e sem a necessidade de bancos de dados ou arquivos HTML estáticos.

Como instalar o docsify?

Você pode instalar o docsify via npm com npm install -g docsify-cli ou adicionar um script tag com src=”//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js” ao seu arquivo HTML.

Quais são as vantagens do docsify?

O docsify facilita a manutenção da documentação, é escalável, melhora a colaboração entre equipes e possui um eficiente sistema de busca em tempo real.

Aproveite e veja também:

desenvolvimento de software docsify documentações negócios digitais

Neste post

Foto do autor

Niag Alves

Software Engineer Frontend na SoftDesign. Graduado em Análise e Desenvolvimento de Sistemas (FAQI) e pós graduado em Engenharia da Computação (Uninter). Apaixonado por tecnologia e inovação, atua há mais de sete anos com projetos voltados para web.

Posts relacionados

Quer saber mais sobre
Design, Estratégia e Tecnologia?