Vuepress: Prerender de Arquivos Markdown com Vue.js

bookmark Vuepress, Vue.js access_time 4/24/2020 person Gabriel Willemann

Vuepress: Surgimento

O Vuepress é uma ferramenta que tem como objetivo gerar sites estáticos e focados em conteúdo. Além disso, outra premissa importantíssima do Vuepress é fazer isso tudo da maneira mais simples e rápida possível.

Esta ferramenta foi criada por Evan You (criador do Vue.js) para documentação de seus projetos. Durante seu trabalho ele não encontrou uma ferramenta que combinasse:

Sites estáticos (Prerender)
Linguagem Markdown
Amigável para SEO
Temas e plugins para customização
Funcionar com Vue.js

O Evan You fez um comparativo entre várias ferramentas e explicou o motivo de ter criado o Vuepress, clique aqui para conferir.

Vuepress: Instalação

Primeiramente, é necessário criar a pasta do projeto e inicializá-lo. Execute os seguintes comandos:

# Criar a pasta do projeto
mkdir vuepress-my-test && cd vuepress-my-test

# Inicializar o package.json
npm init -y

# Instalar o vuepress
npm install vuepress --save

# Criar pasta da documentação
mkdir docs

# Criar página inicial
echo 'Hello Word' > docs/README.md

# Executar o dev server para visualizar o teste
npx vuepress dev docs

Neste caso a documentação vai ficar na pasta "docs", porque é comum as bibliteocas/frameworks terem uma subpasta em seu projeto destinada a documentação.

No site do Vuepress tem um passo a passo da instalação com alguns comandos diferentes, mas o resultado é o mesmo. Na minha opinião dessa maneira é melhor.

Vuepress: Estrutura e Funcionamento

É muito fácil de entender o funcionamento do Vuepress. Basta você criar uma estrutura pastas com arquivos markdown (extensão .md) e o Vuepress converterá isso para arquivos HTML respeitando a hierarquia de pastas.

A página inicial de cada pasta será o arquivo README.md ou index.md e o demais arquivos markdown podem ser acessados por meio de links.

Dentro desses arquivos markdown você escreve um texto e pode configurar várias opções no FrontMatter. Se você não sabe o que é Markdown e FrontMatter, recomendo que você leia estes artigos:

Além disso, você pode incluir código HTML dentro dos arquivos markdown e com possibilidade de acessar componentes Vue.js. Isso é fantástico!

Para processar os arquivos markdown, o Vuepress utiliza a biblioteca markdown-it e você pode configurá-la de diversas maneiras (inclusive com plugins). Leia mais sobre isso neste link.

Vuepress: Tema Padrão (default)

O Vuepress traz um tema padrão simples e que funciona muito bem. Para um funcionamento básico ele não precisa de nenhuma configuração especial, mas é possível fazer pequenas configurações e deixá-lo com uma aparência melhor.

Vuepress: Homepage

Primeiramente, vamos configurar a página inicial (homepage). Para isso, basta você criar um arquivo "README.md" na pasta "docs".

Neste arquivo você pode escrever o que você quiser, porém Vuepress traz alguns facilitadores para criar uma boa página inicial, que seriam: Imagem de banner, título, subtítulo, ação principal, 3 funcionalidades de destaque e uma mensagem de rodapé.

Veja o código abaixo:

---
lang: pt-BR
home: true
heroImage: https://vuepress.vuejs.org/hero.png
heroText: Title
tagline: Subtitle
actionText: Get Started
actionLink: /guide/
features:
  - title: Feature 1
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  - title: Feature 2
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  - title: Feature 3
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
footer: MIT Licensed | Copyright © 2018-present Evan You
---

## My Content

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

O resultado desse arquivo markdown é muito semelhante a página inicial do Vuepress.

Também é possível personalizar o menu superior (navbar). Para adicionar links neste menu, precisamos criar o arquivo de configuração do Vuepress.

O caminho deste arquivo é "docs/.vuepress/config.js" e nele coloque o seguinte conteúdo:

// docs/.vuepress/config.js
module.exports = {
  title: 'Vuepress Test',
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' },
      { text: 'External Link', link: 'https://google.com' },
    ],
  },
};

Veja que existe uma área que se chama themeConfig e que é destinada as configurações pertinentes ao tema. Desta forma, basta adicionar uma configuração "nav" com os links necessários.

A princípio os links Guide e API são links internos e para funcionarem você precisa criar os seguintes arquivos:

docs/guide/README.md
docs/api/README.md

A configuração do menu lateral (sidebar) também é feita no arquivo "docs/.vuepress/config.js". A configuração mais básica é:

// docs/.vuepress/config.js
module.exports = {
  title: 'Vuepress Test',
  themeConfig: {
    sidebar: 'auto',
  },
};

Desta forma é criado um menu lateral e nele são inseridos todos os subtítulos presentes no seu arquivo markdown.

Se você também deseja colocar link para outras páginas, basta você fazer a configuração da seguinte forma:

// docs/.vuepress/config.js
module.exports = {
  title: 'Vuepress Test',
  themeConfig: {
    sidebar: ['/guide/', '/api/'],
  },
};

Você também personalizar esse menu lateral por página, por exemplo, em uma página são exibidos alguns links e em outras páginas são exibidos outros links:

// docs/.vuepress/config.js
module.exports = {
  title: 'Vuepress Test',
  themeConfig: {
    sidebar: {
      '/guide/': ['', 'introduction-guide', 'details-guide'],
      '/api/': ['', 'introduction-api', 'details-api'],
    },
  },
};

Neste caso quando você acessar a página "/guide/", os menus laterais que serão exibidos são "introduction-guide" e "details-guide". E quando você acessar a página "/api/", outros links serão exibidos.

Vale lembrar que para funcionar a configuração acima, você precisa criar os arquivos:

"docs/guide/introduction-guide.md"
"docs/guide/details-guide.md"
"docs/api/introduction-api.md"
"docs/api/details-api.md"

Se você preferir você também pode criar grupos de menus:

// docs/.vuepress/config.js
module.exports = {
  title: 'Vuepress Test',
  themeConfig: {
    sidebar: [
      {
        title: 'Guide',
        children: ['/guide/', '/guide/introduction-guide', '/guide/details-guide'],
      },
      {
        title: 'API',
        children: ['/api/', '/api/introduction-api', '/api/details-api'],
      },
    ],
  },
};

Ou usar grupos diferentes por página:

// docs/.vuepress/config.js
module.exports = {
  title: 'Vuepress Test',
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          title: 'Group Guide',
          children: ['', 'introduction-guide', 'details-guide'],
        },
      ],
      '/api/': [
        {
          title: 'Group API',
          children: ['', 'introduction-api', 'details-api'],
        },
      ],
    },
  },
};

Vuepress: Markdown + FrontMatter + Vue.js

Inicialmente é importante definir o título de cada arquivo markdown e isso pode ser feito de duas formas. A primeira maneira é definindo a tag "title" no frontmatter:

---
title: 'My Guide'
---

Se você não declarar isso no frontmatter, o título será o primeiro título de nível 1 do seu arquivo:

# My Guide

E a principal funcionalidade do Vuepress (na minha opinião) é a possibilidade de inserir código HTML e código Vue dentro do arquivo markdown:

---
title: 'My Guide'
---

# My Guide

## Subtitle 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

<div v-for="i in 5">
  <button>Button {{ i }}</button>
</div>

## Subtitle 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

E você também consegue utilizar componentes Vue.js. Por exemplo, crie um arquivo "MyButton.vue" dentro da pasta "docs/.vuepress/components/" e com o seguinte conteúdo:

<template>
  <button>
    <slot />
  </button>
</template>

<script>
export default {
  name: 'MyButton',
};
</script>

Agora você consegue utilizar esse componente no seu arquivo markdown:

---
title: 'My Guide'
---

# My Guide

## Subtitle 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

<MyButton>My Custom Button</MyButton>

## Subtitle 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Vuepress: Build (Ambiente de Produção)

Lembrando que em ambiente de desenvolvimento executamos o seguinte comando para visualizar as alterações:

npx vuepress dev docs

Mas para gerar os arquivos que serão executados no ambiente de produção (processo chamado de build), precisamos executar os seguintes comandos:

# Alterar variável de ambiente
export NODE_ENV=production

# Se você estiver no Windows, não use o comando acima e use o comando: set NODE_ENV=production

# Executar o build
npx vuepress build docs

Pronto agora é só fazer o upload dos arquivos gerados. Vale ressaltar que neste tutorial eu utilizei o Vuepress na versão 1.4.

Dúvidas ou sugestões é só entrar em contato. Abraço.

Autor

Gabriel Willemann

Software Developer

SHARKLABS