Documentação com Markdown: Livros e documentos longos com Bookdown 3/3

Bookdown é um pacote R que facilita a produção de livros e documentos longos com R Markdown

Este é o nosso nono artigo da série sobre produção de documentos com Markdown, uma linguagem de marcação simples e muito útil para produzir praticamente qualquer tipo de documento técnico, acadêmico, para a Web, etc.

Ao longo dos artigos anteriores já tratamos sobre linguagens de marcação da sintaxe básica Markdown; apresentamos o Pandoc, um conversor universal de documentos que possui uma sintaxe Markdown estendida; apresentamos o Limarka, uma ferramenta que ajuda a produzir documentos acadêmicos conforme as normas da ABNT utilizando Markdown; tratamos do R Markdown, que permite produzir documentos dinâmicos a partir da mistura de código de linguagens de programação com texto em Markdown; e apresentamos o R Notebook, que é um modo especial de execução de documentos R Markdown para Literate Programming.

No sétimo texto da série iniciamos um artigo em três partes sobre o Bookdown, que é um pacote R de código aberto que facilita a escrita de livros e documentos longos com o R Markdown. A primeira parte se concentrou em apresentar o Bookdown, as dependências necessárias, suas principais características e a estrutura do documento, enquanto na segunda parte abordamos os elementos da sintaxe Markdown estendida trazida pelo pacote Bookdown.

Nesta terceira parte, continuação das anteriores, tratamos das características dos diferentes formatos de saída, das principais configurações, dos mecanismos de edição e produção e das formas de publicação.

Documentação com Markdown: Livros e documentos longos com Bookdown 3/3

Sumário do artigo

Introdução

Este texto é uma continuação dos dois artigos anteriores, nos quais tratamos do Bookdown, que é um pacote R de código aberto que facilita a escrita de livros e documentos longos com o R Markdown.

Na primeira parte apresentamos o Bookdown, suas vantagens e principais características, e as dependências e instalações necessárias. Tratamos do funcionamento do Bookdown dentro do ambiente R e R Markdown, no software RStudio, descrevemos o processo de criação de um projeto Bookdown e apresentamos sua estrutura.

Na segunda parte abordamos os elementos da sintaxe Markdown estendida trazida pelo pacote Bookdown.

Nesta terceira parte trataremos das principais características dos diferentes formatos de saída, as principais configurações, os mecanismos de edição e produção, e as formas de publicação.

O pacote Bookdown foi criado por Yihui Xie, que também criou os pacotes knitr, rmarkdown, pagedown xaringan, e é coautor dos livros “R Markdown: The definitive guide” e “R Markdown Cookbook”, dentre outros.

Formatos de saída

Os formatos de saída podem ser especificados no cabeçalho de metadados YAML do primeiro arquivo .Rmd do livro - o arquivo index.Rmd - ou no arquivo YAML separado denominado _output.yml.

Múltiplos formatos de saída podem ser definidos para um mesmo projeto Bookdown. No caso destas definições serem inseridas no cabeçalho de metadados YAML do primeiro arquivo .Rmd elas devem ser colocadas como valores da chave output:, conforme exemplo a seguir:

---
title: "Inteligência Urbana"
author: "Elson Fabiano Alves"
output:
  bookdown\:\:gitbook:
    lib_dir: assets
    split_by: section
    config:
      toolbar:
        position: static
  bookdown\:\:pdf_book:
    keep_tex: true
  bookdown\:\:html_book:
    css: toc.css
documentclass: book
---

Já no caso destas definições serem inseridas no arquivo YAML _output.yml cada formato de saída deve ser um elemento YAML de nível superior, conforme o seguinte exemplo:

bookdown\:\:gitbook:
  lib_dir: assets
  split_by: section
  config:
    toolbar:
      position: static
bookdown\:\:pdf_book:
  keep_tex: true
bookdown\:\:html_book:
  css: toc.css

Como podemos observar, não é necessário o uso dos três --- (traços) antes e depois, uma vez que não se trata de um cabeçalho YAML dentro de um arquivo .md/.Rmd, mas de um arquivo YAML separado.

O pacote Bookdown oferece suporte a três tipos de formatos de saída: HTML, LaTeX / PDF, e-books e documentos simples:

HTML
- gitbook
- bs4_book
- html_book
- tufte_html_book
LaTeX / PDF
- pdf_book
E-book
- epub_book Documentos simples:
- html_document2
- tufte_html2
- pdf_document2
- tufte_handout2
- tufte_book2
- word_document2

HTML

A principal diferença entre renderizar um projeto Bookdown e renderizar um documento R Markdown simples em HTML é que o Bookdown irá gerar várias páginas HTML por padrão, normalmente um arquivo HTML por capítulo.

O pacote bookdown fornece vários estilos diferentes para a saída HTML:

GitBook
Bootstrap de três colunas
Bootstrap padrão
Tufte

Gitbook

O estilo GitBook é baseado no GitBook, um projeto dedicado a ajudar autores a escrever livros com Markdown. O layout consiste em uma barra lateral mostrando o índice à esquerda e o corpo principal de um livro à direita. O design é responsivo e sensível ao tamanho da janela, os botões de navegação são exibidos ou recolhidos conforme o tamanho do dispositivo, no sentido de facilitar a leitura.

A maneira mais fácil de criar um projeto Bookdown com o formato de saída HTML no estilo gitbook é com o uso do Assistente de projeto do RStudio, conforme demonstramos mais detalhadamente na primeira parte deste artigo.

Na barra de menus, deve clicar em “File” e então, no meu que se abre, clicar em “New project”. Na janela que se abre deve-se clicar em “New Directory” e depois em em “Book project using bookdown”, e então, ainda na mesma janela, deve-se atribuir um nome ao projeto que está sendo criado, estabelecer o local e em “Select HTML book format” selecionar a opção Gitbook (Figura 1) e, por fim, clicar em “Create Project”

rstudio-01 — Interface do RStudio - criar projeto Bookdown, formato HTML, estilo Gitbook

Também é possível criar o mesmo projeto chamando a função bookdown::create_gitbook(), no console.

Neste link temos um exemplo de livro Bookdown estilo Gitbook, que também pode ser visto na Figura 2.

exemplo-01 — Livro Bookdown, formato HTML, estilo Gitbook

Como podemos observar, o estilo GitBook possui uma barra de ferramentas na parte superior de cada página que permite alterar dinamicamente as configurações do livro. Por padrão a barra de ferramentas é fixada na parte superior da página.

O primeiro botão da barra de ferramentas pode alternar a visibilidade da barra lateral.

O segundo botão da barra de ferramentas é o botão de pesquisa. Conforme se digite na caixa de pesquisa o sumário será filtrado para exibir as seções que correspondem à palavra-chave da pesquisa.

O terceiro botão é para configurações de fonte e tema. É possível alterar o tamanho da fonte, a família da fonte (serif ou sans serif) e o tema (Branco, Sépia ou Noite). Pode-se definir o valor inicial dessas configurações por meio do parâmetro fontsettings:, conforme o seguinte exemplo.

bookdown\:\:gitbook:
  config:
    fontsettings:
      theme: night
      family: serif
      size: 3

O tamanho da fonte é medido em uma escala de 0 a 4. O botão pode ser removido da barra de ferramentas definindo fontsettings: null.

O quarto botãpo é para edição. A opção foi projetada para que contribuidores em potencial contribuam com a edição do livro no GitHub após clicar no botão.

O quinto botão é para download. Se o livro tiver outros formatos de saída disponíveis para download pode-se fornecer a opção de download para que um botão de download possa ser adicionado à barra de ferramentas.

Outro botão mostrado na barra de ferramentas é o botão de informações, que lista os atalhos de teclado disponíveis para navegar no documento. Este botão pode ser ocultado definindo info: false.

À direita da barra de ferramentas, existem alguns botões para compartilhar o link em sites de redes sociais como Twitter, Facebook e Linkedin.

Conclusão

Neste artigo apresentamos o Bookdown, que é um pacote R de código aberto que facilita a escrita de livros e documentos longos com o R Markdown. Esta foi a terceira parte de um artigo de três partes, e abordamos as principais características dos diferentes formatos de saída, as configurações, os mecanismos de edição e produção e as formas de publicação. Além do blog, a plataforma Inteligência Urbana disponibiliza páginas com referências para livros, cursos e leis e normas relacionadas aos temas que tratamos aqui. Caso você tenha interesse pode conferir nossos serviços oferecidos e entrar em contato quando quiser. Se quiser ser alertado da publicação de material novo pode assinar a nossa newsletter, e muito obrigado pela atenção até aqui!

Principais referências