diff --git a/docs/index.Rmd b/docs/index.Rmd index 0970cd3..66d278c 100644 --- a/docs/index.Rmd +++ b/docs/index.Rmd @@ -14,6 +14,10 @@ editor_options: ```{r knitr_init, echo=FALSE, cache=FALSE} library(knitr) +# need to make sure this is installed +# to compile this document +# pacman::p_load_gh("juba/rmdformats") + ## Global options options(max.print="75") opts_chunk$set(echo=FALSE, @@ -522,7 +526,7 @@ Only copy the `/`:
-**From the website repo** (i.e. the repo that will have the source code), enter the following command, where `theme` corresponds to the link of the corresponding GitHub repo: +**From the local website repo** (i.e. the repo that will have the source code on your local machine), enter the following command, where `theme` corresponds to the link of the corresponding GitHub repo: ```{r, eval=FALSE, echo=TRUE} blogdown::new_site(theme = "gcushen/hugo-academic", theme_example = TRUE) @@ -574,53 +578,249 @@ You should notice that there is now a `Build` button available: ## Step 3: Publish website -config.toml - The configuration file for your website. This file tells Hugo how it should render your site, as well as define its menus, and set various other site-wide parameters. This file will look different for every theme, but they will all contain some basic components. -baseurl set this to the desired URL for your site, in this case baseurl = "https://.github.io/" -title set the title for your new site. Some completely random and objective examples include “Real Leaks, Fake News”, “Gravy Fries and Putin”, and “Kellyanne’s Alternative Factory” -description a brief description or mission of your new site, something like “Democracy Described in Data” or “Hair and Imbalanced” -theme this should list the theme you specified when creating the site -publishDir tell blogdown which directory it should place the rendered site in. This directory will include a copy of everything that gets generated in the public/ directory of your site’s root directory. To use the two repository method described above, set this to publishDir = "../.github.io". Adjust this path to where ever you keep your .github.io repository +
+As explained in [this post](https://tclavelle.github.io/blog/blogdown_github/): +> User pages on GitHub require all site content (and only site content) to be on the master branch. This is problematic for blogdown sites because when Hugo builds your website it places the site content in a new folder called public/. Thus, your blog’s source and site content will be on the master branch and GitHub will be unable to render your site. -publishDir is relative to current directory. so can use ../ , or use full path "/home/sahir/git_repositories/cssc2018.github.io" -but dont use "~/git_repositories/cssc2018.github.io" +There are [two ways](https://tclavelle.github.io/blog/blogdown_github/) to get around this problem. In this tutorial we go with the option that requires the least amount of `Git` knowledge (the two repository method). +As explained in Step 2, we create two repositories: one for the source code of the website and another for the static `HTML` files. The figure below demonstrates that you should have the following two folders on your local machine: ![](assets/img/blogdown/publish/publish001.png) + +************* + +
+ +Head over the the `website` source repo on your local machine and open the +`config.toml` file. This is the configuration file for your website. This file tells Hugo how it should render your site, as well as define its menus, and set various other site-wide parameters. This file will look different for every theme, but they will all contain some basic components. The two most important ones for now are: + +1. `baseurl`: set this to the URL for your site `https://.github.io/` +2. `publishDir`: this tells blogdown which directory it should place the static files in. This directory will include a copy of everything that gets generated in the public/ directory of your site's root directory. Set this to `publishDir = "../.github.io"`. + +Adjust this path to where ever you keep your `.github.io` repository. `publishDir` is relative to current directory. So you can use `../`, or use the full path (e.g. `"/home/sahir/git_repositories/cssc2018.github.io"`) but dont use `"~/git_repositories/cssc2018.github.io"`. + +Feel free to change the other self-explanotory options such as `title`, `name`, `role`, `organization` ect. + ![](assets/img/blogdown/publish/publish002.png) -![](assets/img/blogdown/publish/publish003.png) + +************* + +
+ +Notice that your local folder of the `.github.io` doesn't have many files in it prior to building the website: + ![](assets/img/blogdown/publish/publish004.png) + +************* + +
+ +Click on the `Build Website` button to render the site: + +![](assets/img/blogdown/publish/publish003.png) + + +************* + +
+ +You should see a window of the rendered website (sometimes it shows up in the pop up windown and sometimes it doesn't, but don't worry just yet): + ![](assets/img/blogdown/publish/publish005.png) + +************* + +
+ +If you have properly setup the `publishDir` in the `config.toml` file, you should now see many files in your local `.github.io` folder: + ![](assets/img/blogdown/publish/publish006.png) + +************* + +
+ +GitHub defaults to using [Jekyll](https://jekyllrb.com/) with website content, and this needs to be disabled since blogdown sites are built with Hugo. To disable this, include an empty file named `.nojekyll` in your GitHub repo `.github.io`. You can do so within RStudio by opening a text file: + ![](assets/img/blogdown/publish/publish007.png) + +************* + +
+ +Click on the save button: + ![](assets/img/blogdown/publish/publish008.png) + +************* + +
+ +Save as `.nojekyll` in the root of your local repo: + ![](assets/img/blogdown/publish/publish009.png) + +************* + +
+ +You might not notice the `.nojekyll` file show up in RStudio, but you should be able to see it in you file explorer: + ![](assets/img/blogdown/publish/publish010.png) + +************* + +
+ +We now need to commit these changes and push them to GitHub. Check all the boxes in the `Staged` column: + ![](assets/img/blogdown/publish/publish011.png) + +************* + +
+ +Click on `commit`: + ![](assets/img/blogdown/publish/publish012.png) + +************* + +
+ +Enter a commit message and click on `Commit`: + ![](assets/img/blogdown/publish/publish013.png) -![](assets/img/blogdown/publish/publish014.png) -![](assets/img/blogdown/publish/publish015.png) + +************* + +
+ + +If everything worked, you should see a window like this: + ![](assets/img/blogdown/publish/publish016.png) + +************* + +
+ + +Click on `Push` which will then prompt you for your username and password: + ![](assets/img/blogdown/publish/publish017.png) + +************* + +
+ + +![](assets/img/blogdown/publish/publish014.png) + +************* + +
+ + +![](assets/img/blogdown/publish/publish015.png) + +************* + +
+ + + + + +If everything worked, you should see a window like this: + + ![](assets/img/blogdown/publish/publish018.png) + +************* + +
+ + +Head over to the remote repo. You should see your most recent commit message. Click on `Settings`: + ![](assets/img/blogdown/publish/publish019.png) + +************* + +
+ +Scroll down. You should see that your site is now published. Be sure to check the `Enforce HTTPS` box. Read more about `HTTPS` [here](https://https.cio.gov/everything/). GitHub now support `HTTPS` for custom domain names and `.github.io` subdomains. + ![](assets/img/blogdown/publish/publish020.png) + +************* + +
+ +Head over to `https://.github.io` and see your website in action! + ![](assets/img/blogdown/publish/publish021.png) + +************* + +
+ +Be sure to also commit and push the changes to the source code of your website: + ![](assets/img/blogdown/publish/publish022.png) + +************* + +
+ ![](assets/img/blogdown/publish/publish023.png) + +************* + +
+ ![](assets/img/blogdown/publish/publish024.png) + +************* + +
+ ![](assets/img/blogdown/publish/publish025.png) +************* + +
## Step 4: Create blog post +
+ +The next step is to create a blog post. This step is made easy by the RStudio `Addins` menu: ![](assets/img/blogdown/post/post001.png) + +************* + +
+ +Fill in the boxes. Be sure to check the `.Rmd` format: + ![](assets/img/blogdown/post/post002.png) + + +************* + +
+ +You should see the following `.Rmd` file in your RStudio: + ![](assets/img/blogdown/post/post003.png) + Copy the following into the `.Rmd` file: ```` @@ -665,6 +865,8 @@ x_{FIS} = \left(\prod_{g=1}^{6} SS_{i,g}^{C_{i,g}}\right)^\frac{1}{\sum{C_{i,g} $$ ```` +Save the file. Click on `Build Website` and repeat the steps above (commit and push the changes of both the `website` repo and the `.github.io` repo). + # Part 3: Project pages {.tabset .tabset-fade .tabset-pills} diff --git a/docs/index.html b/docs/index.html index 907aaf5..f980adb 100644 --- a/docs/index.html +++ b/docs/index.html @@ -14,65 +14,933 @@ CSSC 2018 Workshop - - - + + + - - - - - - - - - - - - - + + + + + + + + + + + + + @@ -143,9 +1011,9 @@

Requirements

  • Run the following commands in R for required packages:


    • -
    install.packages("pacman")
-pacman::p_load(knitr, rmarkdown, bookdown, data.table, sjPlot, car)
-pacman::p_load_gh('rstudio/blogdown')
    +


    @@ -182,30 +1050,21 @@

    Standing on the shoulder of giants



    -
    - - -
    +

    Reproducible Research

    What is needed for Reproducible Research (RR) ?


    -
    - - -
    +


    Why RR?


    -
    - - -
    +


    @@ -214,7 +1073,7 @@

    Division of Labor

    Focus on the stats, code, interpretation. Leave everything else (filling in tables, inserting plots, formatting) to the typesetter.


    -

    +

    Pictured above is Adam Smith, author of The Wealth of Nations (1776), in which he conceptualizes the notion of the division of labour.

    @@ -227,10 +1086,7 @@

    Markdown

    Markdown is to HTML what LaTeX is to TeX

    Markdown was initially created by John Gruber as a simple way for non-programming types to write in an easy-to-read format that could be converted directly into HTML.

    -
    - - -
    +


    See the Markdown cheatsheet for syntax details.

    Note: All HTML is valid Markdown. If you’re stuck not able to format your content how you would like you can always use plain HTML instead of Markdown (e.g. use <br> for line breaks).

    @@ -240,10 +1096,7 @@

    Markdown

    R Markdown = R + Markdown

    R Markdown combines the computing power of R with the simplicity of Mardown syntax to generate high quality reproducible reports in various formats.

    -
    - - -
    +

    See the R Markdown cheatsheet for syntax details.

    @@ -251,52 +1104,31 @@

    R Markdown = R + Markdown

    Quick Start

    We first start with a minimal, complete, and verifiable example (MCVE) to ensure you have all the correct dependencies and updated versions of software installed. In Rstudio, create a new R Markdown document:

    -
    - - -
    +


    Select Document and ensure that the default output format is HTML. Enter a title if you wish, but you can change this later. Click on OK:

    -
    - - -
    +


    A default skeleton of R Markdown code is included everytime you create a new R Markdown document within RStudio. The important pieces of the document are highlited in the figure below. The YAML header is very similar to the header in LaTeX; it contains all the options for the document. The two mandatory pieces in the YAML are a title and the output format. See here for further customizations.

    -
    - - -
    +


    Leave the content as is and click on the knit button:

    -
    - - -
    +


    This will prompt you to save the file:

    -
    - - -
    +


    An RStudio window of the compiled HTML file should appear

    -
    - - -
    +


    The following figure shows exactly what happens when you press the Knit button. The .Rmd file is first converted into a markdown (.md) file, which is subsequently converted by a tool called pandoc into the format specified by output: in the YAML:

    -
    - - -
    +


    @@ -304,28 +1136,19 @@

    Quick Start

    Remarks

    1. How to choose between LaTeX and Markdown ?

    -
    - - -
    +


    2. Rule of thumb

    -
    - - -
    +


    3. Replicability

    -
    - - -
    +




    @@ -343,240 +1166,259 @@

    Introduction

    Step 1: Create 2 git repos

    We first need to create two GitHub repositories (abbreviated as repo). One will hold the source code for your website, and the other will host the compiled HTML files which make up your website (these are often referred to as static files). Head over to your GitHub account online and create a new repository:

    -
    - - -
    +


    Give it a name. It can be anything you want such as website, website_source, source (just pick a name that will remind you that this repository contains the source files of your website). In the screenshots below I used website throughout. Check the box to initialize the repository with a README and then click on Create repository:

    -
    - - -
    +


    You should now see the homepage of your repository. Note the URL for the repository is given by https://github.com/<user-name>/<repo-name>. This online version of this repo is called the remote.

    -
    - - -
    +


    Click on the Clone or download green button and copy the URL to your clipboard:

    -
    - - -
    +


    We now want a local copy of the website repo so that we can start creating content to put on our website. Head over to RStudio and go to File --> New Project..:

    -
    - - -
    +


    Select Version Control:

    -
    - - -
    +


    Then select Git:

    -
    - - -
    +


    Paste the repository URL that you copied from your remote GitHub repo. Enter a project directory name (I call it the same as the repo name), and if you want, copy the files of the remote repo to a specific subdirectory:

    -
    - - -
    +


    You will notice that a .Rproj file was created and a .gitignore file was created. Let’s first test to see if our connection from the local repo to the remote repo is working. We first check the boxes next to each file and click on commit:

    -
    - - -
    +


    Enter a commit message and click on Commit:

    -
    - - -
    +


    If everything went ok, you should see a window like this:

    -
    - - -
    +


    Next we want to Push these local changes to the remote. Click on the Push button:

    -
    - - -
    +


    This will prompt you to enter your GitHub username:

    -
    - - -
    +


    … and password:

    -
    - - -
    +


    If everything worked smoothly, you should see a window like this:

    -
    - - -
    +


    Head over to the webpage for your GitHub repo (refresh the page if necessary) and you should see you commit message, as well as a .gitignore file and a .Rproj file.

    -
    - - -
    +


    We now need to repeat the exact same steps as before to create the second repo which will host the static files for your website. Create a local copy, though it is not yet necessary to push your changes to the remote as this will be done in a later step.

    Note: the name of this repo must be <user-name>.github.io.

    -
    - - -
    +


    -
    - - -
    +


    -
    - - -
    +


    -
    - - -
    +


    -
    - - -
    +


    -
    - - -
    +


    -
    - - -
    +

    Step 2: Install Hugo


    Note for Mac Users: the first time you install Hugo, you might need to install homebrew.

    -
    library(blogdown)
-blogdown::install_hugo(force = TRUE)
-blogdown::hugo_version()
    +


    Choose a theme

    Choose a theme from https://themes.gohugo.io/ and find the link to the theme’s GitHub repository. In this example we choose the Academic theme.

    -
    - - -
    +

    Click on the Homepage button to get the link to the theme’s GitHub repo:

    -
    - - -
    +

    Only copy the <user-name>/<repo-name>:

    -
    - - -
    +


    -

    From the website repo (i.e. the repo that will have the source code), enter the following command, where theme corresponds to the link of the corresponding GitHub repo:

    -
    blogdown::new_site(theme = "gcushen/hugo-academic", theme_example = TRUE)
    -
    - - -
    +

    From the local website repo (i.e. the repo that will have the source code on your local machine), enter the following command, where theme corresponds to the link of the corresponding GitHub repo:

    + +


    Click on the button encircled in red which should spawn a web page in your browser:

    -
    - - -
    +


    Take a look at your website. It’s only a local copy for now, and we still need to personalize it before publishing it.

    -
    - - -
    +


    After this is complete, you should quit and then reopen the project. Upon reopening, RStudio will recognize the project as a website.

    -
    - - -
    +


    -
    - - -
    +


    You should notice that there is now a Build button available:

    -
    - - -
    +

    Step 3: Publish website

    -

    config.toml - The configuration file for your website. This file tells Hugo how it should render your site, as well as define its menus, and set various other site-wide parameters. This file will look different for every theme, but they will all contain some basic components. baseurl set this to the desired URL for your site, in this case baseurl = “https://.github.io/” title set the title for your new site. Some completely random and objective examples include “Real Leaks, Fake News”, “Gravy Fries and Putin”, and “Kellyanne’s Alternative Factory” description a brief description or mission of your new site, something like “Democracy Described in Data” or “Hair and Imbalanced” theme this should list the theme you specified when creating the site publishDir tell blogdown which directory it should place the rendered site in. This directory will include a copy of everything that gets generated in the public/ directory of your site’s root directory. To use the two repository method described above, set this to publishDir = “../.github.io”. Adjust this path to where ever you keep your .github.io repository

    -

    publishDir is relative to current directory. so can use ../ , or use full path “/home/sahir/git_repositories/cssc2018.github.io” but dont use “~/git_repositories/cssc2018.github.io”

    -

    +


    +

    As explained in this post:

    +
    +

    User pages on GitHub require all site content (and only site content) to be on the master branch. This is problematic for blogdown sites because when Hugo builds your website it places the site content in a new folder called public/. Thus, your blog’s source and site content will be on the master branch and GitHub will be unable to render your site.

    +
    +

    There are two ways to get around this problem. In this tutorial we go with the option that requires the least amount of Git knowledge (the two repository method).

    +

    As explained in Step 2, we create two repositories: one for the source code of the website and another for the static HTML files. The figure below demonstrates that you should have the following two folders on your local machine:

    +

    +
    +


    +

    Head over the the website source repo on your local machine and open the config.toml file. This is the configuration file for your website. This file tells Hugo how it should render your site, as well as define its menus, and set various other site-wide parameters. This file will look different for every theme, but they will all contain some basic components. The two most important ones for now are:

    +
      +
    1. baseurl: set this to the URL for your site https://<user-name>.github.io/
      +
      2. +
    2. publishDir: this tells blogdown which directory it should place the static files in. This directory will include a copy of everything that gets generated in the public/ directory of your site’s root directory. Set this to publishDir = "../<user-name>.github.io".
      3. +
    +

    Adjust this path to where ever you keep your <user-name>.github.io repository. publishDir is relative to current directory. So you can use ../, or use the full path (e.g. "/home/sahir/git_repositories/cssc2018.github.io") but dont use "~/git_repositories/cssc2018.github.io".

    +

    Feel free to change the other self-explanotory options such as title, name, role, organization ect.

    +

    +
    +


    +

    Notice that your local folder of the <user-name>.github.io doesn’t have many files in it prior to building the website:

    +

    +
    +


    +

    Click on the Build Website button to render the site:

    +

    +
    +


    +

    You should see a window of the rendered website (sometimes it shows up in the pop up windown and sometimes it doesn’t, but don’t worry just yet):

    +

    +
    +


    +

    If you have properly setup the publishDir in the config.toml file, you should now see many files in your local <user-name>.github.io folder:

    +

    +
    +


    +

    GitHub defaults to using Jekyll with website content, and this needs to be disabled since blogdown sites are built with Hugo. To disable this, include an empty file named .nojekyll in your GitHub repo <user-name>.github.io. You can do so within RStudio by opening a text file:

    +

    +
    +


    +

    Click on the save button:

    +

    +
    +


    +

    Save as .nojekyll in the root of your local repo:

    +

    +
    +


    +

    You might not notice the .nojekyll file show up in RStudio, but you should be able to see it in you file explorer:

    +

    +
    +


    +

    We now need to commit these changes and push them to GitHub. Check all the boxes in the Staged column:

    +

    +
    +


    +

    Click on commit:

    +

    +
    +


    +

    Enter a commit message and click on Commit:

    +

    +
    +


    +

    If everything worked, you should see a window like this:

    +

    +
    +


    +

    Click on Push which will then prompt you for your username and password:

    +

    +
    +


    +

    +
    +


    +

    +
    +


    +

    If everything worked, you should see a window like this:

    +

    +
    +


    +

    Head over to the remote repo. You should see your most recent commit message. Click on Settings:

    +

    +
    +


    +

    Scroll down. You should see that your site is now published. Be sure to check the Enforce HTTPS box. Read more about HTTPS here. GitHub now support HTTPS for custom domain names and <user-name>.github.io subdomains.

    +

    +
    +


    +

    Head over to https://<user-name>.github.io and see your website in action!

    +

    +
    +


    +

    Be sure to also commit and push the changes to the source code of your website:

    +

    +
    +


    +

    +
    +


    +

    +
    +


    +

    +
    +


    Step 4: Create blog post

    -

    +


    +

    The next step is to create a blog post. This step is made easy by the RStudio Addins menu:

    +

    +
    +


    +

    Fill in the boxes. Be sure to check the .Rmd format:

    +

    +
    +


    +

    You should see the following .Rmd file in your RStudio:

    +

    Copy the following into the .Rmd file:

    ```{r setup, include=FALSE}
 knitr::opts_chunk$set(echo = TRUE)
@@ -617,6 +1459,7 @@ 
    Step 4: Create blog post
    
 $$
 x_{FIS} =  \left(\prod_{g=1}^{6} SS_{i,g}^{C_{i,g}}\right)^\frac{1}{\sum{C_{i,g}}}
 $$
    +

    Save the file. Click on Build Website and repeat the steps above (commit and push the changes of both the website repo and the <user-name>.github.io repo).

    @@ -663,10 +1506,7 @@

    blogdown

    Acknowledgements

    -
    - - -
    +

    • Félix-Antoine Fortin (Calcul Québec)