Post Import

Overview

Teaching: 15 min
Exercises: 10 min

Questions

• What other house keeping needs to be done?

Objectives

• Change repository default branch in github

• Access Mana via Open OnDemand

• Start an interactive deskop view

• Setup your Mana SSH key for github

• Clone your repository to Mana and initialize the lesson

Setting up the default branch

Once the repository has been imported into your github account we want to make it simple to be in the right branch when we clone the repository for local editing.

Accessing Mana via Open OnDemand

Now that the repository has the right default branch set, we need to get into an environement that we can use to initialize the lesson repository.

Imported repository still needs initialization

The intial imported repository is missing key files to generate pages on github. The initialization step will create these files, but it requires python

So that everyone is in a common environment, we will use Open OnDemand and connect to a Desktop session on Mana https://mana.its.hawaii.edu

Security

An incognito browser sessions is reocmmended for Open Ondemand so that you can “logout” by closing the browser window.

Setup your Mana SSH key for github

Now that you have a desktop on Mana, open up a terminal. The first step we want to deal with is setting up github with our SSH key so we no longer need to use our password when using git from Mana and our github account. We are looking for your public key on Mana.

cd ~/.ssh
ls id_*.pub

You should see a file named “id_rsa.pub” or “id_ed25519.pub” This file would represent your default SSH key public. We want to copy this content and add it as a SSH key in github

cat ~/.ssh/id_rsa.pub

Copying can be done by just highlighting the text in your terminal so you can paste it into your github SSH & GPG key list. Upper right, click on user icon and go into settings

SSH key security

For security some users like to put a password on SSH keys. On Mana the default key is passwordless, but users can create a different key with a password, just making sure to not overwrite the existing key. Using a non-default key is outside the scope of this tutorial.

Clone your repository to Mana and initialize the lesson

Now that we should have our key setup, with our still open terminal, create a directory on Mana where we can put the cloned respoistory

cd 
mkdir hidsi
cd hidsi

Once in the directory let us get the SSH version of the clone address for our repository and clone it locally.

git clone git@github.com:landcaster/swc-tutorial.git

Once the repository is local, we can now initilize it.

cd ~/hidsi/swc-tutorial
python3 bin/lesson_initialize.py

A few new files should now be present in our repository

git status

Finally, add the new files, commit the changes and push it back to github

git add --all
git commit -m "initialized"
git push

Key Points

Adding content

Overview

Teaching: 0 min
Exercises: 30 min

Questions

• How to do basic modificaitons to a lesson?

• What tool can I use to edit the differnt files?

Objectives

• Learn about the built in github editor or how to edit locally

• Change the lesson title

• Add another episode

• Edit an episode

• Add a an image/figure

Text Editors

Editing the lesson and episodes can take place both directly on github, using the in site editor or locally using a basic text editor or Integrated development environment (IDE) like visual studio.

Editing via github

Viewing a markdown file, yaml file or plain text files is possible on github. When viewing those files, you can even edit them and commit changes all in browser

Visual studio code on Mana

In our session on Mana, visual studio code is installed and can be used to edit files as well as commit changes to github.

Editing files

For any lesson, you will need to provide a correct title (_config.yml) and add and edit episodes with figures.

Directory layout

In case you forget what files and directories do what, you can refer back to the episode on lesson organization

Changing the lesson title and set the email

With your basic lesson it is time to make it unique and less generic. Your first task is to change the title of your lesson and change the contact email address by editing the _config.yml file.

Add a new episode

We need to add a new episode for new lesson content. Create a new file in the _episodes folder called “02-figures.md”.

Copy when you can

I find it easier to copy conent or duplicate files when possible. Why reinvent the wheel if someone has alread done it for me. Instead of a new file, copy/duplicate 01-introduction.md and rename it. Then change the text and remove tags that are needed. Github does not seem to have a duplicate file function, but you can copy the raw contents of a file and paste it into a new file created using the github menu.

Edit your first episode

With a new lesson title it is time to dive into editing an episode. Go into the introductory episode “01-introduction.md” and change the title, add some questions and add some text where it says fix me. Use some styles to add section headers “##” and other style and formatting

Episode 2 needs a figure

Although we have a new episode focused on figures, it lacks what it claims it will have, figures!
Find an image and add it to your repository in the fig directory.
Once it is in the fig directory add it to your second episode.

<a href="{{ page.root }}/fig/10.png">
 <img src="{{ page.root }}/fig/10.png" alt="What am I" />
</a>

Key Points

• Can edit locally or directly on github

• Some styles provided beyond the basics

• Don’t reinvent the wheel, reuse content when possible