class: center, middle, inverse, title-slide # Programming Tools in Data Science ## Lecture #9: website with R ### Samuel Orso ### 15 November 2021 --- # Website with R * Website is a good way to showcase your work. * RStudio provides a nice set of tools to quickly build a website. --- # Setup * For this class, you will need (at least) the following packages: ```r install.packages(c("pkgdown", "blogdown")) ``` * Check that your package version is up-to-date ```r packageVersion("blogdown") ``` ``` ## [1] '1.5' ``` ```r blogdown::hugo_available() ``` ``` ## [1] TRUE ``` ```r blogdown::hugo_version() ``` ``` ## [1] '0.80.0' ``` --- # pkgdown <img src="images/pkgdown.png" style="height:150px; width:150px; position:absolute; top:7%; right:5%;"/> * It is quick and automated way to create a website around your package. * To build your first website, this is as simple as ```r # Run once to configure your package to use pkgdown usethis::use_pkgdown() # Run to build the website pkgdown::build_site() ``` * It is also a good idea to add a Github action: ```r usethis::use_github_action("pkgdown") ``` * Checkout <https://pkgdown.r-lib.org/> for more details. --- <img src="images/pkgdow_pkgtest.png" width="2273" style="display: block; margin: auto;" /> --- # blogdown <img src="images/blogdown.png" style="height:150px; width:150px; position:absolute; top:7%; right:5%;"/> * [blogdown](https://bookdown.org/yihui/blogdown/) offers a more flexible way to create a website. * It is based on the static site generator [Hugo](https://gohugo.io/). <img src="images/hugo.png" width="600" height="400" style="display: block; margin: auto;" /> --- # Static vs dynamic * **dynamic website generator**: when a user visit a website and a HTTP server generates a HTML file that is sent to the browser to be viewed. * This is resource consuming, and over time HTML pages started to be cached. * **static website generator**: all HTML files are rendered and cached locally (could be a server), before being sent to a HTTP server. * It translates into high performance. --- # Getting started Create a new project selecting `Website using blogdown`. <img src="images/bg_new_project.png" width="400" height="300" style="display: block; margin: auto;" /> --- # Choosing a theme * The choice of a theme is essential: themes have different ways to create content, structures, features and provide more or less user documentation. * A list of themes is at <https://themes.gohugo.io/>. * By default, `blogdown` proposes the simple [hugo-lithium](https://github.com/yihui/hugo-lithium) theme. * [Learn](https://themes.gohugo.io/hugo-theme-learn/): it is a great theme to start with. * [Academic](https://themes.gohugo.io/academic/): this a very complete theme. * [Tranquilpeak](https://themes.gohugo.io/hugo-tranquilpeak-theme/): a beautiful and neat theme for blogging. --- * You need to specify under `Hugo theme:` the `USER_NAME/REPOSITORY_NAME` from the GitHub repository of the theme. * For example, the `Learn` theme is at <https://github.com/matcornic/hugo-theme-learn> so we enter: <img src="images/bg_theme.png" width="400" height="300" style="display: block; margin: auto;" /> --- # Rendering the website * Since Hugo is a static website generator, you can render it live locally. ```r blogdown::serve_site() ``` Or alternatively, use directly the `Rstudio` `Addins`. <img src="images/bg_addins1.png" width="467" style="display: block; margin: auto;" /> --- * It creates the website in the viewer panel. <img src="images/bg_viewer_panel.png" width="2556" style="display: block; margin: auto;" /> * To stop the rendering ```r blogdown::stop_server() ``` --- # Creating content * You need to decide whether you want to create a plain Markdown document (`.md`) or a RMarkdown document (`.Rmd`) as there are noticeable differences. * A good rule of thumb is: always write a post with plain Markdown unless you need to *run* `R` code. --- * The easiest way to create a document is to click on `Addins > Blogdown > New post` which generates a windows through a shiny app. Here is an example: <img src="images/bg_new_post.png" width="400" height="300" style="display: block; margin: auto;" /> --- - *Archetype* is a pre-configured skeleton page. The [Learn](https://learn.netlify.app/en/) theme has two archetypes: chapter or default (see [here](https://learn.netlify.app/en/cont/archetypes/)). - *Format*: there is a third format, `.Rmarkdown`. This format will be compiled to a Markdown document (not HTML) so you keep the files clean, however it does not use Pandoc as the `rmarkdown` package does (see [Blogdown output format](https://bookdown.org/yihui/blogdown/output-format.html) for more details). --- * Alternatively you can simply create a document as usual and then fill the header and the content. For example here with a plain Markdown document ```r --- title: Some title date: 2021-11-15T09:00:00+01:00 weight: 5 description: some description --- ``` * You can find [here](https://gohugo.io/content-management/front-matter/) a complete list of variables * Note that Hugo renders Markdown document using `Goldmark` (click [here](https://gohugo.io/getting-started/configuration-markup) for more info) as opposed to `Pandoc`. --- # Shortcodes > Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video iframe’s) to Markdown content. We think this contradicts the beautiful simplicity of Markdown’s syntax. > > [What a shortcode is](https://gohugo.io/content-management/shortcodes/) --- * The idea of shortcodes is to circumvent some of Markdown's limitations. For example, if you want to embed a Youtube video, say ```r https://www.youtube.com/watch?v=w7Ft2ymGmfc ``` you can simply use the following syntax ```r #{{< youtube w7Ft2ymGmfc >}} ``` * Here is how it looks on the website: <img src="images/bg_yt.png" width="2559" /> * Check this [link](https://gohugo.io/content-management/shortcodes/#use-hugos-built-in-shortcodes) for other Hugo's built-in shortcodes. --- * [Learn](https://learn.netlify.app/en/shortcodes/) theme proposes several shortcodes. For instance, we can add an info notice using ```r #{{% notice info %}} #An information disclaimer #{{% /notice %}} ``` --- # Website structure and content organization * Here is a simplified view of a website organization: ```r my-website/ ├─ my-website.Rproj ├─ config.toml ├─ content/ │ ├─ _index.md │ ├─ post/ │ │ ├─ 2021-11-15-my-first-post.html │ │ ├─ 2021-11-15-my-first-post.Rmd ├─ layouts/ ├─ public/ ├─ static/ │ ├─ images/ │ │ ├─ showcase/ │ │ │ ├─ tat.png ├─ themes/ │ ├─ hugo-theme-learn/ ``` --- - `config.toml` is where you have configuration directives. Some themes such as Academic have `config/` directory. These directives could also be stored in `JSON` or `YAML` syntax. - With `blogdown`, it is recommended to ignore some files by adding to `config.toml` ```r ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"] ``` - The `content/` folder is where you add the content for your website. Hugo follows the logic of this folder to construct the website. The organization between different pages at the same level can be specified using the `weight` variable. Usually a section begins with a `_index.md` file. - The `layouts/` folder contains templates in HTML. If empty, it uses the theme defaults. You need to copy such a file from the theme before modifying it, it is a bad habit to modify files from the `theme/` directory. - `static/` stores all the static content such as CSS, JavaScript, ... This content is served as-is, meaning without modification to the website. For example, the image in `static > images > showcase > tat.png` can be directly accessed at <https://learn.netlify.app/images/showcase/tat.png>. - See this [link](https://gohugo.io/getting-started/directory-structure/) for other directories and further information. --- # Customizing the theme * Customization depends on the theme you pick. * For example, with the [Learn](https://learn.netlify.app/en/) theme, you can easily modify the color variants (see [here](https://learn.netlify.app/en/basics/style-customization/#theme-variant)). * To create your own variant, you have to create a CSS file in `static > css` with your own setup following [this example](https://learn.netlify.app/en/basics/style-customization/#yours-variant). * You have many more options such as Google Analytics, Disqus, Twitter, Google News, etc. See <https://gohugo.io/templates/internal/> for templates. * To add **LaTeX** equations for `.md` file, a solution is to use [MathJax](https://www.mathjax.org) but you will need some tweaks following for example this [blog](https://geoffruddock.com/math-typesetting-in-hugo/). --- # Deployment * Once your website is on a GitHub repository, t is easy, quick and free of charge to publish your website online using for example the service of [Netlify](https://netlify.app/). * See [Blogdown: deployment with netlify](https://bookdown.org/yihui/blogdown/netlify.html) for more details. --- # To go further * More details and examples in the book [An Introduction to Statistical Programming Methods with R](https://smac-group.github.io/ds/section-blogdown-websites-and-blogs-creation.html) * More material and details in [blogdown: Creating Websites with R Markdown](https://bookdown.org/yihui/blogdown/). * Checkout <https://gohugo.io/> --- class: sydney-blue, center, middle # Question ? .pull-down[ <a href="https://ptds.samorso.ch/"> .white[<svg viewBox="0 0 384 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <path d="M369.9 97.9L286 14C277 5 264.8-.1 252.1-.1H48C21.5 0 0 21.5 0 48v416c0 26.5 21.5 48 48 48h288c26.5 0 48-21.5 48-48V131.9c0-12.7-5.1-25-14.1-34zM332.1 128H256V51.9l76.1 76.1zM48 464V48h160v104c0 13.3 10.7 24 24 24h104v288H48z"></path></svg> website] </a> <a href="https://github.com/ptds2021/"> .white[<svg viewBox="0 0 496 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path></svg> GitHub] </a> ]