SHARKLABS
menu

SHARKLABS

Aprenda a Criar um Blog com Vuepress

Página Inicial
/
Vuepress
/
Aprenda a Criar um Blog com Vuepress
bookmark Vuepress, Vue.js access_time

Vuepress para Blogs

Quando Evan You criou o Vuepress, seu foco era criar uma ferramenta para facilitar a documentação de seus projetos, ou seja, criar uma ferramenta que gerasse sites estáticos, amigável para SEO e compatível com markdown e Vue.js.

Inicialmente seu foco não era criar blogs, mas depois de lançada a versão 0.1 foram muitas as solicitações para aperfeiçoar o Vuepress. A partir da versão 1.0 que o sistema de plugins e temas foi aprimorado para gerar blogs e outros tipos de websites.

Plugin para Blog

Por padrão o Vuepress simplesmente converte sua estrutura de arquivos e pastas em arquivos HTML, porém blogs nem sempre seguem essa estrutura e muitas vezes precisam de URL's especiais para seus artigos.

Foi pensando nisso que o time do Vuepress criou um plugin para fornecer funcionalidades úteis especificamente para blogs. De uma maneira bem sintética esse plugin pega os artigos gera URL's especiais e classificá-los por data para paginação.

Tema para Blog

O tema padrão do Vuepress não utiliza o plugin citado anteriormente, uma vez que ele (o tema) é destinado para documentação de projetos técnicos. Por isso o time do Vuepress desenvolveu um tema específico para blogs e que utiliza todas as funcionalidades do plugin.

Antes de continuarmos, recomendo que você tenha pelo menos uma noção básica sobre o Vuepress. Ou seja, se você não nunca usou o Vuepress, é bom dar uma lida neste artigo que eu explico os fundamentos e o seu funcionamento.

Instalação

A instalação do blog deve começar com os seguintes comandos:

# Criar a pasta do projeto
mkdir vuepress-my-blog
cd vuepress-my-blog

# Inicializar o package.json
npm init -y

# Instalar o vuepress
npm install vuepress --save

# Instalar o tema para blogs
npm install @vuepress/theme-blog --save

Feito isso, vamos configurar a estrutura de diretório do blog.

# Criar pastas
mkdir blog
mkdir blog/_posts
mkdir blog/.vuepress

Dentro da pasta "blog/_posts" é onde ficarão os arquivos markdown dos artigos. Já a pasta "blog/.vuepress" é destinada para os arquivos de configuração.

Configuração Básica

Agora crie o arquivo "config.js" dentro da pasta "blog/.vuepress/". Neste arquivo coloque o seguinte conteúdo:

// blog/.vuepress/config.js
module.exports = {
  title: 'My Blog',
  theme: '@vuepress/theme-blog',
  themeConfig: {},
};

Essa é a forma mais básica que o arquivo de configuração pode ter. Primeiramente declaramos o título do blog, depois declaramos o nome do tema utilizado e definimos a propriedade "themeConfig" que é destinada a configurações do tema.

Criar um artigo (post)

A partir de agora vamos criar um artigo de testes para ver nosso blog em funcionamento. Crie o arquivo "2020-04-29-meu-post-inicial.md" dentro da pasta "blog/_posts/" e coloque o seguinte conteúdo nele:

---
title: My Post
date: 2020-4-29
tags:
  - assunto-qualquer
  - outro-assunto
author: Gabriel Willemann
location: Brasil
---
# My Post

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum sed urna scelerisque, sodales ante ac, iaculis erat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum sed urna scelerisque, sodales ante ac, iaculis erat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum sed urna scelerisque, sodales ante ac, iaculis erat.

Veja que o artigo deve seguir a sintaxe Markdown com Frontmatter na parte superior. Se você tem dúvidas sobre essa sintaxe recomendo que você abra os seguintes links:

Para ver o blog em funcionamento, execute o comando abaixo no terminal e depois abra o navegador com o endereço http://localhost:8080/:

npx vuepress dev blog

Pronto! O blog já está funcionando. Porém você pode aperfeiçoar a aparência do seu blog por meio de algumas configurações, é o que veremos a seguir.

Para personalizar o menu superior com outros links, basta adicionar esta configuração:

module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Tags', link: '/tag/' },
      { text: 'Google', link: 'https://www.google.com/' },
    ],
  },
};

Também é possível colocar links de redes sociais no rodapé:

module.exports = {
  themeConfig: {
    footer: {
      contact: [
        { type: 'github', link: 'https://github.com/gabrielwillemann/' },
        { type: 'twitter', link: 'https://twitter.com/gabrielwilleman' },
      ],
    },
  },
};

Paginação

A paginação padrão do Vuepress é 5 artigos por pagina, mas você pode alterar para qualquer outro valor:

module.exports = {
  themeConfig: {
    globalPagination: {
      lengthPerPage: 10,
    },
  },
};

Progressive Web App (PWA)

Também é possível adicionar suporte à Progressive Web App, ou seja, o seu blog pode ser instalado e pode ser aberto mesmo offline:

module.exports = {
  themeConfig: {
    pwa: {
      serviceWorker: true,
      updatePopup: true,
    },
  },
};

Personalizando a URL

Por padrão a URL gerada para os artigos segue o padrão "ano/mês/dia/titulo", conforme o exemplo abaixo:

https://myblog.com/2020/04/29/meu-post-inicial/

Para personalizar suas URL's você precisa alterar a propriedade "itemPermalink" no arquivo "config.js". Abaixo segue a configuração padrão que você pode mudar como preferir.

module.exports = {
  themeConfig: {
    directories: [
      {
        id: 'post',
        dirname: '_posts',
        path: '/',
        itemPermalink: '/:year/:month/:day/:slug',
      },
    ],
  },
};

Se existir um artigo que precise de uma URL específica (fuja da regra) é só declarar essa URL no frontmatter (propriedade "permalink"):

---
title: My Post
date: 2020-4-29
tags:
  - assunto-qualquer
  - outro-assunto
author: Gabriel Willemann
location: Brasil
permalink: /url-especifica-para-este-artigo
---
# My Post

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum sed urna scelerisque, sodales ante ac, iaculis erat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum sed urna scelerisque, sodales ante ac, iaculis erat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum sed urna scelerisque, sodales ante ac, iaculis erat.

Vuepress + SEO

Se sua intenção é fazer um blog, você sabe da importância do SEO (Search Engine Optimization). Por isso vou mostrar algumas configurações relevantes.

A primeira dica é definir uma propridade description no frontmatter de cada artigo, uma vez que isso será usado para gerar a Meta Tag Description.

---
description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
---

A segunda dica é configurar um sitemap. Coloque esta configuração no arquivo config.js:

// blog/.vuepress/config.js
module.exports = {
  themeConfig: {
    sitemap: {
      hostname: 'https://myblog.com',
    },
  },
};

A terceira dica é definir o idioma do seu blog. Isso também pode ser feito no seu arquivo de configuração:

// blog/.vuepress/config.js
module.exports = {
  locales: {
    '/': {
      lang: 'pt-BR',
    },
  },
};

A quarta dica é usar a URL canônica. Neste caso você precisar instalar e configurar o plugin vuepress-plugin-canonical:

# Instalar o plugin
npm install vuepress-plugin-canonical --save

// blog/.vuepress/config.js
module.exports = {
  plugins: [
    [
      'vuepress-plugin-canonical',
      {
        baseURL: 'https://myblog.com',
        stripExtension: true,
      },
    ],
  ],
};

Em relação a outras Meta Tags importantes, você pode instalar o plugin vuepress-plugin-seo:

# Instalar o plugin
npm install vuepress-plugin-seo --save

// blog/.vuepress/config.js
module.exports = {
  plugins: [['vuepress-plugin-seo']],
};

Vale ressaltar que a propriedade "plugins" do arquivo "config.js" é um array, ou seja, permite a declaração de vários plugins (clique aqui para saber mais).

Se ainda assim, você precisar de alguma Meta Tag especial, basta você declará-la no frontmatter de cada artigo.

---
meta:
  - name: custom-meta-tag
    content: custom-content
---

Outras Configurações

Para inserir alguma Tag HTML no cabeçalho do seu blog, basta adicionar a propriedade "head" no arquivo "config.js":

// blog/.vuepress/config.js
module.exports = {
  head: [
    ['link', { rel: 'icon', href: '/assets/img/icon-32x32.png', sizes: '32x32' }],
    ['link', { rel: 'icon', href: '/assets/img/icon-192x192.png', sizes: '192x192' }],
    ['link', { rel: 'apple-touch-icon-precomposed', href: '/assets/img/icon-180x180.png' }],
    ['meta', { name: 'msapplication-TileImage', content: '/assets/img/icon-270x270.png' }],
  ],
};

Além disso, quando o blog é acessado pela primeira vez, por padrão o Vuepress faz o Prefetch de todos os artigos. Ou seja, ele carrega todos os arquivos no primeiro acesso (pode ficar um pouco lento). Para desabilitar isso faça a seguinte configuração:

// blog/.vuepress/config.js
module.exports = {
  shouldPrefetch: () => false,
};

Redirecionamentos 301 / 302

Caso você precise fazer redirecionamentos 301 ou 302, você precisa fazer isso no seu servidor HTTP. Se você estiver usando Apache, você pode fazer no ".htaccess". Se você estiver usando Nginx, você pode fazer isso no arquivo de configuração da pasta "sites-available".

Google Analytics

Para configurar o Google Analytics, basta você instalar o plugin @vuepress/plugin-google-analytics e na configuração passar o GA ID:

// blog/.vuepress/config.js
module.exports = {
  plugins: [['@vuepress/plugin-google-analytics', { ga: 'XX-000000000-0' }]],
};

Melhorando a Aparência do Tema

É possível fazer alguns ajustes na aparência do tema. Basta criar o arquivo "palette.styl" na pasta "blog/.vuepress/styles" e modificar as variáveis listadas neste link.

Outra possibilidade é herdar o tema e mudar somente alguns componentes. No site oficial do Vuepress tem um passo a passo que auxilia neste processo.

Se você não gostar do visual do tema padrão, você pode criar seu próprio tema. Inclusive este blog foi construído com Vuepress e eu criei meu próprio tema. O tema que eu desenvolvi está disponível para download neste link e você pode usá-lo à vontade.

Além disso, o repositório Awesome Vuepress traz uma série de temas mantidos pela comunidade. Fique à vontade para escolher o seu preferido.

Lembrando que cada tema tem configurações diferentes e o nome das propriedades pode mudar entre um e outro.

Imagens

Caso você precise inserir imagens nos seus artigos, você pode colocá-las na pasta "blog/.vuepress/public". Para mais informações sobre a manipulação de assets, acesse este link.

Migração do Wordpress para Vuepress

Para quem tem um blog construído com Wordpress e quer migrar para Vuepress, deve estar com a dúvida: Como vou exportar os meus artigos/posts?

Então, primeiramente você exporta todos os artigos e depois você utiliza esta biblioteca para converter seus posts para markdown.

É um processo rápido e simples. Talvez você tenha fazer ajustes na formatação de alguns artigos. Mas não se preocupe, isso não é complicado (somente pequenas correções).

Ambiente de Produção

Para gerar os arquivos do ambiente de produção é só executar os 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 blog

Por fim, quero destacar que neste artigo eu utilizei o Vuepress na versão 1.4 e o @vuepress/theme-blog na versão 2.2.

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

Autor
"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." Martin Fowler