Documentação no Github Pages com Docsify

janeiro 24, 2022fevereiro 7, 2022 Luiz Antônio Rech 0 comentários docsify, documentação, githubpages

Antes de mais nada, você viu que estamos no YOUTUBE? Isso mesmo! Corre lá:

Nesse rápido tutorial iremos ver como utilizar o Docsify para gerar documentação no mesmo projeto com o Github Pages.

Docsify

O Docsify nada mais é do que um gerador de site que utiliza como fonte arquivos .md. Ideal para gerar documentações com templates padronizados.

Instalando o Docsify

Você pode conferir todo o processo de instalação e inicialização AQUI. Mas irei resumir ainda mais nesse post.

Instalação:

npm i docsify-cli -g

Inicialização:

Dentro da pasta do seu projeto execute o seguinte comando:

docsify init ./docs

Como pode ser visto, foi criado uma pasta chamada docs que contém os arquivos da sua documentação.

Personalizando a documentação

Neste post iremos realizar uma personalização rápida e simples, como pode ser visto a seguir.

Basicamente personalizamos o index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Vue Axios Http</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
        name: "Vue Axios Http",
        repo: "https://github.com/aluizrech/vue-axios-http",
        logo: "assets/logo-coffops.png",
        homepage: "index.md",
        loadSidebar: "menu.md",
        maxLevel: 4,
        subMaxLevel: 3,
        search: {
            noData: {
                "/": "Sem resultado!"
            },
            paths: 'auto',
            placeholder: {
                "/": "Pesquisar",
            },
        },
    }
  </script>
  <!-- Docsify v4 -->
  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>
</html>

Também foram alterados os demais arquivos, conforme pode ser visto no github desse projeto de exemplo.

Executando o projeto localmente

Para visualizar o resultado, basta executar o comando a seguir.

docsify serve docs

Configurando no github

Após realizar o commit de todos os seus arquivos, basta configurar o seu github.

Acesse a aba Settings/Configurações e depois em pages.

Depois selecione a branch e o diretório docs criado clique em salvar.

Conclusão

Para concluir, podemos visualizar a documentação recém criada no link.