I Publish, therefore I Am

Abstract

Putting it all out there on the web

“Most institutions demand unqualified faith; but the institution of science makes skepticism a virtue.”

— Robert King Merton, sociologist (4 Jul 1910-2003)

1 Setting up Git and GitHub

1. Windows: Head off https://gitforwindows.org and download and install the git app.

2. MacOS: In a terminal type: xcode-select --install. This will also install git.

3. Head off to https://github.com and register for an account. Make a note of your emailID and the password used.

4. Setup 2FA Authentication for GitHub based on instructions here: https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa

2 Linking RStudio and GitHub (One Time Only)

1. In RStudio, in your console:

   • install.packages(usethis)
   • library(usethis)
   • usethis::use_git_config(user.name = "Your Name", user.email = "Your Email ID used on GitHub")

2. Generate a Personal Access Token(PAT) (One Time Only, usually)

   • usethis::create_github_token()
     This will open a browser window and ask you to log in to GitHub. In the popup window, give your token a logical name you can remember(e.g. “For my Mac”), and remember why you created it. Check the scopes of the PAT; the defaults are OK. Make sure selecting repo, user, and workflow are checked. Save the PAT in your password manager. Default Expiry is 30days; we can set the PAT to not expire too. (I have.)

3. Let RStudio have your PAT (One Time Only, usually). Once more, in your console:

   • install.packages("gitcreds")
   • library(gitcreds)
   • gitcreds::gitcreds_set() and paste the PAT when asked.

4. Check if all is OK using one or more of:

   • usethis::gh_token_help()
   • usethis::git_sitrep()
   • gh::gh_whoami(), after install.packages("gh") and library(gh)

5. Check in RStudio if has automatically detected your Git installation.

   • Tools -> Global Options -> Git/SVN

Figure 1: RStudio Project Options Window

The Git Executable field should be like:

• Windows: C:/Program Files/Git/bin/git.exe.
• MacOS:/usr/bin/git

5. Let RStudio know which project branch to commit/push to GitHub. (Default is “main”)

   • usethis::git_default_branch_configure()

3 Creating your Blog Project in RStudio (One Time Only)

In the upper right corner of RStudio, click on:

Project -> New Project -> New Directory -> Quarto Blog

Figure 2: New Quarto Blog Project

Name your Blog, browse to where you want the Blog Project Folder (default is fine). Check the Create a git repository. Click Create Project.

RStudio will restart with a new Blog Project. The Files pane should like this:

Figure 3: Quarto Blog Contents

The posts folder contains dummy blog posts, which you can retain for now and delete once your own content has matured.

4 Making your Blog ready to publish (Now, and every time you have new content)

1. Render all Posts:In your Terminal:

   • quarto render
     This will render all posts and prepare _site and _freeze folders in your Files tab. Check these.

2. Preview all Posts:In your Terminal:

   • quarto preview
     This will pop up your browser and show you a preview of your Blog website. Check the look and feel, the typos.

5 Pushing to GitHub for the First Time

1. “Commit” all files: In your Console:

   • usethis::use_git()
     This will throw up a funky set of messages asking if you are ready to commit all files to push to Github. Choose the appropriate reply and enter.

2. Push to New Github Repo: In your Console:

   • usethis::use_github()
     This will create your new repository on Github and push all the committed files there. Your browser will open in Github and show you the contents of your new Blog repository.

NoteCan’t use this again?

As far as I know, this process, though simple, can only be used at start up time. Can’t use this every time you have new content. For that, use the Git pane in RStudio, or a GUI git client such as Gitkraken (recommended).

6 Connecting to Netlify

1. Head off to https://www.netlify.com. Log in there with Github.

2. Click Add new site -> Import from existing project

Figure 4: Netlify Window

3. Choose Github, then point to your Blog Github repo.

4. Give your Blog site a name: something-idiotic.netlify.app. Check Availability. (Note: netlify.app at the end is not removable, if you want free web-hosting at netlify)

5. Ensure that the branch says main, and that the Publish directory says _site.

6. Hit Deploy. Netlify will ta ke a few minutes and then say the site is deployed. Click on the URL.

7. There!

7 Adding Content and Updating

1. Create a new folder inside your posts folder. Name it something like new-post-todays-date. Hyphens only, no underscores.

2. Create a new Quarto Document: File -> New-File -> New Quarto Document. Save it as index.qmd inside your just-created new-post-todays-date folder.

3. Edit / Write up your index.qmd Post. Add pictures, videos, code, visualizations, explanations. Use https://quarto.org to find other Markdown constructs ( tabs , asides, marginal content…) and complete your post.

4. In your Terminal, run quarto renderto update your _site and _freeze folders.

5. In your Terminal run quarto preview to check if your new post previews properly.

6. In your Git pane, you will see a list of changed files. Click on the Commit button, type in a commit message like Added new post on <date>, and then click Commit.

7. In the Git pane, click on the Push button to push your changes to Github.

8. In your browser, head off to your Github repo and check if the new post is there.

9. In your browser, head off to your Netlify site URL. You should see your new post there, in the list of posts.

10. Using GUI for git commit and push: Instead of using the Terminal, or the Git pane in Rstudio, there is a better way. This is a GUI, and one can see the files, the history of commits/pushes, the commit messages, revert back to a point in history, make brances…all that visually, without some tough-looking git commands:

    • So, install a git client, such as Gitkraken.
    • It offers a ready prompt to log in with Github, accept that, filling in ID and password.
    • Open File ->New tab -> Browse for Repo and browse to your Blog project folder (which is what you open in RStudio)
    • You will a list of previous commits, and a bunch of new edited / changed files which are default labelled WIP. (Work in Progress, peasants)
    • Click on Stage All and type in a memorable commit message in the box below at right.
    • The WIP will be replaced by your commit message.
    • Once staging is done, hit the Push button on the main tool bar.
    • After Gitkraken is done, a brief popup will show stating push was successful.
    • Your website should be updated in a few minutes.

Yeah, peasants, you’re welcome as always.

Figure 5: Gitkraken Window

8 Workflow Diagram

9 References

1. https://jcoliver.github.io/learn-r/010-github.html
2. https://info5940.infosci.cornell.edu/setup/git/git-configure/
3. https://posit-conf-2024.github.io/quarto-websites/
4. Alice Bartlett. Git for Humans https://speakerdeck.com/alicebartlett/git-for-humans