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

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

Este é o nosso sétimo 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.

Neste texto iniciamos um artigo em duas 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.

Este texto se concentrará em apresentar o Bookdown, as dependências necessárias, suas principais características e a estrutura do documento, enquanto o artigo seguinte, continuação deste, abordaremos a sintaxe estendida, as principais características dos diferentes formatos de saída, as principais configurações e customizações possíveis e formas de publicação.

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

Sumário do artigo

Introdução

Bookdown é um pacote R de código aberto que facilita a escrita de livros e documentos longos com o R Markdown.

A partir do Bookdown é possível produzir livros e documentos prontos para impressão, e-books e documentos interativos HTML a partir de documentos R Markdown.

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.

Vantagens do Bookdown

Com vimos no primeiro artigo desta série, o Markdown é uma linguagem de marcação muito útil para escrever documentos relativamente simples que contenham elementos básicos como títulos e subtítulos, parágrafos, listas, links e imagens, etc. Também vimos, no segundo artigo da série, que o Pandoc estende muito a sintaxe básica Markdown e adiciona novos recursos úteis, como notas de rodapé, citações e tabelas, além de permitir gerar documentos de saída em uma grande variedade de formatos.

Todavia, existem alguns recursos úteis ausentes no Pandoc’s Markdown, que são necessários para escrever documentos mais complexos ou longos, tais como numeração automática de figuras e tabelas, referências cruzadas de figuras e tabelas e controle da aparência das figuras (como alinhamento de imagens, por exemplo). O Bookdown soluciona estes problemas, estendendo ainda mais a sintaxe Markdown.

Conforme vimos no quarto e no quinto artigos desta série, nos quais apresentamos o R Markdown, é possível construir documentos dinâmicos, misturando código R (ou de outras linguagens de programação) com texto em Markdown (com a sintaxe estendida Pandoc’s Markdown) e produzir diferentes formatos de saída, utilizando os pacotes R Knitr e rmarkdown, além do próprio Pandoc, no RStudio.

Todavia, projetos maiores podem se tornar difíceis de gerenciar em um único arquivo R Markdown, e o pacote Bookdown resolve também esta limitação, permitindo que livros, relatórios e documentos longos sejam construídos a partir de vários arquivos R Markdown.

O Bookdown permite gerar documentos em uma variedade de formatos adequados para publicação, como PDF, e-book e sites HTML e, no caso do formato de saída HTML, o livro ou documento pode ser ser publicado no GitHub, bookdown.org, ou em qualquer servidor da web.

R e RStudio

R é uma linguagem de programação de alto nível, interpretada, de script, de tipagem dinâmica forte, multiparadigma (com ênfase em programação funcional) voltada à manipulação, análise e visualização de dados.

Neste artigo vamos abordar a utilização do Bookdown no software RStudio que, conforme já tratamos, é um Ambiente de Desenvolvimento Integrado - IDE criado para a linguagem R, mas que em suas versões atuais também trabalha com outras linguagens.

É relevante mencionar que, em que pese o Bookdown seja uma espécie de extensão do R Markdown e faça parte do ecossistema R e o software RStudio forneça um conjunto de ferramentas integradas para trabalhar com R Markdown, um projeto Bookdown não depende do RStudio para “funcionar” e, na realidade, não depende nem mesmo de arquivos R Markdown .Rmd, pode-se produzir um projeto Bookdown com arquivos Markdown simples .md, e mesmo os arquivos .Rmd não precisam conter fragmentos de código R se não forem necessários para o assunto do documento em si. É perfeitamente possível usar o bookdown para compor romances ou poemas, por exemplo.

Para utilizar o Bookdown é necessário, entretanto, ter instalado o R e os mesmos pacotes e dependências necessárias para o R Markdown, notadamente os pacotes Knitr e rmarkdown.

Na primeira parte do artigo sobre R Markdown já tratamos das instalações necessárias e como fazê-las e também apresentamos a interface do RStudio.

R Markdown e Bookdown

Um projeto Bookdown é essencialmente um conjunto de arquivos R Markdown .Rmd (ou mesmo Markdown .md), cada um referente a um capítulo do livro ou documento, além de alguns outros arquivos para configurações, definições de estilo e bibliografia.

Neste artigo em duas partes vamos nos concentrar nas particularidades de um projeto Bookdown em relação à produção de um documento R Markdown isolado, cuja anatomia é essencialmente a mesma de cada um dos documentos que compõem um projeto Bookdown, de modo que é importante que os quarto e quinto artigos desta série, nos quais apresentamos as instalações necessárias e a estrutura básica do documento R Markdown e também as formas de inserção de código, configurações e interações sejam lidos antes, além, é claro, dos artigos anteriores a estes, no quais apresentamos a sintaxe básica Markdown e o Pandoc.

Instalação do Bookdown

Como o Bookdown é um pacote R, para instalá-lo para utilizar a função install.packages() para instalar a versão mais recente e estável do pacote. Assim, basta digitar o seguinte no console do RStudio:

install.packages("bookdown")

Funcionamento do Bookdown

Um projeto Bookdown é composto principalmente por um conjunto de arquivos R Markdown, cada um correspondente a capítulo do documento ou livro.

Um dos arquivos deve se chamar index.Rmd, que será o primeiro arquivo do documento final e conterá o cabeçalho de metadados YAML com o parametros necessários (tanto relativos ao projeto Bookdown quanto as definições comuns de um documento R Markdown e as configurações utilizadas pelo Pandoc). Os demais arquivos R Markdown não devem possuir cabeçalho YAML e devem necessariamente começar com um título de primeiro nível (# Título). Os demais arquivos, após o index.Rmd serão serão mesclados durante a compilação para o formato de saída conforme a ordem alfanumérica do nome dos arquivos (por isso pode ser inteligente nomear os arquivos como 01-introducao.Rmd, 02-desenvolvimento, e assim por diante).

Além dos arquivos R Markdown um projeto Bookdown pode conter outros arquivos YAML com configuração adicionais às definidas no cabeçalho YAML do arquivo index.Rmd, arquivos CSS e TeX apara ajustes aparência e estilo e arquivos BibTeX para bibliografia, conforme descreveremos sucintamente adiante.

O pacote Bookdown possuiu a função bookdown::render_book(), que é “similar” à função rmarkdown::render(), que renderiza (ou compila) os arquivos R Markdown mas que, neste caso, renderiza vários documentos .Rmd (ou .md) em um livro ou documento único, conforme o formato ou formatos de saída especificados. A função bookdown::render_book() pode ser chamada manualmente no console ou pode-se utilizar botões específicos na interface do RStudio, como veremos adiante.

Como criar um projeto Bookdown

No RStudio a maneira mais simples de iniciar um projeto Bookdown é, na barra de menus, clicar em “File” e então, no meu que se abre, clicar em “New project”, conforme Figura 1.

rstudio-01 — Interface do RStudio - criar novo projeto

E então, na janela que se abre deve-se clicar em “New Directory”, conforme Figura 2.

rstudio-02 — Interface do RStudio - criar novo projeto em novo diretório

E depois, na mesma janela, deve clicar em “Book project using bookdown”, conforme Figura 3.

rstudio-03 — Interface do RStudio - criar projeto Bookdown

Na sequência, ainda na mesma janela, deve-se atribuir um nome ao projeto que está sendo criado (1), estabelecer o local (2) e então clicar em “Create Project” (3), conforme Figura 4

rstudio-04 — Interface do RStudio - criar projeto Bookdown em diretório especificado

O RStudio criará um modelo de projeto Bookdown, uma espécie de template exemplificativo, composto pelo diretório do Projeto, com o nome e no local especificados na janela da Figura 4 e, dentro deste diretório um conjunto de arquivos que são um “demo”, um exemplo mínimo de demonstração, conforme podemos observar na Figura 5.

rstudio-05 — Interface do RStudio - Projeto Bookdown

Como podemos observar, existem vários arquivos na aba “Files” do bloco inferior direito da interface do RStudio, a maioria arquivos .Rmd referentes a cada um dos capítulos do livro de demonstração.

Como também podemos observar na Figura 5, no Editor, no bloco superior esquerdo da interface do RStudio, está aberto o arquivo index.Rmd, o primeiro e principal dos arquivos R Markdown que compõem o documento e o único deles a possuir um cabeçalho YAML, como já mencionamos.

Estes arquivos podem ser editados, modificados e substituídos livremente. O projeto criado é uma demonstração que serve como ponto de partida com uma espécie de conteúdo mínimo de um projeto Bookdown, sem que seja necessário criar cada um dos arquivos individualmente e manualmente.

O conteúdo destes arquivos exemplificativos também contém pequenas instruções e dicas a respeito da produção de um documento Bookdown.

Estrutura de um projeto Bookdown

Com foi possível observar na Figura 5, o diretório do projeto criado possui os seguintes arquivos:

index.Rmd
01-intro.Rmd
02-cross-refs.Rmd
03-parts.Rmd
04-citations.Rmd
05-blocks.Rmd
06-share.Rmd
07-references.Rmd
_bookdown.yml
_output.yml
book.bib
preamble.tex
style.css
README.md
Livro-Inteligencia-Urbana.Rproj

Na sequencia, apresentamos sucintamente os arquivos no sentido de prosseguir com a explicação do funcionado básico de um projeto Bookdown.

index.Rmd

O arquivo index.Rmd contém o primeiro capítulo do livro ou documento e o cabeçalho de metadados YAML referente ao documento inteiro.

O arquivo index.Rmd de demonstração criado contém o seguinte cabeçalho YAML:

--- 
title: "A Minimal Book Example"
author: "John Doe"
date: "`r Sys.Date()`"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib, packages.bib]
# url: your book url like https://bookdown.org/yihui/bookdown
# cover-image: path to the social sharing image like images/cover.jpg
description: |
  This is a minimal example of using the bookdown package to write a book.
  The HTML output format for this example is bookdown::gitbook,
  set in the _output.yml file.
link-citations: yes
github-repo: rstudio/bookdown-demo
---

A maioria dos parâmetros definidos neste exemplos são metadados comuns de um documento: título, autor, descrição, etc.

A chave site: com o valor bookdown::bookdown_site permite que a função bookdown::render_book().

A chave bibliography: estabelece os arquivos onde estarão as referências bibliográficas do livro, neste caso uma lista com dois arquivos, book.bib, que foi criado junto com o projeto, e packages.bib, que possui as referência bibliográficas dos pacotes R utilizados no projeto e é gerada automaticamente na compilação.

O cabeçalho YAML poderia conter a chave output: para a definição dos formatos de saída, mas neste caso esta definição está no arquivo _output.yml, como veremos.

Arquivos .Rmd

Por padrão, todos os arquivos .Rmd são mesclados com o index.Rmd para renderizar o livro. Os arquivos .Rmd devem começar imediatamente com o título do capítulo usando o título de primeiro nível (por exemplo: # Título do capítulo). Os metadados YAML não devem ser incluídos nesses arquivos .Rmd, uma vez que serão herdados do arquivo index.Rmd.

Por padrão, o bookdown mescla todos os arquivos .Rmd pela ordem alfanumérica dos nomes dos arquivos, de modo 01-intro.Rmd aparecerá antes de 02-cross-refs.Rmd. Os arquivos cujos nomes começam com um _ (sublinhado, ou underline) não serão compilados.

_bookdown.yml

O arquivo _bookdown.yml permite especificar configurações opcionais para a construção do livro.

O arquivo _bookdown.Rmd de demonstração criado contém o seguinte conteúdo:

delete_merged_file: true
language:
  ui:
    chapter_name: "Chapter "

Como pode ser observado, uma vez que é um arquivo YAML isolado, não é necessário o uso dos três hifens --- e no início e no final, como é o caso de um cabeçalho YAML dentro de um arquivo .Rmd ou .md.

O arquivo acima está definindo que os arquivos mesclados sejam excluídos após a compilação e que deve ser utilizado a palavra “Chapter” para os capítulos. Se quisermos, por exemplo, substituir “Chapter” por “Capítulo” basta editarmos o conteúdo da seguinte forma:

delete_merged_file: true
language:
  ui:
    chapter_name: "Capítulo "

Também é possível modificar o comportamento padrão do Bookdown e substituir a ordem em que os arquivos são mesclados, utilizando para isso o campo rmd_files: que deve ter como valor uma lista com os arquivos a serem mesclados na ordem que que se deseje que sejam mesclados.

Se, por exemplo, quisermos que sejam mesclados, por qualquer razão, apenas os arquivos index.Rmd, 03-parts.Rmd e 01-intro.Rmd, nesta ordem, basta acrescentarmos a seguinte linha neste arquivo:

rmd_files: ["index.Rmd", "03-parts.Rmd", "01-intro.Rmd"]

_output.yml

O arquivo _output.yml é usado para especificar os formatos de saída do documento, bem como opções relativas aos formatos, que podem ser múltiplos.

O arquivo _output.Rmd de demonstração criado contém o seguinte conteúdo:

bookdown::gitbook:
  css: style.css
  config:
    toc:
      before: |
        <li><a href="./">A Minimal Book Example</a></li>
      after: |
        <li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
    edit: https://github.com/USERNAME/REPO/edit/BRANCH/%s
    download: ["pdf", "epub"]
bookdown::pdf_book:
  includes:
    in_header: preamble.tex
  latex_engine: xelatex
  citation_package: natbib
  keep_tex: yes
bookdown::epub_book: default

Neste caso estão sendo especificados três formados de saída: bookdown::gitbook, que é um dos tipos de livros HTML pré-formatados disponíveis (quie veremos melhor no próximo artigo); bookdown::pdf_book, que é um PDF; e bookdown::epub_book, que é oo formato de e-book ePub.

Adicionalmente, estão sendo definidos parâmetros adicionais específicos a cada um dos formatos:

Para o formato gitbook está sendo definida a utilização o arquivo CSS styles.css para estilizar o livro/site; está sendo definido um conteúdo para aparecer antes e outro conteúdo para aparecer após o ToC (Table of Contents), que é o sumário do documento gerado automaticamente a partir dos títulos e subtítulos; está sendo definido um link para que o usuário possa acessar o repositório do livro e sugerir edições e está sendo definido que o livro/site HTML permitirá download de seu próprio conteúdo nas versões PDF e ePub, que são os outros formatos de saída definidos neste mesmo arquivo YAML;
Para o formato pdf_bookestá sendo definida a utilização do arquivo preamble.tex para inclusão de conteúdo no cabeçalho; está sendo definido que o xelatex será a engine LaTeX utilizada (o Pandoc produz documentos de saída PDF através do LaTeX, como já vimos); está sendo definido natbib como pacote de citações e está sendo definido que o arquivo .tex (LaTeX) gerado como formato intermediário na conversão, seja mantido;
Para o formato epub_book está sendo definida a utilização de configurações padrão, apenas.

É importante mencionar que todas estas mesmas definições poderiam, alternativamente, estar no cabeçalho YAML do arquivo index.Rmd, como valor do parâmetro output:.

book.bib

O arquivo book.bib contém as referências bibliográficas do documento.

O arquivo book.bib de demonstração criado contém o seguinte conteúdo:

@Book{xie2015,
  title = {Dynamic Documents with {R} and knitr},
  author = {Yihui Xie},
  publisher = {Chapman and Hall/CRC},
  address = {Boca Raton, Florida},
  year = {2015},
  edition = {2nd},
  note = {ISBN 978-1498716963},
  url = {http://yihui.org/knitr/},
}

As referências devem ser cadastradas utilizando o sistema Bibtex. No terceiro artigo desta série, sobre o Limarka, discorremos sucintamente a respeito da “sintaxe Bibtex”.

preamble.tex e style.css

Os arquivos preamble.tex e style.css podem ser usados para ajustar a aparência e os estilos dos documentos de saída do livro, notadamente nos formatos de saída PDF e HTML, respectivamente. É necessário algum conhecimento de LaTeX e de CSS, conforme o caso, para editá-los (ou substituí-los). Os formatos de saída padrão do Bookdown já possuem estilos e aparência pré-definidos e algumas opções de personalização facilitada através dos arquivos - e do cabeçalho - YAML, como veremos no próximo artigo. Com a utilização do arquivo .tex, para PDF, e de arquivos .css, para HTML, virtualmente tudo pode ser editado e modificado livremente.

Outros arquivos

Os arquivos README.md e Livro-Inteligencia-Urbana.Rproj são arquivos comuns a qualquer projeto criado no RStudio, não apenas a um projeto Bookdown.

O arquivo readme.md (leia-me) deve conter informações úteis sobre o projeto em questão, a serem lidas por quem eventualmente tenha acesso a este “código fonte” do projeto, e pode ser editado livremente.

O arquivo .Rproj indica para o RStudio que aquele diretório será a raiz de um projeto e que, portanto, várias outras funcionalidades podem ser ativadas. Não deve ser editado.

Como compilar o documento

No próximo artigo nós trataremos sobre as principais características dos diferentes formatos de saída, além as principais configurações e definições possíveis.

Por enquanto, vamos testar o funcionamento básico do processo de “construção” de um documento a partir de um projeto Bookdown e chamar a função render_book() para este projeto de demonstração da forma como está, para ver como é o resultado.

No RStudio, a maneira mais simples de fazer isso é a seguinte: abra o arquivo R Markdown index.Rmd e clique no botão “Build Book” na aba Build, no bloco superior direito da interface do RStudio, conforme Figura 6.

rstudio-06 — Interface do RStudio - Projeto Bookdown - Build Book

E então, após uns instantes de processamento, o projeto é “construído” e sua versão HTML (Gitbook) aberta em uma nova janela, conforme podemos ver na Figura 7.

A partir do próprio site/livro HTML é possível fazer download da versão PDF e ePub do mesmo documento, uma vez que isto foi definido no arquivo _output.yml, mas isso será tratado na próxima parte deste artigo.

Isto conclui a primeira parte do artigo sobre Bookdown. Na segunda parte deste artigo, abordaremos a sintaxe estendida, as principais características dos diferentes formatos de saída, as principais configurações e customizações possíveis e formas de publicação.

Conclusão

Neste artigo apresentamos o R notebook, que é uma espécie de modo de execução especial de documentos R Markdown, com características e funcionalidades sutilmente diferentes que lhe conferem casos de uso próprios e se configura como uma implementação de literate programming em uma interface de computational notebook mais conceitualmente alinhada com o significado destes termos.

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