Download the full version of the textbook now at textbookfull.

com

R Markdown: The Definitive Guide Yihui Xie

https://textbookfull.com/product/r-markdown-the-
definitive-guide-yihui-xie/

Explore and download more textbook at https://textbookfull.com

 Recommended digital products (PDF, EPUB, MOBI) that
you can download immediately if you are interested.

Fashion The Definitive Visual Guide Caryn Franklin

https://textbookfull.com/product/fashion-the-definitive-visual-guide-
caryn-franklin/

textbookfull.com

JavaScript The Definitive Guide 7th Edition David Flanagan

https://textbookfull.com/product/javascript-the-definitive-guide-7th-
edition-david-flanagan/

textbookfull.com

Xie s Veterinary Acupuncture Huisheng Xie Vanessa Preast

https://textbookfull.com/product/xie-s-veterinary-acupuncture-
huisheng-xie-vanessa-preast/

textbookfull.com

Public Confidence in Criminal Justice: A History and

Critique 1st Edition Elizabeth R. Turner (Auth.)

https://textbookfull.com/product/public-confidence-in-criminal-
justice-a-history-and-critique-1st-edition-elizabeth-r-turner-auth/

textbookfull.com
World Trade and Local Public Interest: Trade
Liberalization and National Regulatory Sovereignty Csongor
István Nagy
https://textbookfull.com/product/world-trade-and-local-public-
interest-trade-liberalization-and-national-regulatory-sovereignty-
csongor-istvan-nagy/
textbookfull.com

Deception in the Digital Age: Exploiting and Defending

Human Targets Through Computer-Mediated Communications
Cameron H. Malin
https://textbookfull.com/product/deception-in-the-digital-age-
exploiting-and-defending-human-targets-through-computer-mediated-
communications-cameron-h-malin/
textbookfull.com

New Directions in Literature and Medicine Studies 1st

Edition Stephanie M. Hilger (Eds.)

https://textbookfull.com/product/new-directions-in-literature-and-
medicine-studies-1st-edition-stephanie-m-hilger-eds/

textbookfull.com

Exploring the Rules (The Dating Playbook #4) 1st Edition

Mariah Dietz

https://textbookfull.com/product/exploring-the-rules-the-dating-
playbook-4-1st-edition-mariah-dietz/

textbookfull.com

Digital Conversion on the Way to Industry 4.0: Selected

Papers from ISPR2020, September 24-26, 2020 Online -
Turkey Numan M. Durakbasa
https://textbookfull.com/product/digital-conversion-on-the-way-to-
industry-4-0-selected-papers-from-
ispr2020-september-24-26-2020-online-turkey-numan-m-durakbasa/
textbookfull.com
On the scent : a journey through the science of smell 1st
Edition Pelosi

https://textbookfull.com/product/on-the-scent-a-journey-through-the-
science-of-smell-1st-edition-pelosi/

textbookfull.com
 R Markdown
The Definitive Guide
 Chapman & Hall/CRC
The R Series
Series Editors
John M. Chambers, Department of Statistics Stanford University Stanford,
California, USA
Torsten Hothorn, Division of Biostatistics University of Zurich Switzerland
Duncan Temple Lang, Department of Statistics University of California,
Davis, California, USA
Hadley Wickham, RStudio, Boston, Massachusetts, USA

Recently Published Titles

bookdown: Authoring Books and Technical Documents with R Markdown

Yihui Xie
Testing R Code
Richard Cotton
R Primer, Second Edition
Claus Thorn Ekstrøm
Flexible Regression and Smoothing: Using GAMLSS in R
Mikis D. Stasinopoulos, Robert A. Rigby, Gillian Z. Heller, Vlasios Voudouris,
Fernanda De Bastiani
The Essentials of Data Science: Knowledge Discovery Using R
Graham J. Williams
blogdown: Creating Websites with R Markdown
Yihui Xie, Alison Presmanes Hill, Amber Thomas
Handbook of Educational Measurement and Psychometrics Using R
Christopher D. Desjardins, Okan Bulut
Displaying Time Series, Spatial, and Space-Time Data with R, Second Edition
Oscar Perpinan Lamigueiro
Reproducible Finance with R
Jonathan K. Regenstein, Jr
R Markdown: The Definitive Guide
Yihui Xie, J.J. Allaire, Garrett Grolemund

For more information about this series, please visit:

https://www.crcpress.com/go/the-r-series
 R Markdown
The Definitive Guide

Yihui Xie
J. J. Allaire
Garrett Grolemund
CRC Press
Taylor & Francis Group
6000 Broken Sound Parkway NW, Suite 300
Boca Raton, FL 33487-2742

© 2019 by Taylor & Francis Group, LLC

CRC Press is an imprint of Taylor & Francis Group, an Informa business

No claim to original U.S. Government works

Printed on acid-free paper

Version Date: 20180702

International Standard Book Number-13: 978-1-138-35933-8 (Paperback)

International Standard Book Number-13: 978-1-138-35942-0 (Hardback)

This book contains information obtained from authentic and highly regarded sources. Reasonable
efforts have been made to publish reliable data and information, but the author and publisher cannot
assume responsibility for the validity of all materials or the consequences of their use. The authors and
publishers have attempted to trace the copyright holders of all material reproduced in this publication
and apologize to copyright holders if permission to publish in this form has not been obtained. If any
copyright material has not been acknowledged please write and let us know so we may rectify in any
future reprint.

Except as permitted under U.S. Copyright Law, no part of this book may be reprinted, reproduced,
transmitted, or utilized in any form by any electronic, mechanical, or other means, now known or
hereafter invented, including photocopying, microfilming, and recording, or in any information
storage or retrieval system, without written permission from the publishers.

For permission to photocopy or use material electronically from this work, please access
www.copyright.com (http://www.copyright.com/) or contact the Copyright Clearance Center, Inc.
(CCC), 222 Rosewood Drive, Danvers, MA 01923, 978-750-8400. CCC is a not-for-profit organization
that provides licenses and registration for a variety of users. For organizations that have been granted
a photocopy license by the CCC, a separate system of payment has been arranged.

Trademark Notice: Product or corporate names may be trademarks or registered trademarks, and
are used only for identification and explanation without intent to infringe.
Visit the Taylor & Francis Web site at
http://www.taylorandfrancis.com
and the CRC Press Web site at
http://www.crcpress.com
 To Jung Jae-sung (1982 – 2018),
a remarkably hard-working badminton player with a remarkably
simple playing style
Contents

List of Tables xvii

List of Figures xix

Preface xxiii

About the Authors xxxiii

I Get Started 1

1 Installation 3

2 Basics 5
2.1 Example applications . . . . . . . . . . . . . . . . . . . . . 9
2.1.1 Airbnb’s knowledge repository . . . . . . . . . . . . 9
2.1.2 Homework assignments on RPubs . . . . . . . . . . 10
2.1.3 Personalized mail . . . . . . . . . . . . . . . . . . . 10
2.1.4 2017 Employer Health Benefits Survey . . . . . . . . 11
2.1.5 Journal articles . . . . . . . . . . . . . . . . . . . . . 12
2.1.6 Dashboards at eelloo . . . . . . . . . . . . . . . . . 12
2.1.7 Books . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.1.8 Websites . . . . . . . . . . . . . . . . . . . . . . . . 13
2.2 Compile an R Markdown document . . . . . . . . . . . . . 14
2.3 Cheat sheets . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.4 Output formats . . . . . . . . . . . . . . . . . . . . . . . . 16
2.5 Markdown syntax . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.1 Inline formatting . . . . . . . . . . . . . . . . . . . 19
2.5.2 Block-level elements . . . . . . . . . . . . . . . . . 20
2.5.3 Math expressions . . . . . . . . . . . . . . . . . . . 23
2.6 R code chunks and inline R code . . . . . . . . . . . . . . . 24
2.6.1 Figures . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.6.2 Tables . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.7 Other language engines . . . . . . . . . . . . . . . . . . . . 30

vii
viii Contents

2.7.1 Python . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.7.2 Shell scripts . . . . . . . . . . . . . . . . . . . . . . 34
2.7.3 SQL . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.7.4 Rcpp . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.7.5 Stan . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.7.6 JavaScript and CSS . . . . . . . . . . . . . . . . . . 39
2.7.7 Julia . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.7.8 C and Fortran . . . . . . . . . . . . . . . . . . . . . 40
2.8 Interactive documents . . . . . . . . . . . . . . . . . . . . . 41
2.8.1 HTML widgets . . . . . . . . . . . . . . . . . . . . 41
2.8.2 Shiny documents . . . . . . . . . . . . . . . . . . . 42

II Output Formats 47

3 Documents 49
3.1 HTML document . . . . . . . . . . . . . . . . . . . . . . . 49
3.1.1 Table of contents . . . . . . . . . . . . . . . . . . . . 50
3.1.2 Section numbering . . . . . . . . . . . . . . . . . . 51
3.1.3 Tabbed sections . . . . . . . . . . . . . . . . . . . . 51
3.1.4 Appearance and style . . . . . . . . . . . . . . . . . 52
3.1.5 Figure options . . . . . . . . . . . . . . . . . . . . . 54
3.1.6 Data frame printing . . . . . . . . . . . . . . . . . . 55
3.1.7 Code folding . . . . . . . . . . . . . . . . . . . . . . 56
3.1.8 MathJax equations . . . . . . . . . . . . . . . . . . . 57
3.1.9 Document dependencies . . . . . . . . . . . . . . . 58
3.1.10 Advanced customization . . . . . . . . . . . . . . . 59
3.1.11 Shared options . . . . . . . . . . . . . . . . . . . . . 62
3.1.12 HTML fragments . . . . . . . . . . . . . . . . . . . 62
3.2 Notebook . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.2.1 Using Notebooks . . . . . . . . . . . . . . . . . . . 63
3.2.2 Saving and sharing . . . . . . . . . . . . . . . . . . 72
3.2.3 Notebook format . . . . . . . . . . . . . . . . . . . 73
3.3 PDF document . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.3.1 Table of contents . . . . . . . . . . . . . . . . . . . . 79
3.3.2 Figure options . . . . . . . . . . . . . . . . . . . . . 80
3.3.3 Data frame printing . . . . . . . . . . . . . . . . . . 80
3.3.4 Syntax highlighting . . . . . . . . . . . . . . . . . . 81
3.3.5 LaTeX options . . . . . . . . . . . . . . . . . . . . . 81
3.3.6 LaTeX packages for citations . . . . . . . . . . . . . 82
3.3.7 Advanced customization . . . . . . . . . . . . . . . 83
Contents ix

3.3.8 Other features . . . . . . . . . . . . . . . . . . . . . 84

3.4 Word document . . . . . . . . . . . . . . . . . . . . . . . . 85
3.4.1 Other features . . . . . . . . . . . . . . . . . . . . . 85
3.5 OpenDocument Text document . . . . . . . . . . . . . . . . 86
3.5.1 Other features . . . . . . . . . . . . . . . . . . . . . 86
3.6 Rich Text Format document . . . . . . . . . . . . . . . . . . 87
3.6.1 Other features . . . . . . . . . . . . . . . . . . . . . 87
3.7 Markdown document . . . . . . . . . . . . . . . . . . . . . 88
3.7.1 Markdown variants . . . . . . . . . . . . . . . . . . 88
3.7.2 Other features . . . . . . . . . . . . . . . . . . . . . 89
3.8 R package vignette . . . . . . . . . . . . . . . . . . . . . . 90

4 Presentations 93
4.1 ioslides presentation . . . . . . . . . . . . . . . . . . . . . . 93
4.1.1 Display modes . . . . . . . . . . . . . . . . . . . . . 95
4.1.2 Incremental bullets . . . . . . . . . . . . . . . . . . 95
4.1.3 Visual appearance . . . . . . . . . . . . . . . . . . . 96
4.1.4 Code highlighting . . . . . . . . . . . . . . . . . . . 98
4.1.5 Adding a logo . . . . . . . . . . . . . . . . . . . . . 98
4.1.6 Tables . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.1.7 Advanced layout . . . . . . . . . . . . . . . . . . . 100
4.1.8 Text color . . . . . . . . . . . . . . . . . . . . . . . 100
4.1.9 Presenter mode . . . . . . . . . . . . . . . . . . . . 101
4.1.10 Printing and PDF output . . . . . . . . . . . . . . . 101
4.1.11 Custom templates . . . . . . . . . . . . . . . . . . . 101
4.1.12 Other features . . . . . . . . . . . . . . . . . . . . . 102
4.2 Slidy presentation . . . . . . . . . . . . . . . . . . . . . . . 102
4.2.1 Display modes . . . . . . . . . . . . . . . . . . . . . 104
4.2.2 Text size . . . . . . . . . . . . . . . . . . . . . . . . 104
4.2.3 Footer elements . . . . . . . . . . . . . . . . . . . . 105
4.2.4 Other features . . . . . . . . . . . . . . . . . . . . . 105
4.3 Beamer presentation . . . . . . . . . . . . . . . . . . . . . . 106
4.3.1 Themes . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.3.2 Slide level . . . . . . . . . . . . . . . . . . . . . . . 108
4.3.3 Other features . . . . . . . . . . . . . . . . . . . . . 109
4.4 PowerPoint presentation . . . . . . . . . . . . . . . . . . . 109
4.4.1 Custom templates . . . . . . . . . . . . . . . . . . . 112
4.4.2 Other features . . . . . . . . . . . . . . . . . . . . . 113

III Extensions 115

Visit https://textbookfull.com
now to explore a rich
collection of eBooks, textbook
and enjoy exciting offers!
x Contents

5 Dashboards 117
5.1 Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.1.1 Row-based layouts . . . . . . . . . . . . . . . . . . 120
5.1.2 Attributes on sections . . . . . . . . . . . . . . . . . 120
5.1.3 Multiple pages . . . . . . . . . . . . . . . . . . . . . 121
5.1.4 Story boards . . . . . . . . . . . . . . . . . . . . . . 123
5.2 Components . . . . . . . . . . . . . . . . . . . . . . . . . . 124
5.2.1 Value boxes . . . . . . . . . . . . . . . . . . . . . . 125
5.2.2 Gauges . . . . . . . . . . . . . . . . . . . . . . . . . 126
5.2.3 Text annotations . . . . . . . . . . . . . . . . . . . . 128
5.2.4 Navigation bar . . . . . . . . . . . . . . . . . . . . . 130
5.3 Shiny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
5.3.1 Getting started . . . . . . . . . . . . . . . . . . . . . 132
5.3.2 A Shiny dashboard example . . . . . . . . . . . . . 132
5.3.3 Input sidebar . . . . . . . . . . . . . . . . . . . . . 135
5.3.4 Learning more . . . . . . . . . . . . . . . . . . . . . 135

6 Tufte Handouts 137

6.1 Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
6.2 Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.2.1 Margin figures . . . . . . . . . . . . . . . . . . . . . 139
6.2.2 Arbitrary margin content . . . . . . . . . . . . . . . 139
6.2.3 Full-width figures . . . . . . . . . . . . . . . . . . . 140
6.2.4 Main column figures . . . . . . . . . . . . . . . . . 141
6.3 Sidenotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6.4 References . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.5 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.6 Block quotes . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.7 Responsiveness . . . . . . . . . . . . . . . . . . . . . . . . 144
6.8 Sans-serif fonts and epigraphs . . . . . . . . . . . . . . . . 145
6.9 Customize CSS styles . . . . . . . . . . . . . . . . . . . . . 145

7 xaringan Presentations 147

7.1 Get started . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
7.2 Keyboard shortcuts . . . . . . . . . . . . . . . . . . . . . . 149
7.3 Slide formatting . . . . . . . . . . . . . . . . . . . . . . . . 150
7.3.1 Slides and properties . . . . . . . . . . . . . . . . . 150
7.3.2 The title slide . . . . . . . . . . . . . . . . . . . . . 152
7.3.3 Content classes . . . . . . . . . . . . . . . . . . . . 153
7.3.4 Incremental slides . . . . . . . . . . . . . . . . . . . 154
Contents xi

7.3.5 Presenter notes . . . . . . . . . . . . . . . . . . . . 155

7.3.6 yolo: true . . . . . . . . . . . . . . . . . . . . . . . . 156
7.4 Build and preview slides . . . . . . . . . . . . . . . . . . . 157
7.5 CSS and themes . . . . . . . . . . . . . . . . . . . . . . . . 158
7.6 Some tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
7.6.1 Autoplay slides . . . . . . . . . . . . . . . . . . . . 159
7.6.2 Countdown timer . . . . . . . . . . . . . . . . . . . 160
7.6.3 Highlight code lines . . . . . . . . . . . . . . . . . . 160
7.6.4 Working offline . . . . . . . . . . . . . . . . . . . . 161
7.6.5 Macros . . . . . . . . . . . . . . . . . . . . . . . . . 162
7.6.6 Disadvantages . . . . . . . . . . . . . . . . . . . . . 163

8 reveal.js Presentations 165

8.1 Display modes . . . . . . . . . . . . . . . . . . . . . . . . . 166
8.2 Appearance and style . . . . . . . . . . . . . . . . . . . . . 167
8.2.1 Smaller text . . . . . . . . . . . . . . . . . . . . . . 167
8.3 Slide transitions . . . . . . . . . . . . . . . . . . . . . . . . 168
8.4 Slide backgrounds . . . . . . . . . . . . . . . . . . . . . . . 169
8.5 2-D presenations . . . . . . . . . . . . . . . . . . . . . . . . 169
8.6 Custom CSS . . . . . . . . . . . . . . . . . . . . . . . . . . 170
8.6.1 Slide IDs and classes . . . . . . . . . . . . . . . . . 170
8.6.2 Styling text spans . . . . . . . . . . . . . . . . . . . 171
8.7 reveal.js options . . . . . . . . . . . . . . . . . . . . . . . . 171
8.8 reveal.js plugins . . . . . . . . . . . . . . . . . . . . . . . . 172
8.9 Other features . . . . . . . . . . . . . . . . . . . . . . . . . 173

9 Community Formats 175

9.1 Lightweight Pretty HTML Documents . . . . . . . . . . . . 175
9.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . 176
9.1.2 Package vignettes . . . . . . . . . . . . . . . . . . . 176
9.2 The rmdformats package . . . . . . . . . . . . . . . . . . . 177
9.3 Shower presentations . . . . . . . . . . . . . . . . . . . . . 179

10 Websites 181
10.1 Get started . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
10.2 The directory structure . . . . . . . . . . . . . . . . . . . . 183
10.3 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . 184
10.4 Other site generators . . . . . . . . . . . . . . . . . . . . . 185
10.5 rmarkdown’s site generator . . . . . . . . . . . . . . . . . . 185
10.5.1 A simple example . . . . . . . . . . . . . . . . . . . 186
xii Contents

10.5.2 Site authoring . . . . . . . . . . . . . . . . . . . . . 187

10.5.3 Common elements . . . . . . . . . . . . . . . . . . 190
10.5.4 Site navigation . . . . . . . . . . . . . . . . . . . . . 193
10.5.5 HTML generation . . . . . . . . . . . . . . . . . . . 195
10.5.6 Site configuration . . . . . . . . . . . . . . . . . . . 196
10.5.7 Publishing websites . . . . . . . . . . . . . . . . . . 197
10.5.8 Additional examples . . . . . . . . . . . . . . . . . 197
10.5.9 Custom site generators . . . . . . . . . . . . . . . . 198

11 HTML Documentation for R Packages 201

11.1 Get started . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
11.2 Components . . . . . . . . . . . . . . . . . . . . . . . . . . 202
11.2.1 Home page . . . . . . . . . . . . . . . . . . . . . . 203
11.2.2 Function reference . . . . . . . . . . . . . . . . . . . 203
11.2.3 Articles . . . . . . . . . . . . . . . . . . . . . . . . . 204
11.2.4 News . . . . . . . . . . . . . . . . . . . . . . . . . . 204
11.2.5 Navigation bar . . . . . . . . . . . . . . . . . . . . . 204

12 Books 205
12.1 Get started . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
12.2 Project structure . . . . . . . . . . . . . . . . . . . . . . . . 207
12.2.1 Index file . . . . . . . . . . . . . . . . . . . . . . . . 208
12.2.2 Rmd files . . . . . . . . . . . . . . . . . . . . . . . . 208
12.2.3 _bookdown.yml . . . . . . . . . . . . . . . . . . . . 209
12.2.4 _output.yml . . . . . . . . . . . . . . . . . . . . . . 209
12.3 Markdown extensions . . . . . . . . . . . . . . . . . . . . . 209
12.3.1 Number and reference equations . . . . . . . . . . . 210
12.3.2 Theorems and proofs . . . . . . . . . . . . . . . . . 210
12.3.3 Special headers . . . . . . . . . . . . . . . . . . . . 211
12.3.4 Text references . . . . . . . . . . . . . . . . . . . . . 211
12.3.5 Cross referencing . . . . . . . . . . . . . . . . . . . 212
12.4 Output Formats . . . . . . . . . . . . . . . . . . . . . . . . 213
12.4.1 HTML . . . . . . . . . . . . . . . . . . . . . . . . . 213
12.4.2 LaTeX/PDF . . . . . . . . . . . . . . . . . . . . . . 214
12.4.3 E-books . . . . . . . . . . . . . . . . . . . . . . . . 214
12.4.4 A single document . . . . . . . . . . . . . . . . . . 214
12.5 Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
12.5.1 Build the book . . . . . . . . . . . . . . . . . . . . . 215
12.5.2 Preview a chapter . . . . . . . . . . . . . . . . . . . 216
12.5.3 Serve the book . . . . . . . . . . . . . . . . . . . . . 216
Contents xiii

12.5.4 RStudio addins . . . . . . . . . . . . . . . . . . . . 216

12.6 Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
12.6.1 RStudio Connect . . . . . . . . . . . . . . . . . . . 217
12.6.2 Other services . . . . . . . . . . . . . . . . . . . . . 217
12.6.3 Publishers . . . . . . . . . . . . . . . . . . . . . . . 217

13 Journals 219
13.1 Get started . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
13.2 rticles templates . . . . . . . . . . . . . . . . . . . . . . . . 222
13.3 Using a template . . . . . . . . . . . . . . . . . . . . . . . . 222
13.4 LaTeX content . . . . . . . . . . . . . . . . . . . . . . . . . 224
13.5 Linking with bookdown . . . . . . . . . . . . . . . . . . . 224
13.6 Contributing templates . . . . . . . . . . . . . . . . . . . . 225

14 Interactive Tutorials 227

14.1 Get started . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
14.2 Tutorial types . . . . . . . . . . . . . . . . . . . . . . . . . 229
14.3 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
14.3.1 Solutions . . . . . . . . . . . . . . . . . . . . . . . . 230
14.3.2 Hints . . . . . . . . . . . . . . . . . . . . . . . . . . 231
14.4 Quiz questions . . . . . . . . . . . . . . . . . . . . . . . . . 233
14.5 Videos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
14.6 Shiny components . . . . . . . . . . . . . . . . . . . . . . . 235
14.7 Navigation and progress tracking . . . . . . . . . . . . . . 235

IV Other Topics 237

15 Parameterized reports 239

15.1 Declaring parameters . . . . . . . . . . . . . . . . . . . . . 239
15.2 Using parameters . . . . . . . . . . . . . . . . . . . . . . . 240
15.3 Knitting with parameters . . . . . . . . . . . . . . . . . . . 241
15.3.1 The Knit button . . . . . . . . . . . . . . . . . . . . 241
15.3.2 Knit with custom parameters . . . . . . . . . . . . . 241
15.3.3 The interactive user interface . . . . . . . . . . . . . 242
15.4 Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

16 HTML Widgets 247

16.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
16.2 A widget example (sigma.js) . . . . . . . . . . . . . . . . . 248
16.2.1 File layout . . . . . . . . . . . . . . . . . . . . . . . 249
16.2.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 250
xiv Contents

16.2.3 R binding . . . . . . . . . . . . . . . . . . . . . . . 250

16.2.4 JavaScript binding . . . . . . . . . . . . . . . . . . . 252
16.2.5 Demo . . . . . . . . . . . . . . . . . . . . . . . . . . 255
16.3 Creating your own widgets . . . . . . . . . . . . . . . . . . 256
16.3.1 Requirements . . . . . . . . . . . . . . . . . . . . . 256
16.3.2 Scaffolding . . . . . . . . . . . . . . . . . . . . . . . 257
16.3.3 Other packages . . . . . . . . . . . . . . . . . . . . 258
16.4 Widget sizing . . . . . . . . . . . . . . . . . . . . . . . . . 258
16.4.1 Specifying a sizing policy . . . . . . . . . . . . . . . 259
16.4.2 JavaScript resize method . . . . . . . . . . . . . . . 260
16.5 Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . 264
16.5.1 Data transformation . . . . . . . . . . . . . . . . . . 264
16.5.2 Passing JavaScript functions . . . . . . . . . . . . . 269
16.5.3 Custom widget HTML . . . . . . . . . . . . . . . . 270
16.5.4 Create a widget without an R package . . . . . . . . 271

17 Document Templates 273

17.1 Template structure . . . . . . . . . . . . . . . . . . . . . . . 274
17.2 Supporting files . . . . . . . . . . . . . . . . . . . . . . . . 276
17.3 Custom Pandoc templates . . . . . . . . . . . . . . . . . . 277
17.4 Sharing your templates . . . . . . . . . . . . . . . . . . . . 278

18 Creating New Formats 279

18.1 Deriving from built-in formats . . . . . . . . . . . . . . . . 279
18.2 Fully custom formats . . . . . . . . . . . . . . . . . . . . . 280
18.3 Using a new format . . . . . . . . . . . . . . . . . . . . . . 282

19 Shiny Documents 283

19.1 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . 283
19.2 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . 287
19.2.1 ShinyApps.io . . . . . . . . . . . . . . . . . . . . . 287
19.2.2 Shiny Server / RStudio Connect . . . . . . . . . . . 288
19.3 Embedded Shiny apps . . . . . . . . . . . . . . . . . . . . 289
19.3.1 Inline applications . . . . . . . . . . . . . . . . . . . 289
19.3.2 External applications . . . . . . . . . . . . . . . . . 290
19.4 Shiny widgets . . . . . . . . . . . . . . . . . . . . . . . . . 290
19.4.1 The shinyApp() function . . . . . . . . . . . . . . . 290
19.4.2 Example: k-Means clustering . . . . . . . . . . . . . 291
19.4.3 Widget size and layout . . . . . . . . . . . . . . . . 293
19.5 Multiple pages . . . . . . . . . . . . . . . . . . . . . . . . . 293
Contents xv

19.6 Delayed rendering . . . . . . . . . . . . . . . . . . . . . . . 294

19.7 Output arguments for render functions . . . . . . . . . . . 294
19.7.1 A caveat . . . . . . . . . . . . . . . . . . . . . . . . 297

Bibliography 299

Index 303
List of Tables

3.1 The possible values of the df_print option for the

html_document format. . . . . . . . . . . . . . . . . . . . . . 55
3.2 The options for paged HTML tables. . . . . . . . . . . . . . . 56
3.3 The possible values of the df_print option for the
pdf_document format. . . . . . . . . . . . . . . . . . . . . . 81
3.4 Available top-level YAML metadata variables for LaTeX out-
put. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.5 Markdown variants for some popular publishing systems. . 89

8.1 The currently supported reveal.js plugins. . . . . . . . . . . 172

15.1 Possible input types and the associated Shiny functions for pa-
rameterized reports. . . . . . . . . . . . . . . . . . . . . . . 245

16.1 Options that can be specified within a sizing policy. . . . . . 261

xvii
List of Figures

2.1 A minimal R Markdown example in RStudio. . . . . . . . . . 7

2.2 The output document of the minimal R Markdown example
in RStudio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 A screenshot of RPubs.com that contains some homework ass-
ginments submitted by students. . . . . . . . . . . . . . . . . 11
2.4 The output formats listed in the dropdown menu on the RStu-
dio toolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.5 Two plots side-by-side. . . . . . . . . . . . . . . . . . . . . . 28
2.6 The R Markdown hex logo. . . . . . . . . . . . . . . . . . . . 29
2.7 An R Markdown document with a leaflet map widget. . . . . 43
2.8 An R Markdown document with a Shiny widget. . . . . . . . 45

3.1 Traditional tabs and pill tabs on an HTML page. . . . . . . . 52

3.2 A paged table in the HTML output document. . . . . . . . . 56
3.3 An R Notebook example. . . . . . . . . . . . . . . . . . . . . 64
3.4 Send the R code chunk output to the console. . . . . . . . . . 65
3.5 Select the code to split into a new chunk. . . . . . . . . . . . 65
3.6 Insert a new chunk from the code selected before. . . . . . . 66
3.7 Insert a new chunk from the code selected before. . . . . . . 67
3.8 Output from an inline R expression in the notebook. . . . . . 69
3.9 Execute a code chunk read from an external R script. . . . . . 70
3.10 Preview a notebook. . . . . . . . . . . . . . . . . . . . . . . 71
3.11 Errors in a notebook. . . . . . . . . . . . . . . . . . . . . . . 72

4.1 Two sample slides in an ioslides presentation. . . . . . . . . 94

4.2 Two sample slides in a Slidy presentation. . . . . . . . . . . 104
4.3 Two sample slides in a Beamer presentation. . . . . . . . . . 107
4.4 Two sample slides with the AnnArbor theme in Beamer. . . . 108
4.5 A sample slide in a PowerPoint presentation. . . . . . . . . . 111

5.1 A quick example of the dashboard layout. . . . . . . . . . . 120

5.2 Multiple pages on a dashboard. . . . . . . . . . . . . . . . . 122

xix
Visit https://textbookfull.com
now to explore a rich
collection of eBooks, textbook
and enjoy exciting offers!
xx List of Figures

5.3 An example story board. . . . . . . . . . . . . . . . . . . . . 124

5.4 Three value boxes side by side on a dashboard. . . . . . . . . 126
5.5 Three gauges side by side on a dashboard. . . . . . . . . . . 127
5.6 Text annotations on a dashboard. . . . . . . . . . . . . . . . 130
5.7 An interactive dashboard based on Shiny. . . . . . . . . . . . 134

6.1 The basic layout of the Tufte style. . . . . . . . . . . . . . . . 138

6.2 A margin figure in the Tufte style. . . . . . . . . . . . . . . . 140
6.3 A full-width figure in the Tufte style. . . . . . . . . . . . . . 141
6.4 A figure in the main column in the Tufte style. . . . . . . . . 142
6.5 A table in the Tufte style. . . . . . . . . . . . . . . . . . . . . 144
6.6 The Tufte HTML style on narrow screens. . . . . . . . . . . . 145

7.1 Two sample slides created from the xaringan package. . . . . 147
7.2 Separate the current display from the external display. . . . . 156

8.1 Two sample slides created from the revealjs package. . . . . 166

9.1 The leonids theme of the prettydoc package. . . . . . . . . . 177

9.2 The Material Design theme in the rmdformats package. . . . 178
9.3 A few sample slides created via the Shower presentation
framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

10.1 Knit a single page of a website. . . . . . . . . . . . . . . . . . 188

10.2 Build an entire website in RStudio. . . . . . . . . . . . . . . 188
10.3 Preview a page side-by-side with the editor in RStudio. . . . 189

11.1 A screenshot of the pkgdown website. . . . . . . . . . . . . . 202

12.1 The HTML output of the bookdown template. . . . . . . . . 206

12.2 The Build tab within RStudio highlighting bookdown output
formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

13.1 Two journal templates in the rticles package (PLOS and

Springer). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
13.2 The R Markdown template window in RStudio showing avail-
able rticles templates. . . . . . . . . . . . . . . . . . . . . . . 221

14.1 Create an interactive tutorial in RStudio. . . . . . . . . . . . 228

14.2 A simple example tutorial. . . . . . . . . . . . . . . . . . . . 229
14.3 A solution to an exercise. . . . . . . . . . . . . . . . . . . . . 231
14.4 A question in a tutorial. . . . . . . . . . . . . . . . . . . . . . 234
List of Figures xxi

14.5 Keeping track of the student’s progress in a tutorial. . . . . . 236

15.1 Input parameter values interactively for parameterized re-

ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
15.2 Custom controls for parameters. . . . . . . . . . . . . . . . . 245

16.1 A graph generated using the sigma.js library and the sigma
package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

17.1 Selecting R Markdown templates within RStudio. . . . . . . 274

19.1 Create a new Shiny document in RStudio. . . . . . . . . . . . 284

19.2 Increase the number of rows in the table in a Shiny document. 285
19.3 Change the number of bins of a histogram in a Shiny docu-
ment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
19.4 Deploy a Shiny document to ShinyApps.io. . . . . . . . . . . 288
19.5 A Shiny widget to apply k-Means clustering on a dataset. . . 291
Preface

The document format “R Markdown” was first introduced in the knitr pack-
age (Xie, 2015, 2018d) in early 2012. The idea was to embed code chunks (of
R or other languages) in Markdown documents. In fact, knitr supported sev-
eral authoring languages from the beginning in addition to Markdown, in-
cluding LaTeX, HTML, AsciiDoc, reStructuredText, and Textile. Looking back
over the five years, it seems to be fair to say that Markdown has become the
most popular document format, which is what we expected. The simplicity
of Markdown clearly stands out among these document formats.

However, the original version of Markdown invented by John Gruber1 was

often found overly simple and not suitable to write highly technical docu-
ments. For example, there was no syntax for tables, footnotes, math expres-
sions, or citations. Fortunately, John MacFarlane created a wonderful pack-
age named Pandoc (http://pandoc.org) to convert Markdown documents
(and many other types of documents) to a large variety of output formats.
More importantly, the Markdown syntax was significantly enriched. Now
we can write more types of elements with Markdown while still enjoying its
simplicity.

In a nutshell, R Markdown stands on the shoulders of knitr and Pandoc. The

former executes the computer code embedded in Markdown, and converts R
Markdown to Markdown. The latter renders Markdown to the output format
you want (such as PDF, HTML, Word, and so on).

The rmarkdown package (Allaire et al., 2018c) was first created in early 2014.
During the past four years, it has steadily evolved into a relatively complete
ecosystem for authoring documents, so it is a good time for us to provide a
definitive guide to this ecosystem now. At this point, there are a large number
of tasks that you could do with R Markdown:

• Compile a single R Markdown document to a report in different formats,

such as PDF, HTML, or Word.
1
https://en.wikipedia.org/wiki/Markdown

xxiii
xxiv Preface

• Create notebooks in which you can directly run code chunks interactively.

• Make slides for presentations (HTML5, LaTeX Beamer, or PowerPoint).

• Produce dashboards with flexible, interactive, and attractive layouts.

• Build interactive applications based on Shiny.

• Write journal articles.

• Author books of multiple chapters.

• Generate websites and blogs.

There is a fundamental assumption underneath R Markdown that users

should be aware of: we assume it suffices that only a limited number of fea-
tures are supported in Markdown. By “features”, we mean the types of ele-
ments you can create with native Markdown. The limitation is a great feature,
not a bug. R Markdown may not be the right format for you if you find these
elements not enough for your writing: paragraphs, (section) headers, block
quotations, code blocks, (numbered and unnumbered) lists, horizontal rules,
tables, inline formatting (emphasis, strikeout, superscripts, subscripts, verba-
tim, and small caps text), LaTeX math expressions, equations, links, images,
footnotes, citations, theorems, proofs, and examples. We believe this list of
elements suffice for most technical and non-technical documents. It may not
be impossible to support other types of elements in R Markdown, but you
may start to lose the simplicity of Markdown if you wish to go that far.

Epictetus once said, “Wealth consists not in having great possessions, but in hav-
ing few wants.” The spirit is also reflected in Markdown. If you can control
your preoccupation with pursuing typesetting features, you should be much
more efficient in writing the content and can become a prolific author. It is
entirely possible to succeed with simplicity. Jung Jae-sung was a legendary
badminton player with a remarkably simply playing style: he did not look
like a talented player and was very short compared to other players, so most
of the time you would just see him jump three feet off the ground and smash
like thunder over and over again in the back court until he beats his oppo-
nents.

Please do not underestimate the customizability of R Markdown because of

the simplicity of its syntax. In particular, Pandoc templates can be surpris-
ingly powerful, as long as you understand the underlying technologies such
as LaTeX and CSS, and are willing to invest time in the appearance of your
output documents (reports, books, presentations, and/or websites). As one
Random documents with unrelated
content Scribd suggests to you:
on the sand-dunes there. Then the sea piled the sand up, changed
the course o’ the river, and she’s been left high and dry ever since.”
“You mean the old Sea-Lark?” put in Jack.
The watchman nodded.
“I know where she is,” observed the boy. “I’ve climbed aboard her
several times. She’s lying a couple of hundred yards from the river
now.”
“Well,” Cap’n Crumbie went on, “that night, just when the gale was
starting, your father left the office with the money he’d drawn from
the bank to pay off the crew of the Grace and Ella. It was in a canvas
bag, notes and silver together, and he didn’t like leaving it at the
office all night. I was coming down High Street, when I met the
parson, and we walked along together a ways. It was hard going and
all-fired dark, when we turned down Wharf Street and fell right over
your father. He was lying all in a heap on the sidewalk. I didn’t know
it was him at first, mind you, because it was so dark. Parson and me
tried to get him onto his feet, but he was all limp, like a wet string,
and so we carried him into Simmons’s house, and there we saw who
it was. When he recovered a bit he told us he’d been robbed. He had
no idea who’d done it. All he knew was that he was hurrying along,
with his head bent down, when some one laid hold of him. Then he
got a smashing blow on the head, and didn’t know anything more
until he came to in Simmons’s kitchen.”
“And the police never found any clue?” Jack asked.
“Not as I ever heard of. But Simon Barker went nearly crazy. You’d
have thought, by the way he fussed, that Sam Holden was the
biggest criminal unhung. Barker lost his head. He’s that mean he
hates to see a mosquito walking on his wall-paper ’cause it’s wearing
out the paper. You’d have thought it was him that had been half killed
instead of Sam Holden. He swore ’twas a put-up job, and that your
father had done it himself somehow, to get away with the money.
And mighty unpopular he made himself by saying such things. Some
of us told him what we thought o’ him, next day, and then he began
to calm down a bit, but by that time the thief had covered up his
tracks, and nobody has ever heard any explanation o’ what
happened, from that day to this. It cost your father his partnership in
the business, ’cause he had too much pride to go on working with a
man who had as good as called him a thief, and he sold his home to
replace the money that was stolen. I did hear that Simon Barker
came near dropping dead when your dad handed it to him. You see,
if things had been t’other way round, Barker couldn’t have brought
himself to do such a thing in a month o’ Sundays, and so he couldn’t
understand any one else doing it. Your father wasn’t obliged to pay
the money to Barker, o’ course. If a thing gets stole, it’s stole, and
that’s all there is to it. But your father wanted to clear his name. And
he did, don’t you ever doubt it, Jack! Maybe Barker still has a
sneaking notion that it was a put-up job, but if he does I can’t see
how he figures your father made anything by it!”
“How can he?” protested Jack.
Cap’n Crumbie shook his head, and cast a glance in the direction
of the tug Simon P. Barker, which was being coaled noisily at its
owner’s wharf thirty yards away.
“I ain’t no Shylock Holmes, son,” he said. “Maybe he thinks what
he says, and maybe he says what he don’t think. I shouldn’t faint
right now if some one told me here and now that Barker knew more
than your father did about the robbery.”
“You don’t mean—”
“No, Jack, no. I ain’t saying Barker had anything to do with it,
because, to give him his due, he wasn’t never convicted o’ theft. I
b’lieve he’s honest, and if he is, it’s only because he’s too mean to
give his time to the Government, in prison.”
The conversation was interrupted by the approach of a stranger,
who, after looking across the harbor, addressed the watchman.
“Pardon me,” he said, “but will you tell me where I can find the
ferry to East Greenport?”
“There ain’t no ferry, and there ain’t never been one,” replied the
watchman, “though ’tain’t for the want o’ customers. Sometimes in
the summer I’ve been asked that same question a dozen times a
day.”
“How can I get over there?” the stranger asked, looking dubiously
at the intervening mile of water. “There is no trolley and it is rather a
long way to walk with this grip.”
“A little ways round that corner,” replied the watchman, pointing off
the wharf, “you’ll find Hinkley’s stable, and you’ll get a carriage
there.”
Cap’n Crumbie watched the man speculatively until he had
disappeared, but Jack was looking out at the stretch of water
between the wharf and the distant hotel, with a puzzled expression.
“I say, Cap’n,” he said a few moments later, “did you mean it when
you said lots of people want to be ferried across to the Point during
the summer?”
“Why, yes, son,” replied the watchman. “You never heard me say
anything that wasn’t the truth, did you?”
Jack smiled and almost made some reference to the Indian
Ocean; but other thoughts were buzzing at the back of his brain.
“Why hasn’t anybody ever started a ferry, then, if there’s need of
one?” he asked.
Cap’n Crumbie put his head on one side and looked down at the
ocean.
“Ever swallow sea-water, Jack?” he asked.
“When I was swimming, many a time.”
“What does it taste of?”
“Salt, of course.”
“Salt is right. But there’s all manner o’ things in it besides salt—
even gold, I’ve heard say. It’s there, for the taking, and no danger o’
the ocean running dry. Well, did you ever hear o’ any one in
Greenport starting to take salt or gold out o’ the sea. No. O’ course
you didn’t. Don’t ask me why. I don’t know. But I reckon it’s about the
same reason why nobody ever started to run a ferry across to the
Point from here. Either they didn’t think of it, or it’s too much trouble.”
“When the summer cottagers come back and the hotel opens, I
guess there would be plenty of business,” Jack mused. “You’d think
the hotel alone would make it pay.”
“Probably ’twould,” the Cap’n agreed.
“I’m sure of it,” said Jack, thoughtfully; and then, as his eyes fell on
something away out to sea, beyond the breakwater, he suppressed
an exclamation and glanced amusedly at Cap’n Crumbie, who was
engaged in a contest with his obstinate pipe.
“Too bad about Bob Sennet!” the boy said. “You think the Ellen E.
Hanks must have foundered with all hands, don’t you?”
“Aye, with all hands,” declared Cap’n Crumbie, wagging his head.
“Fathoms deep, they must be now, floating around among the fish
they went after. I’m not denying they’d ha’ made a big haul o’
mackerel, and they’d ha’ had the market all to themselves. But there,
obstinate folks have to pay for their obstinacy sooner or later! I
warned Bob, but ’twas no use.”
“There’s a boat coming in now,” said the boy, pointing to the craft,
which, with all sail set, was rounding the end of the breakwater, her
hatches evidently full, for her hull was low. “If she isn’t the Ellen E.
Hanks she’s awfully like her.”
Cap’n Crumbie shot a glance over the harbor, and a look of
mingled surprise and chagrin crossed his rugged face.
“Humph!” he said finally. “Some folks are like Jeff Trefry’s old tom-
cat for luck. Jeff tied the cat up in a sack and dropped him off the
wharf and afore he’d more than turned around that cat comes
marchin’ into the kitchen with a flounder in his mouth!”
 CHAPTER II
GEORGE SIGNS ON

A few minutes later Jack left the watchman, and made his way
through town toward the cottage in which he lived. And as he
went, his mind busied itself with the idea of the ferry suggested by
Cap’n Crumbie.
Jack Holden was as care-free as any boy of his age in Greenport.
For him, life so far had contained little but healthy sport and
amusement, and the question of earning money had never
concerned him. Nor was it the wish of his father that it should. Yet,
despite his natural light-heartedness, Jack had a level head. The
time would come, and before very long, when he must face the
problem of winning a place for himself in the world. It had been
decided that, if it could be arranged, he was to spend another two
years at High School, after which he would seek a position. But two
years is a long time, and Jack was by no means certain that he
would not have to turn out and become a wage-earner long before
his education was completed. For his father was now a very different
man from the old Samuel Holden. Since the robbery, troubles had
piled themselves on his shoulders somewhat seriously. First had
come the loss of Jack’s mother, from which Mr. Holden had never
really recovered. Then had followed that blow on the head inflicted
by the thief, which had necessitated numerous visits to a costly eye
specialist, in order to preserve his sight. Finally, with his business
taken away from under his feet, he had been in financial straits ever
since. After selling his home to make good the missing money, he
had taken a small cottage on the outskirts of Greenport and gone to
work as a bookkeeper for Garnett and Sayer, the fish-packers. Had
his wife lived, with her indomitable spirit and unending courage—
characteristics which, fortunately, she had bestowed upon her son—
she would have buoyed him up and kept alive his old ambition. But
now his worries told on him, and it was that fact which caused Jack
to wonder sometimes whether his own education would ever be
completed as he would like it to be.
If, he reflected, as he walked home, he could only start that ferry
and so bring a little grist to the mill, it would at least help to relieve
his father of some of his anxiety. But one cannot make bricks without
straw. And he was face to face with the cold fact that he had no boat,
nor any chance of acquiring one. At home, he looked over his sum
total of worldly possessions. There was four dollars and twenty cents
in the savings-bank. He had a nickel and two dimes in his pocket.
Also, he owned a silver watch, of little value, as most of its works
were missing. There was a penknife, which he had bought after
much careful deliberation, and there was—well, little else save
rubbish, worth nothing when it came to a question of raising enough
money to buy a boat suitable for Holden’s Ferry.
“Holden’s Ferry!” Jack repeated aloud, smiling a little at the sound.
The name had an agreeable ring to it. It would be fun. And at the
same time it might be fairly profitable fun.
In the evening, when his father returned, Jack immediately
introduced the subject uppermost in his thoughts.
“Dad,” he began impulsively, “how can I get a boat, twenty feet
long, or something like that—one that will hold ten or a dozen people
and won’t leak more than about ten buckets of water an hour.”
“Eh? What’s that?” asked Mr. Holden, in surprise.
“I’ve got an idea, and I want a boat, Dad,” replied Jack. “I thought
—perhaps—somehow—”
“I wish I could buy you one, my lad,” said Mr. Holden, a trifle
dejectedly, “but you’ll have to wait till my ship comes in.”
“I don’t want it for pleasure—not altogether, that is,” the boy
declared.
“Not for pleasure? Then what on earth— Are you thinking of
setting up in the shipping business?”
Jack chuckled.
 “I may do a little freight-carrying,” he said with mock seriousness,
“but the passenger trade is what I was thinking of chiefly.”
“Modest youth! You’ll want to go into steam for that, though,” said
Mr. Holden, jokingly. “It is a pretty tall proposition for a youngster of
your age. Have you fixed on just what ports you are going to trade
at?”
“Only Greenport, Dad. But I’m in earnest.”
Still slightly amused, Mr. Holden stroked his chin and eyed his son
inquiringly.
“Well, what is this wonderful scheme of yours?” he asked.
“I want to run a ferry between Garnett and Sayer’s wharf and the
hotel landing on the Point,” the boy replied. “There is no way of
getting across except by hiring a boat or walking around, or taking a
carriage; and plenty of people would pay a dime to be run across
there in a ferry-boat.”
“Yes, but—”
“Wait a minute, Dad. I’ve had this in my mind all the afternoon.
Cap’n Crumbie tells me there are lots of people who inquire for the
ferry in the summer. He says there never has been one, but that is
no reason why there shouldn’t be one now. Perhaps I wouldn’t make
lots of money at it, but I’m old enough to help you a bit, and I don’t
want to loaf all through vacation, because I know you’ve had worry
enough and that you’re going to have a tough time keeping me in
school until I finish.”
“Well?” observed Samuel Holden, rather vaguely.
“I was wondering,” continued the boy, “whether you could manage
somehow to buy me the sort of boat I’d need. Almost anything would
do that was half-way decent—and clean, too, because summer folk
wouldn’t want to get into her if she wasn’t.”
Mr. Holden shook his head slowly. “I dare say it might work out all
right, Jack,” he said, “and a little more money would come in very
handy, but you’d better get the notion out of your head, son, before
you waste any more time thinking about it. I couldn’t afford to buy
you even a dory, and it’s about six times too far across the water at
that point to row, anyway.”
“All right, Dad,” said Jack, quietly. He realized that there was no
use in asking his father to perform impossibilities. Later in the
evening Mr. Holden noted an expression of quiet determination in the
lad’s face such as he had so often seen in Mrs. Holden’s when,
things not going well, her resourceful brain and stout heart had set
themselves the task of getting affairs back in order.
The next day was Saturday, and shortly after breakfast, there
being no school, Jack and his chum, George Santo, started off on a
hike toward the sand-dunes and salt-flats which lay for miles to the
north of Greenport. This region the boys had made their playground
ever since they were old enough to go about together. It was on the
bold summit of Indian Head, a rocky barrier which for centuries had
kept the encroaching sea at bay, that they had built their first
wigwam out of driftwood, and stood, at the mature ages of nine and
ten respectively, adorned with feathers and armed with spears,
guarding their hunting-grounds from the hated palefaces who never
seemed to approach much nearer than Greenport. From there they
let their eyes wander in imagination over vast herds of buffalo,
moose and antelope grazing peacefully on a far-stretching prairie. At
times, as the hated palefaces all seemed to be fully occupied
elsewhere, phantom palefaces had to blunder upon their hunting-
grounds, and these intruders were hastily despatched or led captive
to the driftwood wigwam, there to be held as hostages. There were
terrific battles up on Indian Head, but somehow or other, whatever
the overwhelming odds with which they were faced, the two lone
braves invariably came out from the encounters unscathed. But the
wigwam was now scattered to the four winds of heaven. The boys
had grown too old for that sort of make-believe; yet their love for the
region of dunes and marsh endured.
On this particular morning they headed over toward the salt-flats
above Cow Creek, and then followed the course of the Sangus River
toward the sea. They must have trudged half a dozen miles by this
circuitous route before Jack, standing on the rippled summit of a
wind-swept dune, drew his companion’s attention to the fact that the
Sangus had changed its sandy course.
“It must have been caused by the flood and the last gale,” he said.
“See, the water has come right across this low bit and—and—say,
George, the old sloop, the Sea-Lark, was lying nearly buried just
along here. I shouldn’t wonder if the river has swept her away now.
Come on, let’s see how the old dear is.”
Ten minutes’ tramping brought them to the place, and each gave a
cry of joy when they saw that the sloop lay exactly as she had lain
for three years. But she had escaped the effects of the recent gale
by a narrow margin only, for the Sangus had swirled over its banks,
eating its way through the sand to a new course, until it now flowed
within twenty feet of the Sea-Lark.
The boys climbed aboard the derelict, and with their legs dangling
over the side, with healthy appetites attacked a parcel of
sandwiches.
“I’m glad she’s still here,” said Jack. “Do you remember when I
was a pirate king last summer and made you walk the plank? We’ve
had lots of fun on this sloop. If she’d been lying a mile or so nearer
Greenport, crowds of kids would have been swarming all over her
and she’d have been broken up.”
George nodded, and poked the last of the sandwiches into his
mouth.
“Talking of boats,” Jack went on, “where do you suppose I could
get one, George?”
“What do you want her for? There’s my dory. You can have that
any time you want.”
“Thanks, George,” Jack replied. “But a dory isn’t just what I do
want.”
Then he explained.
“I don’t know. I guess a boat like that, one you could use for a
ferry, would cost money,” declared the other, when Jack had finished.
 “I thought maybe, your father being a boat-builder, you might know
of some way I could manage it,” said Jack. “There’s plenty of time,
because it’s early in the season yet, and maybe I’ll find what I want
somewhere.”
“If you do start the ferry I want to help. May I?” asked George.
“Why not?”
“You’ll be skipper and I’ll be mate,” said George, laughing.
“You mustn’t laugh at the captain—that is, not after you’re properly
appointed mate—” said Jack, “or I’ll order you put in irons. That’s
what they always do. Yes, laugh now, if you like, but wait till I’m your
captain. But why wait? See here, George Santo, weren’t you making
an application to me for a job just now?”
“Yes, sir,” replied George, meekly touching his cap.
“How old are you?” This, brusquely, as befitting a fearsome master
mariner.
“Fifteen, sir.”
“Umph! Pretty young for my class of trade. What’s your rating?”
“Chief mate, sir.”
“Got your certificate?”
“I left it at home, sir.”
“Umph! Very careless of you. Well, you want to sail with me, eh?
What about the compass? Can you box it?”
“I’m a pretty fair boxer, sir.”
“Not that sort of boxing, chump! All right, you’re engaged. Now, Mr.
Mate, laugh at me if you dare!”
Whereupon the mate promptly laughed, and Jack as promptly
hurled him overboard into the raging billows of sand. Jack then
strolled aft and stood for a few moments, measuring the distance
between the embedded sloop and the river.
 The mate, clambering aboard again, shouted something which fell
on deaf ears. Again George spoke, and again Jack made no answer.
At last, however, he emerged from his abstraction, and, “Come
here,” he called.
George obeyed, and Jack passed his arm through that of his
friend.
“Now, use your brain,” he said. “How far is it from here to the
stream?”
“Thirty feet,” the other guessed. “Why?”
“Wrong. It’s nearer twenty. And don’t ever ask the captain ‘why’
anything. He’s in supreme command; see? Tell me what is to prevent
us digging the Sea-Lark out of this and getting her afloat.”
“Afloat!” gasped the mate. “Why, you can’t do it! She’s stuck here.”
“Why can’t I do it?”
“Well,” began the mate, dubiously.
“You’ll be disrated if you don’t use more intelligence,” snapped the
skipper. “What are shovels for but to dig with?”
“Yes, but—” began George.
“But what?”
“Well, if you got her afloat she’d only sink. Her timbers will all be
rotten.”
“Show me a rotten timber!” said Jack. “I don’t mean these planks
that have got broken on deck. I mean in the hull. She’s as sound as
a bell. A boat like this would take years and years to rot. She’d need
some calking, I guess, but that’s what I engaged you for, isn’t it?—
while I sit in my deck chair and give orders. George, honestly, I
believe it could be done.”
“But she isn’t yours to float,” parried the mate, “nor to use after you
get her afloat.”
“That’s true,” agreed the skipper, frowning. “But you have got a
way of raising difficulties since I signed you on. Who does she
belong to?”
“She used to belong to Mr. Farnham,” replied George. “He’s a New
York man with pots of money, who lives over on the Point in the
summer. The sloop was in my father’s boat-yard for repairs the
summer before she broke away and got stranded here.”
“Well, do you suppose he wants her? I don’t believe so.”
“Don’t know,” observed George, doubtfully.
“Well, if he does want her, why doesn’t he come and get her? And
what could he use her for? A coal cellar, or what? She’s abandoned,
I tell you.”
“If you took her away from here, which you couldn’t do, anyway,”
observed the younger boy, “you’d be committing ship theft.”
“What’s that?”
“It’s a dreadful offense, worse than piracy. I believe they hang you
for it, or something.”
“I certainly don’t want you to get hanged,” said the captain. “Good
mates are scarce; and they always hang the mate, because he’s
engaged to make himself useful in little ways like that. But it wouldn’t
be ship theft if I wrote a letter to this Mr. Farnham and got his
permission, would it?”
“I suppose not.”
“Of course not. Where does he live?”
“My dad will have his address.”
“Well, don’t forget to ask him for it, and I’ll write. He can only
refuse.”
George, beginning to awake to the possibilities of the plan, cast a
more critical eye over the stranded sloop.
“I wouldn’t be surprised if you were right,” he said at length. “We
might get her into the water.”
 “It wouldn’t be exactly easy, because she’s pretty big,” Jack
admitted, “but it would be worth trying, anyway. What a prize if we
got her, though! She’s thirty foot over all, if she’s an inch. And ten—
no, twelve-foot beam. The only thing is, if she did float, we couldn’t
row her very well.”
“There’s bales of junk gear up at our yard,” put in George. “I
suppose her mast got broken off in the gale when she stranded. I
think I could get that fixed all right, though. There’s an old spar that
came out of her when she was refitted. I don’t know why it was taken
out, but it looks all right. We can find an old mainsail and jib
somewhere. Even if they need a bit of patching, they’ll do.”
“The boat is the chief thing,” Jack mused. “The rest will be easy,
once we get her. I’m going to send that letter off to-day. Let’s go
home now and do it.”
Letter-writing was not an occupation which, ordinarily, filled Jack
with joy. But this was not an ordinary occasion. After a first attempt
which he regarded as a failure, the boy produced a missive that was
both frank and polite, and then, feeling that he did not stand a ghost
of a chance of having his request granted, posted it. Later, he and
George walked to the boat-yard, there to consult George’s father,
Tony Santo, on the question of moving the Sea-Lark from her sandy
bed. Tony promised to go down the river and look the sloop over, the
following day, and was as good as his word. Jack and George
accompanied him in his sailing-dory, and to the delight of the boys
the boat-builder declared that there ought not to be a great deal of
difficulty in getting the sloop off, though he cautiously declined either
to have anything to do with such operations or allow his son to,
unless definite permission was received from Mr. Farnham. He
pointed out, however, that the accumulation of sand in the sloop’s
cabin would have to be removed before any attempt could be made
at shifting her. Her companionway door had evidently been open
when she grounded, with the result that in the three years which had
since elapsed the space below deck, a roomy cabin twelve feet by
nine, had been half filled with the fine white sand.
 During the next three days the boys, taking a shovel with them,
employed themselves busily at this task until the last of the
undesired ballast was removed. Jack now began to keep an anxious
lookout for the postman. Four days elapsed, and still no reply
arrived. Thursday came, and on returning from school he found an
envelope bearing his name, on the mantel-shelf. His fingers
unsteady with excitement, he tore it open and read:

Dear Sir:
I thought my old sloop must have been broken up by
now. Yes, she is still my property, and if you want her
you are welcome to her, on one condition. If you get
her afloat, you must take me for a sail in her some day.
Yours sincerely,
CHARLES FARNHAM.
 CHAPTER III
BACK TO THE WATER

S tuffing the letter into a pocket, Jack reached for his cap, and
hurried out to summon his crew, consisting of George Santo.
“All hands on deck!” he said. “Mr. Mate, we’re going to start work
right away. There are only three weeks of May left, and before long
we’ll have Holden’s Ferry going.”
“Aye, aye, sir,” replied the mate, “if ever we do get her floated.”
“If!” cried Jack. “You talk like a codfish. Of course we’re going to
get her floated! Before we do another thing, though, I’m going to hold
a war council with your dad. He knows best how we can tackle the
job.”
They hurried to the boat-builder’s yard, where Tony was found at
work.
“Mr. Farnham has given me that sloop,” Jack cried as he
approached. “See, here’s his letter.”
Tony’s features developed a broad smile, and he glanced through
the note.
“So you’ll soon be setting off on a journey around the world, or
thereabouts, eh?” he remarked at last, banteringly.
“Well, maybe about half-way, or perhaps as far as Greenport
breakwater,” Jack returned; “but you know, Mr. Santo, we can’t do
much till we get your help.”
“Well, what do you want me to do?” asked Tony good-humoredly,
putting down his hammer.
“I don’t want to bother you too much,” said Jack, “but you said that
if we got stuck you would give us a bit of help.”
 “Why, yes, I’ll run over there in the dory some Saturday and help
you to launch her, when you’re ready.”
“Thank you. That will be a tremendous help. Shall we dig a
channel down to the water and float her out that way, or dig the sand
away from her bow—she is lying bow-on toward the river, you know
—and get her out with a winch?”
“I’ll take a winch. That will be easier. I’ll find a place on the
opposite bank of the river where I can moor the winch, and then run
a cable across the water to the sloop. We’ll drag her out when you’ve
done enough spade-work. But mind, you want to get all that sand
clear away from her sides, and make a nice slope up from her bow
so that she won’t stick when the winch begins to haul on her. How
long will that take you? Till next fall?”
“I hope not. We couldn’t very well manage it by next Saturday.
That would only give us two days. But we’ll be ready for the winch
the Saturday after.”
“All right,” replied Tony. “We’ll make that a date.”
To any one less enthusiastic than her proud new owner, the sloop
would not, perhaps, have looked such a priceless possession. There
is something peculiarly desolate about the appearance of a wreck at
any time, and, at least up to the time when the Sangus had again
changed its course, the Sea-Lark had looked even more desolate
than she would otherwise have done, because she was so far from
the river. The water had left her canting over heavily to port, her
stump of mast, a yard long, sticking up. On the port side her deck
was now about level with the sand; her starboard side, raised four or
five feet higher, had formed a barrier against which a solid bank of
the restless sand had settled. Had she been an old boat and needing
paint at the time she came to grief, decay might have left its stamp
upon her in the three years she had lain there; but it so happened
that her oaken beams and hard-pine planking were as sound at the
time of the accident as on the day when they were first put into her,
while the fact that she had received a double coat of paint only two
months before, helped her further to resist the weather. She was not,
therefore, really a wreck, as nothing of any consequence, except the
mast, was broken.
Taking turn and turn about, the two boys worked strenuously, first
removing the sand that had silted up against her starboard side. It
was no light task, for the drift ran the whole length of the sloop, and
the lads’ backs were aching and their limbs weary before they
seemed to have made any impression on it. When the skipper called
a final halt, however, they were well pleased with the result of their
arduous labors. Nevertheless, Jack realized now for the first time
how great was the task he had set himself, and how hopeless would
be his efforts without the kindly assistance of Tony with the winch.
In three days the boys had entirely removed the drift, and then
began to dig down around the sides of the vessel, to release her
from the grip of the sand there. George proved not only a willing but
an extremely useful helper. Though not so tall as his chum, he was
strong, and gave promise of developing into an unusually powerful
man. But it was the spirit with which he threw himself into the task
that Jack appreciated as much as anything. Just before the date of
the appointment with Tony, once when they were resting, perched on
the side of the Sea-Lark, George surveyed the piles of sand which
they had removed in the past week.
“We only want one thing now,” he said thoughtfully, “to make us
both thoroughly happy.”
“What’s that?”
“A peach of a wind-storm, to fill up all the holes we’ve been
digging! If that happened, I don’t believe we’d have the pluck to start
all over again.”
“Don’t suggest such an awful thing,” cried Jack, “or I’ll smite you
with a belaying-pin! By the way, George, I can’t do that.”
“Oh, I am so sorry!” said the other. “Why not?”
“Because there doesn’t seem to be a belaying-pin on board. We’ll
need one or two, won’t we? The skipper always thumps people on
the head with a belaying-pin, particularly the mate. There’s
something about a marlinespike, too, isn’t there? I’m not quite sure
what a marlinespike is, but I think I club you with it when there isn’t a
belaying-pin handy.”
With a deft movement of his body, the mate got behind the skipper
and neatly tipped him overboard into the hole they had so
painstakingly dug; nor was the captain allowed to climb on board
again until the mate had extracted a promise that he would at all
times be treated in a humane manner when they were far out on the
bounding ocean.
During the last of the preparations for Tony’s operations their
spirits rose greatly, for it began to look as though the sloop merely
needed a gentle tug to slide her away from the bed in which she had
so long lain. At school on Friday Jack struggled hard to keep his
attention riveted on his lessons, but it was an effort in which he failed
utterly; for the launching on the morrow of the good ship Sea-Lark
seemed a matter of infinitely greater importance than the problems
that were put before him.
It was late that afternoon when the boy finally declared that all was
ready for the great ceremony. He and his chum had carried out
Tony’s instructions to the letter, even searching about on the bank of
the river for driftwood, which they dragged to the sloop and placed in
position just under her nose. That night Tony was informed of their
readiness for his part in the program, and the boat-builder bade them
be prepared for an early start next day, as it might take until late in
the afternoon to get through.
Not very long after sunrise next day Jack leaped from bed and
looked anxiously out at the window. It seemed as though the Fates
were going to be kind to him, because the weather was perfect for
the day’s operations. The boy was too impatient to eat much
breakfast, and after a hurried meal went round to the Santo boat-
yard, where he found Tony and George already moving the
necessary gear into the sailing-dory—much strong manila rope with
blocks and tackle, a powerful hand-winch, several heavy planks, a
number of rollers, and a bucket of grease. When these were aboard,
the sail was hoisted, and the dory dropped down the creek to the
river. There, as the stream was not over wide, the oars had to be
used, and the dory was rowed some four miles, Tony pulling steadily
all the time, and the boys taking turn and turn about at the other oar.
“It’s hard work against the wind,” said Tony, “but we shall feel the
benefit of it coming back.”
It was only a little after nine o’clock when they reached the spot
where the Sea-Lark lay, and some hours were left before high water
was due. First Tony went ashore and inspected the work the boys
had already done.
“That’s good,” he declared unhesitatingly. “She ought to come off
like a wet fish slides off a plate. Lend a hand with those rollers and
boards in the dory, and we’ll fix her.”
Already Tony seemed to take as keen an interest in the salvage
operations as the boys had done. He soon had everything ready on
that bank of the Sangus, and then crossed the river to moor the
winch in the sand there, so that it would haul without moving. This
was not easily accomplished, for the loose sand gave poor
anchorage. When, however, it was done to his satisfaction, the cable
was run across the water and made fast to the sloop. Tony sent the
boys back to start hauling, while he stood by the Sea-Lark to
“navigate” her. Jack and his chum each seized a crank and began to
tighten the cable. It came easily enough until the drag of the sloop
began. Then they managed a bare-half-turn only. Putting forth every
ounce of their strength, they struggled to start the sloop on her
journey toward the water, but it was beyond them. The Sea-Lark
refused to glide with fairy footsteps down to the river after her long
rest ashore. Tony meanwhile was heaving at the side of the boat to
loosen her keel in the sand, but when he saw the joint efforts of the
boys were unequal to the task, he beckoned them to fetch the dory
across.
“She seems to be glued there,” he declared, “but that glue will
have to come unstuck, if it takes us the whole day to do the trick.
Let’s see if all three of us working at the winch can get her to start.”
Tony rolled up his sleeves, put the boys together at one crank, and
applied his own strength to the other.
 “Now, lads,” he said, “give her all you’ve got. Heave!”
There was a back-breaking moment of straining, cracking
muscles.
And then something happened. The Sea-Lark reluctantly began to
move.
Click-click-clickety-click, went the winch.
“Easy, now,” ordered Tony. “Rest a few minutes. She’ll come all
right, and we have plenty of time.”
From that moment the launching of the sloop, though slow, was a
certainty. A dozen times Tony had to make the trip across the river to
adjust the planks and rollers beneath the boat’s keel, but she came
up the slope without mishap.
“My word, she looks big!” Jack exclaimed when he had climbed to
the top and was lumbering along on her side, down to the water’s
edge.
“What did you take her for?—a canoe?” Tony laughed. “She won’t
look as big, though, when she gets into the water. Still, a thirty-foot
sloop is all you two will want to handle in a breeze.”
When their prize was within a foot of the water, Tony went over her
with a calking-iron and mallet, plugging up the worst of the leaky
places with oakum so that she could safely be taken up the river as
far as the boat-yard without danger of sinking on the way. Jack
watched this performance with a critical eye.
“Is she very bad?” he asked with some anxiety.
“Why, no,” replied Tony. “She’s not what you might call seaworthy,
with these seams wide open, but you’re bound to get that. I didn’t
expect to have much trouble with her hull, and I must say that,
considering all things, she’s in pretty fair condition. Just the same, I
guess there’s enough work on her to keep you busy for a week or
so.”
“I don’t care if it takes us all summer! Yes, I do, too,” said Jack. “I
want to get her shipshape in a month or so if possible.”