GitHub Portfolios

This is the STEM extension version of the documentation portfolio.

What is GitHub?#

GitHub is the industry standard for sharing code and documentation. It is a platform that allows programmers to share their work, work collaboratively, and keep track of all of the changes they’ve made. GitHub has a lot of very advanced features that you may use one day if you’re interested in STEM. For now, we’ll just get started on making one of the simplier things on GitHub: a documentation page.

Make a GitHub account#

Skip this if you already have one. Use the account you have rather than making a second.

1. Go to github.com/signup.

2. Sign up with a personal email address. It cannot be your TDSB email.

3. Pick a username you would be happy showing an employer later down the line. This is an account that might be useful to you if you’re looking to go into STEM after high school. Avoid using your full name.

4. Enter the verification code GitHub emails you.

Tell me your username, then accept the invitation#

Your portfolio is something called a repository, which is just a folder of files that lives on a website called GitHub, which is a platform developed to share code and documentation. Your portfolio will be created in a coding language called HTML, but thankfully you are not building it from scratch, and you don’t need to learn any code to make it. You will be provided with a template that converts a special kind of text document, called a Markdown file into HTML for you.

1. Send me an email with the name of your account. I will create your repository.

2. You should get an email from GitHub inviting you to a repository called something like portfolio-priya-g. Click View invitation, then Accept invitation.

   

   

3. You are now looking at your own portfolio. Bookmark it. This is the one link you need all year.

   

Your site is already switched on, so there is nothing to configure. The address is on the right-hand side of this page under Deployments, and in Settings, then Pages. Bookmark that too.

Put your name on it#

1. Go back to the Code tab and click on _config.yml.

   

2. Click the pencil icon at the top right.

   

3. Change the first two lines to your own name and course code. First name only, do not include your last name.

   Grade	Course code
   9	TAS1O
   10	TAS2O
   11	TEJ3M
   12	TEJ4M

4. Click the green Commit changes button, type a short message saying what you changed, and leave Commit directly to the main branch selected.

   

5. Click Commit changes again.

Committing is what you do to save a file on GitHub, it does not happen automatically. The neat thing is that every commit is kept, so if you ever commit something that breaks your site, you can just revert your changes back to a previous commit, so experiment freely.

Check that it worked#

1. Click the Actions tab at the top of your repository.

2. Look at the entry at the top of the list. A yellow dot means it is still building, so wait a minute and refresh. A green tick means your site is up to date.

3. Open your site address. The URL should be mistermills-tech.github.io/{your-username}. You should see your own name at the top of the site if it updated.

   

If you get a red X instead, click it and then click the failed step to read the error. It is nearly always the block of dashes at the top of a page, or a tab character in _config.yml. Fix the file, commit again, and it rebuilds on its own. Your old site stays up the whole time.

Adding Content to Your Pages#

Open the front page of your repository, or click the “Code” tab if you’re lost. Navigate to your about-me.md and click edit. We are going to create a page where your teacher and your peers can learn more about you and your learning process.

How markdown works#

Markdown is plain text with a few punctuation marks that mean something. You type the marks, the site turns them into formatting when it builds. Nothing to install, no buttons to learn, and the file still reads perfectly well as text if the formatting ever goes away.

Two rules cover most of the mistakes people make on their first day:

• Blank lines separate paragraphs. Two lines of writing with no blank line between them get joined into one paragraph. If you want a gap, leave a blank line.
• The marks have to touch the word. **bold** works. ** bold ** does not, and you will see the asterisks on your published site.

Open the file#

1. On the front page of your repository, click about-me.md in the file list.

2. Click the pencil icon at the top right to start editing.

3. At the very top of the file is a block of dashes with a line or two between them. Leave it exactly as it is. It tells the site what to call the page and where to put it in the menu. Everything you write goes underneath it.

---
title: About Me
nav_order: 2
---

4. Above the editing box are two tabs, Edit and Preview. Preview shows you the formatted version. Click between the two as you work, rather than committing and hoping.

   

Write your introduction#

1. Write one short sentence introducing yourself: your name, and what school you go to or came from. Put your name in italics by wrapping it in single asterisks.

Hi, I'm *Priya*, a Grade 9 student in TAS1O.

2. Leave a blank line, then write two or three sentences about yourself: your favourite things to do, your hobbies, what you want out of this course. Bold three words that either define you best or describe an activity you enjoy. Bold is two asterisks each side.

I spend most of my free time **skateboarding** or taking apart old electronics
to see what is inside. I am the person my family calls when the printer stops
working, so I am fairly experienced with **fixing things**. This year I want to
learn more about **soldering**.

3. Leave another blank line, then add a heading and a short list under it. Use it for what you are already good at, or what you want to learn this year. A heading is two hashes and a space. A bullet is a hyphen and a space, one per line.

## What I want to learn

- Soldering without burning the bench
- Reading a technical drawing
- Making something that actually turns on

4. Click Preview. Your asterisks and hyphens should have disappeared and left formatting behind. If you can still see the marks themselves, there is a space between a mark and its word, or one of them is missing its pair.

Save it#

Nothing on GitHub saves by itself. This is the step people forget.

1. Click the green Commit changes button at the top right.

2. Type a short message saying what you did, like wrote my about me page. This isn’t going to break your site if you don’t do it, but it’s a good thing to get in the habit of.

3. Leave Commit directly to the main branch selected, then click Commit changes.

Add a photo#

Find a photo you think represents you. It does not have to be a photo of you, though you are welcome to use one.

Uploading images takes a few more steps than what you might be used to. The file needs to go into your repository first, and then you write a line that points at it. Before you begin, make sure the image you want is saved on your computer. If it is an image on a website, right click on it and click “Save images as…” and then save it to a familiar location.

1. Rename the file on your own computer before you upload it. Lowercase letters, hyphens instead of spaces, and keep the .jpg or .png on the end. You can rename by right clicking > Rename or selecting the file and pressing F2 on your keyboard.

   Bad file names	Good file names
   IMG_4471.JPG	skate-park.jpg
   My Photo (1).png	my-photo.png

2. Go to the Code tab and click into the images folder.

   

3. Click Add file, then Upload files, and drag your photo into the box.

   

4. Scroll down, type a message like added my about me photo, and click Commit changes. Your photo is in the repository now, but nothing shows it yet.

5. Open about-me.md again and click the pencil icon.

6. On a line of its own, with a blank line above it, write the image line. Change the words in the square brackets to describe your photo, and change the filename at the end to yours.

![A skate park at sunset with my board leaning on the rail.]({{ site.baseurl }}/images/skate-park.jpg)

Four parts, and all four matter:

7. Commit the change the same way you did before.

Check it the way I will#

1. Click the Actions tab and wait for the green tick beside your most recent commit.

2. Open your site address, go to your About Me page, and read it back. Paste the address into a private or incognito window if you want to see exactly what everybody else sees.

3. If the photo is missing, the filename in your image line does not match the file you uploaded, nine times out of ten. Open the images folder and compare the two character for character. Skate-Park.JPG and skate-park.jpg are different files as far as the server is concerned, even though Windows treats them as the same.

The rest of your pages#

Your Journal, Project 1, Project 2 and Culminating pages are already in the file list. You do not need to create them. When you start a project, open that page, click the pencil, and write in it exactly the way you just did here.

Review the README on the front page of your repository for more details on how to format.

Copy the published link and add it to the class spreadsheet.

Sign-off#

• Site and URL named with my name and the course code
• A home page, an About Me page, Journal page, Project 1 page, Project 2 page, and Culminating Page
• In my About Me page, filled out using markdown with text and a photo
• Check to see if the GitHub action published the site (green checkmark)
• Link added to the spreadsheet