Hugo - Guia de Início Rápido

Guia de início rápido para instalação e uso do Hugo

14 minutos de leitura

Conforme já havia dito aqui, o Hugo é um excelente gerador de sites estáticos. Sendo assim, decidi ajudar os iniciantes, traduzindo o Quickstart da documentação oficial. Sendo assim, mãos à obra.

Construindo uma Estante de Livros

Neste guia de início rápido, nós vamos construir uma estante de livros, onde vamos listar os livros e suas análises.

Nota: Este guia de início rápido, depende das características introduzidas no Hugo v0.15, portanto você vai precisar da versão v0.15, ou posterior. Se você tiver uma versão anterior do Hugo, você vai precisar atualizar antes de prosseguir.

Passo 1. Instalando o Hugo

Vá até os lançamentos do Hugo e baixe a versão apropriada para o seu sistema (Windows/Linux/MacOS) e arquitetura (32/64bits).

Salve o executável principal como hugo (ou hugo.exe no Windows) em algum lugar do seu PATH, pois vamos usá-lo no próximo passo.

Instruções mais completas, estão disponíveis em Instalando o Hugo.

Se você estiver no Windows, este guia de início rápido assumirá que você está usando o Git Bash (também conhecido como Git para Windows). Então, todos os comandos começarão, com o caractere do prompt do Bash (que é $).

Uma vez que o hugo esteja instalado, tenha certeza de executar o comando help para verificar a instalação do hugo. Abaixo, você pode ver abreviada, parte da saída do comando help.

$ hugo help
hugo is the main command, used to build your Hugo site.

Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.

Complete documentation is available at http://gohugo.io/.

Você pode verificar a sua versão do hugo, usando o comando abaixo.

$ hugo version
Hugo Static Site Generator v0.15 BuildDate: 2015-11-26T11:59:00+05:30

Passo 2. Preparando o site de estante de livros no Hugo

O Hugo tem comandos, que nos permite preparar rapidamente, um site gerenciado pelo Hugo. Navegue até um local conveniente em seu sistema de arquivos, então crie um novo site Hugo de estante-de-livros, executando o seguinte comando.

$ hugo new site estante-de-livros

Vá para o diretório estante-de-livros, então você verá o seguinte layout.

$ tree -a
.
|-- archetypes
|-- config.toml
|-- content
|-- data
|-- layouts
|-- static
`-- themes

6 directories, 1 file

Conforme informado na saída do comando, o diretório estante-de-livros tem 5 subdiretórios e 1 arquivo. Vamos olhar cada um deles, um a um.

  • archetypes: Você pode criar novos arquivos de conteúdo no Hugo, usando o comando hugo new. Quando você executa o comando, ele adiciona algumas propriedades de configuração ao post, como data e título. Archetype permite que você defina sua própria configuração, que será adicionado ao pré-texto do post, sempre que o comando hugo new é usado.

  • config.toml: Todo site deve ter um arquivo de configuração na raiz. Por padrão, o arquivo de configuração usa o formato TOML, mas você também pode usar os formatos YAML ou JSON. TOML é um formato de arquivos mínimo, cujo formato é fácil de ler, devido à clara semântica. As configurações definidas no config.toml são aplicadas a todo o site. Estas configurações, incluem a baseURL e o title do site.

  • content: Aqui será onde você vai armazenar o conteúdo do site. Dentro do content, você irá criar sub-diretórios para diferentes seções. Vamos supor que seu site tem três seções – blog, artigo e tutorial. Então, você terá três diferentes diretórios, cada um deles, dentro do diretório content. O nome da seção, ex. blog, artigo ou tutorial, que será usado pelo Hugo para aplicar o layout específico para aquela seção.

  • data: Este diretório é usado para armazenar os arquivos de configuração, que podem ser usados pelo Hugo quando gerando seu site. Você pode escrever estes arquivos, nos formatos YAML, JSON ou TOML.

  • layouts: O conteúdo dentro deste diretório, é usado para definir como seu conteúdo, será convertido para um site estático.

  • static: Este diretório é usado para armazenar todo o conteúdo estático que seu site precisará, tais como imagens, CSS, JavaScript ou outro conteúdo estático.

Passo 3. Adicionar conteúdo

Agora, vamos adicionar um post, à nossa estante-de-livros. Nós usaremos o comando hugo new para criar um post. Em Janeiro, eu li o livro “Good to Great: Empresas feitas para vencer”, então vou começar criando um post para ele. Tenha certeza que você esteja, dentro do diretório estante-de-livros.

$ hugo new post/good-to-great-empresas-feitas-para-vencer.md
/Users/shekhargulati/estante-de-livros/content/post/good-to-great-empresas-feitas-para-vencer.md created

O comando acima vai criar um novo diretório post, dentro do diretório estante-de-livors/content e criar o arquivo good-to-great-empresas-feitas-para-vencer.md dentro dele.

$ tree -a content
content
`-- post
    `-- good-to-great-empresas-feitas-para-vencer.md

1 directory, 1 file

O conteúdo do arquivo good-to-great-empresas-feitas-para-vencer.md, se parecerá como exibido abaixo.

+++
date = "2016-02-14T16:11:58+05:30"
draft = true
title = "good to great empresas feitas para vencer"

+++

O conteúdo dentro do +++ é a configuração TOML para o post. Esta configuração é chamada pré-texto. Ela permite a você definir a configuração do post, juntamente com seu conteúdo. Por padrão, cada post terá as configurações de propriedades, conforme exemplo acima.

  • date - especifica a data e hora, na qual o post foi criado.
  • draft - especifica que o post, ainda é um rascunho e não está pronto para a publicação. Então, ele não estará no site gerado.
  • title - especifica o título do post.

Vamos adicionar uma pequena análise do livro Good to Great: Empresas feitas para vencer.

+++
date = "2016-02-14T16:11:58+05:30"
draft = true
title = "Análise do livro Good to Great: Empresas feitas para vencer"

+++

Eu li **Good to Great: Empresas feitas para vencer em Janeiro de 2016**. Uma leitura incrível, compartilhando análises detalhadas em como boas companhias se tornam grandes.

Passo 4. Servir o conteúdo

Hugo tem um servidor embutido, que pode servir o conteúdo do seu site, então você pode pré-visualizar o conteúdo. Você também pode usar o servidor do Hugo em produção. Para servir o conteúdo, execute o comando a seguir dentro do diretório estante-de-livro.

$ hugo server
0 of 1 draft rendered
0 future content
0 pages created
0 paginator pages created
0 tags created
0 categories created
in 9 ms
Watching for changes in /Users/shekhargulati/estante-de-livros/{data,content,layouts,static}
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Isto vai iniciar o servidor na porta 1313. Você pode visualizar seu blog em http://localhost:1313/. Quando você clicar no link, você não verá nada. Há algumas razões para isso:

  1. Como você pode ver na saída do comando hugo server, o Hugo não gerou o draft (rascunho). O Hugo somente irá gerar os drafts (rascunhos), se você passar o argumento buildDrafts para o comando hugo server.
  2. Nós não definimos como o conteúdo Markdown deveria ser gerado. Nós temos que definir um tema, que o Hugo possa usar. Nós vamos fazer isso no próximo passo.

Para gerar os rascunhos, rode novamente o comando exibido abaixo.

$ hugo server --buildDrafts
1 of 1 draft rendered
0 future content
1 pages created
0 paginator pages created
0 tags created
0 categories created
in 6 ms
Watching for changes in /Users/shekhargulati/bookshelf/{data,content,layouts,static}
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Se você for até http://localhost:1313/, ainda não verá nada, pois ainda não definimos um tema que o Hugo deve usar.

Passo 5. Adicionar um tema

Os temas fornecem o layout e modelo, que será usado pelo Hugo para gerar seu site. Existem vários temas livres, que você pode usar em https://themes.gohugo.io/.

O Hugo não vem com um tema padrão, permitindo que o usuário possa escolher, qual tema melhor se aplica ao seu projeto.

Os temas devem ser adicionados no diretório themes, que está dentro no diretório principal.

$ cd themes

Agora, você pode clonar um, ou mais, temas dentro do diretório themes. Nós vamos usar o tema robust, mas em um commit (em seu histórico), que funcione com este guia de início rápido.

$ git clone https://github.com/dim0627/hugo_theme_robust.git
$ (cd hugo_theme_robust; git checkout b8ce466)

Deixe o diretório themes.

$ cd ..

Inicie o servidor novamente.

$ hugo server --theme=hugo_theme_robust --buildDrafts
1 of 1 draft rendered
0 future content
1 pages created
2 paginator pages created
0 tags created
0 categories created
in 10 ms
Watching for changes in /Users/shekhargulati/estante-de-livros/{data,content,layouts,static,themes}
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Nota: Se o Hugo não encontrar o tema especificado, dentro do diretório themes, ele retornará uma exceção, conforme exibido abaixo.

FATAL: 2016/02/14 Unable to find theme Directory: /Users/shekhargulati/estante-de-livros/themes/robust

Para ver o seu site, você pode ir até http://localhost:1313/. Você verá o site, conforme exibido abaixo.

Exemplo do Tema Robust no Hugo

Vamos entender o layout do tema. Um tema consiste no seguinte:

  • theme.toml - é o arquivo de configuração do tema, que fornece informação sobre o tema, como nome e descrição do tema, detalhes do autor e licença do tema.

  • images - este diretório contêm duas imagens – screenshot.png e tn.png. O screenshot.png é a imagem da visualização em lista e o tn.png é a imagem da visualização de um post.

  • layouts - este diretório contêm diferentes visualizações, para diferentes tipos de conteúdo. Cada tipo de conteúdo deve ter dois arquivos single.html e list.html. O single.html é usado para gerar uma única parte do conteúdo. O list.html é usado para gerar uma lista de itens de conteúdo. Por exemplo, você vai usar o list.html para visualizar todos os posts, que tenham a tag programação.

  • static - este diretório armazena todos os recursos usados pelo tema. Recursos estáticos podem incluir bibliotecas JavaScript, como jQuery, estilos CSS, images ou qualquer outro conteúdo estático. Este diretório será copiado para o site final, quando for gerado.

Passo 6. Usar múltiplos temas

Você pode testar facilmente, diferentes layouts, alternando entre diferentes temas. Vamos supor que queiramos testar o tema bleak. Nós simplesmente clonamos o tema bleak, dentro do diretório estante-de-livros/themes.

$ git clone https://github.com/Zenithar/hugo-theme-bleak.git

Reinicie o servidor usando o tema hugo-theme-bleak, conforme demonstrado abaixo.

$ hugo server --theme=hugo-theme-bleak --buildDrafts

Agora, o site irá usar o tema bleak e será gerado de forma diferente, conforme exibido abaixo.

Exemplo do Tema Bleak no Hugo

Passo 7. Atualize o config.toml e o ative recarregamento automático

Reinicie o servidor com o tema robust, conforme nós usaremos neste guia de início rápido.

$ hugo server --theme=hugo_theme_robust --buildDrafts --watch

O site usa valores padrão, que vêm especificado em estante-de-livros/config.toml. Vamos atualizar a configuração.

baseURL = "http://exemplo.org/"
languageCode = "pt-br"
title = "Análise de Livros por Shekhar Gulati"

[Params]
  Author = "Shekhar Gulati"

Quando você usa o argumento watch no comando hugo server, ele passa a ter o suporte nativo para recarregamento automático. Então, assim que você salvar as alterações, suas alterações serão aplicadas e a página será recarregada. Você verá as alterações, conforme exibidas abaixo.

Exemplo de Recarregamento Automático

O mesmo se aplica aos logs do servidor Hugo. Assim que você alterar o arquivo de configuração, o Hugo aplica estas alterações às páginas afetadas.

Config file changed: /Users/shekhargulati/estante-de-livros/config.toml
1 of 1 draft rendered
0 future content
1 pages created
2 paginator pages created
0 tags created
0 categories created
in 11 ms

Passo 8. Personalizar o tema robust

O tema robusté um bom início para nossa estante-de-livros online, mas nós queremos personalizá-lo um pouco, para uma aparência adequada para uma estante-de-livros. O Hugo torna muito fácil, a personalização dos temas. Você também pode criar seus temas, mas nós não faremos isso hoje. Se você deseja criar seu próprio tema, então você deve consultar a documentação do Hugo.

A primeira alteração, que temos que fazer é usar uma imagem padrão diferente, ao invés da usada no tema. A imagem padrão do tema que é usada, tanto na visualização em lista, quanto na individual, fica em themes/hugo_theme_robust/static/images/default.jpg. Nós podemos facilmente sobrepô-la, criando uma simples estrutura de diretório, dentro no diretório static.

Crie um diretório images, dentro do diretório estante-de-livros/static e copie uma imagem com o nome default.jpg dentro dele. Nós vamos usar a imagem padrão exibida abaixo.

Imagem Padrão

O Hugo vai sincronizar as alterações e recarregar o site para usar a nova imagem, conforme exibido abaixo.

Site com Nova Imagem Padrão

Agora, nós temos que alterar o layout da página de índice, assim somente as imagens serão exibidas, ao invés do texto. O arquivo index.html dentro do diretório layouts do tema, referencia um trecho da lista li, que gera a visualização em lista, conforme exibida abaixo.

<article class="li">
  <a href="{{ .Permalink }}" class="clearfix">
    <div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
    <div class="detail">
      <time>{{ with .Site.Params.DateForm }}{{ $.Date.Format . }}{{ else }}{{ $.Date.Format "Mon, Jan 2, 2006" }}{{ end }}</time>
      <h2 class="title">{{ .Title }}</h2>
      <div class="summary">{{ .Summary }}</div>
    </div>
  </a>
</article>

Crie um novo arquivo li.html dentro do diretório estante-de-livros/layouts/_default. Copie o conteúdo exibido abaixo, para o li.html. Nós removemos os detalhes do livro, então somente a imagem do mesmo será exibida.

<article class="li">
  <a href="{{ .Permalink }}" class="clearfix">
    <div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
  </a>
</article>

Agora, o site será gerado, conforme exibido abaixo.

Tema Robust com Somente Imagem na Lista

Também, queremos remover a informação relacionada ao tema do rodapé. Então, criamos um novo diretório partials, dentro do estante-de-livros/layouts. Nele, crie um novo arquivo default_foot.html com o conteúdo copiado do arquivo layouts/partials/default_foot.html do tema. Substitua a seção do rodapé, com o trecho abaixo.

<footer class="site">
  <p>{{ with .Site.Copyright | safeHTML }}{{ . }}{{ else }}&copy; {{ $.Site.LastChange.Year }} {{ if isset $.Site.Params "Author" }}{{ $.Site.Params.Author }}{{ else }}{{ .Site.Title }}{{ end }}{{ end }}</p>
  <p>Gerado por <a href="http://gohugo.io" target="_blank">Hugo</a>,</p>
</footer>

Nós também queremos remover a barra lateral da direita. Copie o arquivo index.html do diretório layouts do tema, para o diretório estante-de-livros/layouts. Remova a seção relacionada à barra lateral, do HTML:

<div class="col-sm-3">
  {{ partial "sidebar.html" . }}
</div>

Até agora estamos usando a imagem padrão, mas nós podemos querer usar a imagem do livro, associando-a então a ele. Cada análise de livro, vai definir essa configuração em seu pré-texto. Atualize o good-to-great-empresas-feitas-para-vencer.md conforme abaixo.

+++
date = "2016-02-14T16:11:58+05:30"
draft = true
title = "Análise do livro Good to Great: Empresas feitas para vencer"
image = "good-to-great.jpg"
+++

Eu li **Good to Great: Empresas feitas para vencer em Janeiro de 2016**. Uma leitura incrível, compartilhando análises detalhadas em como boas companhias se tornam grandes. Este livro também é sobre como as companhias se tornam grandes, mas como nós podemos aplicar, vários ensinamentos a nós mesmo. Conceitos como 5 níveis de liderança, princípio do ouriço, paradoxo de stockdale, são igualmente aplicáveis a indivíduos.

Pegue uma imagem (legalmente) de algum lugar, nomeie como good-to-great.jpg, e coloque no diretório estante-de-livros/static/images.

Após adicionar mais alguns livros à sua estante, a estante se parecerá como a exibida abaixo. Estes são alguns dos livros que eu li, no ano passado.

Estante de Livros no Hugo

Passo 9. Torne público os posts

Até agora os posts que nós escrevemos estão no modo rascunho. Para mudar de rascunho para público, você pode executar um comando, ou alterar manualmente o definição do draft para false.

$ hugo undraft content/post/good-to-great-empresas-feitas-para-vencer.md

Agora, você pode iniciar o servidor sem o argumento buildDrafts.

$ hugo server --theme=hugo_theme_robust --watch

Passo 10. Integrar o Disqus

O Disqus permite a você, integrar comentários em seu site estático. Para habilitar o Disqus, você precisa apenas configurar o disqusShortname no config.toml, conforme exibido abaixo.

[Params]
  Author = "Shekhar Gulati"
  disqusShortname = <seu apelido disqus>

Agora, os comentários estarão ativados em seu blog.

Disqus no Hugo

Passo 11. Gerar o site

Para gerar o código fonte do site Hugo, você pode fazer o deploy de seu site na GitHub Pages, primeiro edite estante-de-livros/config.toml, trocando a linha baseURL para:

baseURL = "https://<seu usuário GitHub>.github.io/estante-de-livros/"

Então, digite o seguinte comando.

$ hugo --theme=hugo_theme_robust

0 draft content
0 future content
5 pages created
2 paginator pages created
0 tags created
0 categories created
in 17 ms

Após executar o comando hugo, o diretório estante-de-livros/public será criado, contendo o código fonte do seu site gerado.

A propósito (caso você tenha tentado), o site não pode ser acessado pelo protocolo file:///.

Passo 12. Deploy da estante-de-livros na GitHub Pages

Vamos adicionar controle de versão à nossa estante-de-livros:

$ git init
$ echo "/public/" >> .gitignore
$ echo "/themes/" >> .gitignore
$ git add --all
$ git commit -m "Primeiro commit"

Agora o repositório Git em estante-de-livros/themes não vai gerar conflito com o repositório da estante-de-livros, e também não haverá um repositário Git em estante-de-livros/public.

Crie um novo repositório no GitHub chamado estante-de-livros (sem um README). Um vez feito, crie um novo repositório Git em seu sistema local estante-de-livros/public e adicione o servidor remoto:

$ cd public
$ git init
$ git remote add origin git@github.com:<seu-usuario-github>/estante-de-livros.git

Então, crie e faça um checkout em seu novo branch gh-pages.

$ git checkout -b gh-pages
Switched to a new branch 'gh-pages'

Adicione todos os arquivos (dentro de estante-de-livros/public) ao índice, faça o commit deles, depois envie as alterações para o GitHub.

$ git add --all
$ git commit -m "Adicionado a estante-de-livros"
$ git push -f origin gh-pages

Em poucos minutos, seu site estará disponível em https://<seu-usuario-github>.github.io/estante-de-livros/.

A qualquer momento, você pode gerar novamente seu site com:

$ (cd ..; hugo --theme=hugo_theme_robust)
$ cd public
$ git add --all
$ git commit -m "Algumas alteracoes"
$ git push -f origin gh-pages

Este guia de início rápido foi originalmente escrito por Shekhar Gulati, em seu blog 52 Technologies in 2016.