GitHub

1 Create a GitHub account

Go to the GitHub website, available at https://github.com/

GitHub landing page

Enter your email

Set your username and password (Please choose something that you can remember)

Solve the CAPTCHA and submit

2 Install GitHub Desktop

https://desktop.github.com/

GitHub desktop landing page

Once the installer is downloaded, follow the installation instruction. Sign in to your GitHub account

3 Repositories managment

The GitHub repositories are the folders containing the R Project:

3.1 Create new repository

Create a new repository that does not exist

This initializes a new GitHub repository, where you can provide different information concerning its characteristics

Create a new repository that does exist

3.2 Add existing repository

Add an existing repository that does exist

3.3 Publish the repositories

Once a repository is added (either by adding an existing one or creating a new one), it can be published and made available online for other people:

Publish button

If you want your repository to be found by other users, remove the flag from the “Keep this code private”:

Define the publication policies

3.3.1 commit + push

Everything is ready for the commitment.

  1. Select specific files and commit them. The commit message is mandatory! It is useful for your future self, just to remember the changes you made, when and possibly why.

Select & Commit
  1. The changes must be pushed to GitHub:

Select & Commit
  1. Check whether the changes are live on GitHub:

Check Commit

3.3.2 Licenses

Anyone can use, modify, distribute, and commercialize the software, provided that the original copyright notice and license text are included

Anyone can use, modify, and distribute the software. Any derivative work or redistributed version must be released under the same GPL license and with source code available.

Summarizing the differences between the types of licences:

MIT GNU GPL
Can be used in proprietary software Derivative works must remain open source
Minimal restrictions Requires source code disclosure upon redistribution
Maximizes flexibility and adoption Ensures openness is preserved

4 GitHub pages

The code is shared online, but it cannot be seen as a document, but only as a raw html code.

GitHub pages allows for hosting personal websites on the personal GitHub profiles, such as the html documents are rendered as document and not as code.

Each repository can be set to host the GitHub pages by opening the settings page of the repository and navigating to the Pages section:

GitHub pages settings

The main setting for the GitHub pages regards the deployment.

The main branch must be selected, and make sure that the folder for the deployment is set to root.

This is to check whether the pages are actually active:

Instead of the green tick, you might see a yellow dot. It works as well!

GitHub pages is on!

To transform your pages in an actual website, you need a functioning url:

The red circle indicates the settings to be changed. The green rectangle indicates that the GitHub pages are online

Flag the option for setting the GitHub pages as default website option

Now you have a working website!

As you can see, the index file has been taken as the default landing page of your website (Figure 1).

Figure 1: Running website with default index page

This means that whatever changes you do in you index file, they will be reflected on your website landing page if and only if you commit & push the local changes to GitHub, following the flow

flowchart TD

    A[Edit index.qmd]
    B[Render Quarto Project]
    C{Render successful?}
    D[Fix errors]
    E[Review website locally]
    F[Open GitHub Desktop]
    G[Review changes]
    H[Commit changes]
    I[Push to GitHub]
    J[Repository updated]
    K[Website updated]

    A --> B
    B --> C

    C -->|No| D
    D --> B

    C -->|Yes| E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J
    J --> K

This flow applies to any document you modify locally. In other words, to see the changes that you do locally online, you have to commit them and push them through GitHub Desktop.