This tutorial will guide you through the setup on your local machine for editing just the docs sites for our MDLutoronto project.

Prerequisite

Accounts

1. GitHub account and to be added to the learning object repository under MDLutoronto GitHub Team

   1. Managing GitHub Repo access for students

      TBD: link to the guide for MDL staff to add students to the GitHub repo

Software

1. Windows PowerShell / PowerShell
2. Ruby (install the latest x64 version, e.g. Ruby+Devkit 3.4.6-1 (x64))
3. Git (install the Windows version)
4. GitHub CLI (install the Windows version)
   1. This might need administrative privileges to install
5. VS Code
   1. Recommended VS Code extensions to install:
      1. GitLens: for visually using git within VS Code
      2. Path Autocomplete: for auto-completing file paths when editing markdown files
      3. Code Spell Checker: for spell checking when editing markdown files

Configuration

Connect to GitHub using GitHub CLI in (Windows) PowerShell

You would first need to install GitHub CLI on your windows environment

1. Open a (Windows) PowerShell Terminal

2. Type gh auth login to initialize the login. Press Enter to choose the option, as shown in the code block below

    ? Where do you use GitHub? GitHub.com
    ? What is your preferred protocol for Git operations on this host? HTTPS
    ? Authenticate Git with your GitHub credentials? Yes
    ? How would you like to authenticate GitHub CLI? Login with a web browser
   

   See the GIF below for full steps:

Setting up git user.name and user.email

Note that the user.name and user.email input will be visible publicly. If you have any concerns, consider using the email relay address for commit provided by GitHub.

You can retrieve that email address the under Settings > Emails, after turning on the Keep my email addresses private option

1. Input the following to set your git user name and email. The email should be the same as the one on your GitHub account (or the email relay address provided by GitHub)

    git config --global user.name "Your Name"
    git config --global user.email "Your Email"
   

2. Check your settings with the following command. Look at the user.email and user.name rows. It should show the values you have set above.

    git config --list
   

3. You will also need to setup the authentication for GitHub CLI, using the following command:

    gh auth setup-git
   

Clone the GitHub repository

Here is a sandbox repository to test your access rights/connection: MDLutoronto/just-the-docs-sandbox-stduents After logging in with your account that has access to the MDL GitHub repository, you should be able to view the (private) repository in your web browser.

1. Open a (Windows) PowerShell Terminal

2. Type the command below to clone a GitHub repository; replace the git_link with the intended GitHub repository link

    gh repo clone $git_link
   

   For example, if you want to clone the sandbox repository above (with the .git link https://github.com/MDLutoronto/just-the-docs-sandbox-students.git), you will input

    gh repo clone https://github.com/MDLutoronto/just-the-docs-sandbox-students.git
   

   Tip

   After copying something, you can right-click on the terminal to paste it.

   

Enter the repository directory

1. Once you have cloned the repository, type cd $directory_name to change the directory (cd) of the terminal to the repository directory.

   The directory_name by default is the repository name. As for the example above, it is just-the-docs-sandbox-students

   Tip

   To utilize the auto-complete function (avoid typing the long string), type a few characters and press Tab to let the terminal finish it.

   

   You should see the prompt in the terminal changed to PS H:\just-the-docs-sandbox-students> with the above example

2. Type code . in the terminal to initialize the VS Code for this repository directory.

To preview the website

1. Run bundle install to install the necessary files to start the preview server

    bundle install
   

   

2. Run the following command to start the Jekyll server with live reload enabled

    bundle exec jekyll serve --livereload
   

   

   Once you see the following message in the terminal, you may access the preview pages in your preferred web browser via http://127.0.0.1:4000 (or whatever address the terminal shows after the Server address line)

    ...
    You can add fiddle to your Gemfile or gemspec to silence this warning.
    LiveReload address: http://127.0.0.1:35729
        Server address: http://127.0.0.1:4000
    Server running... press ctrl-c to stop.