1.3 Uso

Normalmente, un libro contiene varios capítulos, y un capítulo está contenido dentro de un archivo de R Markdown, con la extensión de archivo .Rmd. Cada archivo de R Markdown debe comenzar inmediatamente con el título del capítulo usando el encabezado de primer nivel, por ejemplo, # Título del Capítulo. Todos los archivos R Markdown deben ser codificados en UTF-8. Aquí hay un ejemplo (las viñetas son los nombres de archivo, seguidos por el contenido del archivo):

  • index.Rmd

    # Prefacio {-}

En este libro presentamos un método interesante.

  • 01-intro.Rmd

    # Introducción

Este capítulo es un panorama de los métodos con que proponemos resolver un  **problema importante**.

  • 02-literatura.Rmd

    # Literatura

Aquí hay una revisión de los métodos existentes.

  • 03-metodos.Rmd

    # Métodos

Describimos nuestros métodos en este capítulo.

  • 04-aplicacion.Rmd

    # Aplicaciones

Algunos aplicaciones _significativas_ se demuestran
en este capítulo.

## Ejemplo uno

## Ejemplo dos

  • 05-resumen.Rmd

    # Palabras finales

Hemos finalizado un bello libro.

De forma predeterminada, bookdown fusiona todos los archivos Rmd por el orden de los nombres de archivo, por ejemplo, 01-intro.Rmd aparecerá antes de 02-literatura.Rmd. Los nombres de archivo que comiencen con un guión bajo _ se omiten. Si existe un archivo Rmd llamado index.Rmd, siempre va a ser tratado como el primer archivo cuando se fusionen todos los archivos Rmd. La razón de este tratamiento especial es que el archivo HTML index.html se genera a partir deindex.Rmd. Este index.html suele ser el archivo de índice por defecto cuando se ve una página web, por ejemplo, usted está viendo http://yihui.name/index.html cuando se abre http://yihui.name/.

Puede anular el comportamiento anterior mediante la inclusión de un archivo de configuración llamado _bookdown.yml en el directorio del libro. Este es un archivo YAML (https://en.wikipedia.org/wiki/YAML), y los usuarios de R Markdown deben estar familiarizados con este formato, ya que también se utiliza para escribir los metadatos al comienzo de los documentos R Markdown (puede aprender más acerca de YAML en la Sección B.2). Puede utilizar un campo llamado rmd_files para definir su propia lista y el orden de los archivos Rmd para el libro. Por ejemplo,

rmd_files: ["index.Rmd", "abstract.Rmd", "intro.Rmd"]

En este caso, bookdown sólo tiene que utilizar lo que se ha definido en este campo YAML sin tratamientos especiales de index.Rmd o guiones bajos. Si desea salidas HTML y LaTeX/PDF del libro, y usar diferentes archivos Rmd para la salida HTML y LaTeX, puede especificar estos archivos para los dos formatos de salida por separado, por ejemplo,

rmd_files:
  html: ["index.Rmd", "abstract.Rmd", "intro.Rmd"]
  latex: ["abstract.Rmd", "intro.Rmd"]

A pesar de que hemos estado hablando acerca de los archivos de R Markdown, los archivos de capítulos en realidad no tienen que ser R Markdown. Pueden ser archivos sin formato Markdown ( .md), y no tienen que contener trozos de código R (en adelante chunks) en absoluto. ¡Por supuesto que puede utilizar bookdown para componer novelas o poemas!

Por el momento, los principales formatos de salida que se pueden utilizar incluyen bookdown::pdf_book,bookdown::gitbook, bookdown::html_book, y bookdown::epub_book. Hay una función bookdown::render_book() similar a rmarkdown::render(), pero fue diseñada para hacer múltiples documentos Rmd en un libro utilizando las funciones de formato de salida. Es posible que se quiera llamar a esta función desde la línea de comandos directamente, o hacer clic en los botones correspondientes en el IDE RStudio. Estos son algunos ejemplos de línea de comandos:

bookdown::render_book('foo.Rmd', 'bookdown::gitbook')
bookdown::render_book('foo.Rmd', 'bookdown::pdf_book')
bookdown::render_book('foo.Rmd', bookdown::gitbook(lib_dir = 'libs'))
bookdown::render_book('foo.Rmd', bookdown::pdf_book(keep_tex = TRUE))

Para utilizar las funciones render_book y el formato de salida en el IDE RStudio, se puede definir un campo YAML llamado site que toma el valor bookdown::bookdown_site,1 y las funciones de formato de salida se pueden utilizar en el campo output, por ejemplo,

---
site: "bookdown::bookdown_site"
output:
  bookdown::gitbook:
    lib_dir: "book_assets"
  bookdown::pdf_book:
    keep_tex: yes
---

A continuación, puede hacer clic en el botón Build Book en el panel Build en RStudio para compilar los archivos Rmd en un libro, o haga clic en el botón Knit en la barra de herramientas para obtener una vista previa del capítulo actual.

Más opciones de configuración bookdown en _bookdown.yml se explican en la sección 4.4. Además de estas configuraciones, también puede especificar otras relacionadas con Pandoc en los metadatos YAML del primer archivo Rmd del libro, como el título, autor y fecha del libro, etc. Por ejemplo:

--- 
title: "Creando un libro con R Markdown"
author: "Yihui Xie"
date: "`r Sys.Date()`"
site: "bookdown::bookdown_site"
output:
  bookdown::gitbook: default
documentclass: book
bibliography: ["book.bib", "packages.bib"]
biblio-style: apalike
link-citations: yes
---

  1. Esta función llama a bookdown::render_book().↩