-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathindex.html
More file actions
510 lines (369 loc) · 16.4 KB
/
index.html
File metadata and controls
510 lines (369 loc) · 16.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
<!DOCTYPE html>
<html lang="" xml:lang="">
<head>
<title>Authoring websites, documents, and more with Markdown</title>
<meta charset="utf-8" />
<meta name="author" content="Alexa Fredston" />
<meta name="date" content="2022-09-14" />
<script src="index_files/header-attrs/header-attrs.js"></script>
<link rel="stylesheet" href="xaringan-themer.css" type="text/css" />
<link rel="stylesheet" href="custom.css" type="text/css" />
</head>
<body>
<textarea id="source">
class: center, middle, inverse, title-slide
# Authoring websites, documents, and more with Markdown
## SORTEE Webinar
### Alexa Fredston
### September 14, 2022
---
class: inverse center middle
# Welcome!
--
I'm glad you're here.
---
# Why am I here?
### To learn (or learn more about) markdown
A beautiful, flexible language for formatting plain text — into a website, a PDF, a slide deck (like this one!), a book, a report, or just legible code.
---
# Who is this for?
Anyone who wants to improve the way that you format and share your work — whatever that means to you.
---
# Alexa Fredston
.pull-left[
- Postdoctoral associate, Rutgers University, New Jersey, USA
- Quantitative marine ecologist
- Treasurer of SORTEE
- Inclusive teaching of coding, etc.
- afredston on [Twitter](https://twitter.com/AFredston) and [GitHub](https://github.com/afredston)
]
.pull-right[
]
---
# Outline
1. Introduction
1. Documents
1. Code
1. Slides
---
# Tell me about you
[https://pollev.com/alexafredston045](https://pollev.com/alexafredston045)
---
# What is Markdown?
- A language for formatting text with a plain text editor
- Designed to be readable in its raw form
- Similar to LaTeX, but more “lightweight” and better integrated with analyses
- Language agnostic; .md files can be opened by most code editors
- We will be editing .Rmd files from RStudio today, but that doesn't actually require any R knowledge!
---
# What does this have to do with open science?
Using Markdown to generate publications, reports, websites, etc. will:
* Make dynamically updating them with new results easier
* Reduce errors from manually entering results
* Create new venues for science communication
Using Markdown to organize your code will:
* Allow you to organize and annotate your analyses
* Make it easier for others to tell what you did, aiding reproducibility
---
# Cool Markdown examples
An entire scientific manuscript [marine protected areas](https://github.com/DanOvando/population-effects-of-mpas) or [matrix population models](https://github.com/BruceKendall/MPM-errors)
A [dynamically updating CV](http://nickstrayer.me/datadrivencv/)
A [RMarkdown tutorial ... written in RMarkdown](https://allisonhorst.github.io/udm-rmarkdown/) 🤯
A [website collaboratively authored in RMarkdown](https://thefaylab.github.io/lab-manual)
An [entire course](https://damariszurell.github.io/CLEWS-EDB/)
---
# Today's learning objectives
By the end of this tutorial, I expect that you will be able to:
* Understand the different parts of a Markdown file
* Recognize how the formatting of raw text in Markdown translates to the aesthetics of an output file
* Generate basic PDFs and slides with code output
* Understand how Markdown can facilitate open science goals
* Know where to go to get help or learn more
---
# The architecture of Markdown
### 1. YAML header
### 2. Markdown text
### 3. Code chunks
---
## 1. YAML header
.pull-left[
- Its own language (not markdown!)
- New markdown files in R include it by default
- Modify it to change some global document options (custom formatting)
- Mostly going to ignore it today
]
.pull-right[
]
---
## 2. Markdown text
.pull-left[
rmarkdown
]
.pull-right[
html
]
---
## 3. Code chunks
```r
ggplot(aes(x=body_mass_g, y=flipper_length_mm), data=penguins) +
geom_point() +
theme_xaringan() + labs(x="Body mass, mm", y="Flipper length, g")
```
<img src="index_files/figure-html/demo-intro-1.png" width="100%" />
---
class: inverse center middle
# Let's get started
---
# Setup
Software you will need:
- RStudio
Packages you will need installed:
- `rmarkdown`
- `palmerpenguins`
- `tidyverse`
- `leaflet` (not crucial if you don't want to install it)
Run `install.packages("packagename")` for any of these that you need to.
Take five minutes to do all this, and let me know if you have issues.
Throughout this workshop, you can get help by raising your hand or using the chat.
---
# Get the code!
This unavoidably involves a little bit of exposure to GitHub.
1. Go to [https://github.com/afredston/markdown-sortee](https://github.com/afredston/markdown-sortee) (I will also put this link in the chat)
1. Click the green "Code ▾" button and then download ZIP (unless you are comfortable enough with GitHub to clone the repository; in that case, go for it)
1. Open RStudio and then navigate to the contents of the ZIP
---
class: inverse center middle
# Documents
---
# Authoring documents
1. Open `document.Rmd` in RStudio
1. Click "knit" at the top of RStudio (if you don't see it, be sure rmarkdown is installed, and relaunch RStudio)
1. Marvel at the glory of what you've created
1. Look line by line between the .pdf and the .Rmd documents. (The PDF will also appear in the `markdown-sortee` folder that `document.Rmd` is in, if you have trouble finding it.)
1. Change something in the document! Here are some ideas:
+ Edit the title, author, or date
+ Write some new text, and try formatting it (make it bold, a header, a bullet...)
+ Change the embedded photo
1. If you're familiar with these Markdown basics, try something more advanced (and any of you can do this with Google's help!)
+ Change the color of some text
+ Insert a table
+ Add an in-text reference to the photo
+ Try aligning text to the center or right, or the image to the left or right
I'll give you five minutes to explore this and troubleshoot as needed. Then we'll check in, and hopefully some of you will share what you discovered. Then I'll bring the document up on my computer and give you a tour.
---
# Authoring documents
One fairly new feature (and one reason we're using RStudio today!) is their new [visual markdown editor](https://rstudio.github.io/visual-markdown-editing/). It's basically an ultra powerful hybrid of Markdown and Microsoft Word. But be warned, it's a little buggy if you frequently switch editing modes.
People write whole books in Markdown, and this may make that seem a little more achievable. For example, the new visual editor allows [easy citation management with a Zotero library](https://www.rstudio.com/blog/rstudio-1-4-preview-citations/) (if we have time, I'll show you this on my computer).
---
# Authoring documents
### What's the catch?
Much like the transition from Excel to code, some simple things are much faster in Markdown (changing the font throughout your document), and others are much more annoying (sizing and aligning images).
In my experience, Markdown is worth it for scientists because of its enormous advantage over a word processor: **code integration**.
---
class: inverse center middle
# Code
---
# Why code in Markdown?
* Can render text and code outputs in the same document
* Can annotate and organize your code more legibly
* Don't actually need to do anything different to your code
* Can use multiple programming languages in the same script (although I generally suggest [Jupyter](https://jupyter.org/) instead for this)
```
## [1] "awk" "bash" "coffee" "gawk" "groovy" "haskell"
## [7] "lein" "mysql" "node" "octave" "perl" "psql"
## [13] "Rscript" "ruby" "sas" "scala" "sed" "sh"
## [19] "stata" "zsh" "highlight" "Rcpp" "tikz" "dot"
## [25] "c" "cc" "fortran" "fortran95" "asy" "cat"
## [31] "asis" "stan" "block" "block2" "js" "css"
## [37] "sql" "go" "python" "julia" "sass" "scss"
## [43] "R" "bslib"
```
---
# Writing code with RMarkdown
1. Open `code.Rmd`.
1. Read through the document and run the chunks one at a time.
1. Try any of the following:
- Create a new chunk that generates a different figure
- Add some chunk options to the header to control how the figure is printed; for example, `fig.cap="Caption here"` or `fig.width=5` or `results="hide"`. See [https://yihui.org/knitr/options/](https://yihui.org/knitr/options/) for details
- Put in new coordinates to the map chunk to map someplace you know
- Click "knit" at the top of the page and see what happens!
- If there is anything you want formatted differently in the html file output, try to fix it (hint: you might start with the chunk options for the first chunk, `setup`)
1. If R isn't your language, feel free to explore these same options in Jupyter.
---
class: inverse center middle
# Slides
---
# Creating presentations with RMarkdown
The principles are the same as you've learned — text formatted in Markdown, code chunks, embedded links / images / references / etc.
The only big difference to remember is that slides are split from one another by:
`---`
Creating presentations in RMarkdown will often force you to deal with extra formatting challenges (image sizes, etc)
The best way to learn is just to try it!
---
# Creating presentations with RMarkdown
This is a great time to learn how to create *new* .md or .Rmd files — up to now, you've been using ones I created. Take a few minutes to try the following.
To create a new `.Rmd` from RStudio, click file -> new file -> RMarkdown and click "Presentation". I suggest you use ioslides or Slidy, unless you know you have TeX installed, in which case beamer works too.
Now... you have all the skills to create this presentation! Try:
* Adding a title slide (use headers)
* Inserting a plot
* Making lists
Try knitting it along the way to see how it looks.
Feel free to copy-paste code from `code.Rmd` and `document.Rmd`. Save this new file as `presentation.Rmd`.
---
# Xaringan
I make my slides using [xaringan](https://bookdown.org/yihui/rmarkdown/xaringan.html), which I encourage you to install and explore. It's easy to make beautiful and unique presentations with minimal coding, especially with the help of [xaringanthemer](https://pkg.garrickadenbuie.com/xaringanthemer/).
It has lots of other cool features — for example, xaringan's "infinite moon reader" (`xaringan::inf_mr()`) lets you view the rendered output as you type.
---
# We're almost done!
## Any questions before I wrap up?
---
# A horizon scan: Quarto
[Quarto](https://quarto.org/) is a sequel to RMarkdown developed by RStudio.
While they are still maintaining RMarkdown, a lot of new development will probably happen in Quarto.
The differences between RMarkdown and Quarto are not huge for R users ([overview here](https://yihui.org/en/2022/04/quarto-r-markdown/)), and there is much more RMarkdown documentation available, which is why I taught it today.
I encourage you to keep tabs on Quarto's development and try it out, especially if you're not an R user.
---
# Thank you for your participation
.pull-left[
### My sources and inspiration
- [Yihui Xie's extraordinary RMarkdown guide](https://bookdown.org/yihui/rmarkdown/)
- [Allison Horst's rmarkdown tutorial](https://allisonhorst.github.io/udm-rmarkdown/)
### How to contact me
- Email fredston@rutgers.edu
- afredston on [Twitter](https://twitter.com/AFredston) and [GitHub](https://github.com/afredston)
- [alexafredston.com](https://www.alexafredston.com/)
]
.pull-right[
### Additional resources
- [Yihui Xie's hilarious, whirlwind video tour of RMarkdown](https://www.youtube.com/watch?v=qLEkUjxk7e8)
- [A Xaringan slides tutorial video](https://presentable-user2021.netlify.app/)
- [Alison Hill and Desirée De Leon's overview of publishing .Rmds to websites](https://rstudio-education.github.io/sharing-short-notice/#1)
- [Alison Hill's advanced RMarkdown workshop](https://www.apreshill.com/project/advanced-r-markdown/)
]
---
</textarea>
<style data-target="print-only">@media screen {.remark-slide-container{display:block;}.remark-slide-scaler{box-shadow:none;}}</style>
<script src="https://remarkjs.com/downloads/remark-latest.min.js"></script>
<script>var slideshow = remark.create({
"slideNumberFormat": "%current%",
"highlightStyle": "github",
"highlightLines": true,
"ratio": "16:10",
"countIncrementalSlides": true
});
if (window.HTMLWidgets) slideshow.on('afterShowSlide', function (slide) {
window.dispatchEvent(new Event('resize'));
});
(function(d) {
var s = d.createElement("style"), r = d.querySelector(".remark-slide-scaler");
if (!r) return;
s.type = "text/css"; s.innerHTML = "@page {size: " + r.style.width + " " + r.style.height +"; }";
d.head.appendChild(s);
})(document);
(function(d) {
var el = d.getElementsByClassName("remark-slides-area");
if (!el) return;
var slide, slides = slideshow.getSlides(), els = el[0].children;
for (var i = 1; i < slides.length; i++) {
slide = slides[i];
if (slide.properties.continued === "true" || slide.properties.count === "false") {
els[i - 1].className += ' has-continuation';
}
}
var s = d.createElement("style");
s.type = "text/css"; s.innerHTML = "@media print { .has-continuation { display: none; } }";
d.head.appendChild(s);
})(document);
// delete the temporary CSS (for displaying all slides initially) when the user
// starts to view slides
(function() {
var deleted = false;
slideshow.on('beforeShowSlide', function(slide) {
if (deleted) return;
var sheets = document.styleSheets, node;
for (var i = 0; i < sheets.length; i++) {
node = sheets[i].ownerNode;
if (node.dataset["target"] !== "print-only") continue;
node.parentNode.removeChild(node);
}
deleted = true;
});
})();
(function() {
"use strict"
// Replace <script> tags in slides area to make them executable
var scripts = document.querySelectorAll(
'.remark-slides-area .remark-slide-container script'
);
if (!scripts.length) return;
for (var i = 0; i < scripts.length; i++) {
var s = document.createElement('script');
var code = document.createTextNode(scripts[i].textContent);
s.appendChild(code);
var scriptAttrs = scripts[i].attributes;
for (var j = 0; j < scriptAttrs.length; j++) {
s.setAttribute(scriptAttrs[j].name, scriptAttrs[j].value);
}
scripts[i].parentElement.replaceChild(s, scripts[i]);
}
})();
(function() {
var links = document.getElementsByTagName('a');
for (var i = 0; i < links.length; i++) {
if (/^(https?:)?\/\//.test(links[i].getAttribute('href'))) {
links[i].target = '_blank';
}
}
})();
// adds .remark-code-has-line-highlighted class to <pre> parent elements
// of code chunks containing highlighted lines with class .remark-code-line-highlighted
(function(d) {
const hlines = d.querySelectorAll('.remark-code-line-highlighted');
const preParents = [];
const findPreParent = function(line, p = 0) {
if (p > 1) return null; // traverse up no further than grandparent
const el = line.parentElement;
return el.tagName === "PRE" ? el : findPreParent(el, ++p);
};
for (let line of hlines) {
let pre = findPreParent(line);
if (pre && !preParents.includes(pre)) preParents.push(pre);
}
preParents.forEach(p => p.classList.add("remark-code-has-line-highlighted"));
})(document);</script>
<script>
slideshow._releaseMath = function(el) {
var i, text, code, codes = el.getElementsByTagName('code');
for (i = 0; i < codes.length;) {
code = codes[i];
if (code.parentNode.tagName !== 'PRE' && code.childElementCount === 0) {
text = code.textContent;
if (/^\\\((.|\s)+\\\)$/.test(text) || /^\\\[(.|\s)+\\\]$/.test(text) ||
/^\$\$(.|\s)+\$\$$/.test(text) ||
/^\\begin\{([^}]+)\}(.|\s)+\\end\{[^}]+\}$/.test(text)) {
code.outerHTML = code.innerHTML; // remove <code></code>
continue;
}
}
i++;
}
};
slideshow._releaseMath(document);
</script>
<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
(function () {
var script = document.createElement('script');
script.type = 'text/javascript';
script.src = 'https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-MML-AM_CHTML';
if (location.protocol !== 'file:' && /^https?:/.test(script.src))
script.src = script.src.replace(/^https?:/, '');
document.getElementsByTagName('head')[0].appendChild(script);
})();
</script>
</body>
</html>