Leet School

{module 2}

Putting a page online

How the web works, and your tools20 min read

What you will be able to do

  • Make a repository on GitHub's website and upload a page to it, with a commit message that says what changed.
  • Turn on GitHub Pages and find the address of the live page.
  • Change the live page by uploading a new version, and send the link with a note that says what to look at.

Why it matters

Havana Guitar Repair fixes guitars in Havana, Cuba. Ernesto Valdés, the owner, had a page with his prices, made by a friend. It lived as a file on Ernesto's laptop. To show a customer, he sent the file as an attachment. On some phones it opened as a page. On others it opened as text full of tags, or not at all. Each time a price changed, the files on people's phones were out of date.

A page on your own computer has an address that starts with file://. Only your computer can open it. To let anyone open it, the page must sit on a server, with an address that starts with https://. This lesson puts a page there, using only your browser.

The idea

A repository and a commit

In the orientation project you made a repository on GitHub and edited its README. Here is what those words mean.

A repository is a folder for one project on GitHub. It holds the project's files and remembers every version of them.

A commit is one saved change to the files in a repository. Each commit records what changed, who made the change, when, and a short commit message that says what the change was. On GitHub's website, every upload and every edit you save is one commit. The list of commits is the history of the project.

A good commit message says what changed, in a few words that start with a verb: "Add the opening hours", "Raise the price of new strings to $18". A message such as "update" tells the next reader nothing.

GitHub Pages

GitHub Pages takes the files in a repository and serves them as a website. A server sends your page to anyone who asks for its address. It costs nothing for a public repository on a free account. The address has this form:

https://your-username.github.io/your-repository/

When an address ends with a folder name and /, the server sends the file called index.html in that folder. So your page must be called exactly index.html, in lower case, at the top level of the repository.

GitHub's rules say that Pages is not for running an online business, a shop, or any site that is mainly there to sell. The pages in this course are practice pages, which the rules allow. Pages also has limits: a site may be at most 1 GB, and a file uploaded through the website at most 25 MiB. Your pages are far smaller.

Worked example

Here is Ernesto's page. Make a folder havana in free-track, and save this in it as index.html:

index.html
<h1>Havana Guitar Repair</h1>
<p>New strings, repairs and set-ups for acoustic and electric guitars.</p>
<h2>Prices</h2>
<p>New strings, fitted: $15</p>
<p>A full set-up: $40</p>
<p>Other repairs: bring the guitar in and we will give you a price.</p>
<h2>Opening hours</h2>
<p>Tuesday to Saturday, 10:00 to 18:00.</p>

Open it in your browser and check it before you publish anything. This is the text it shows:

Output
Havana Guitar Repair

New strings, repairs and set-ups for acoustic and electric guitars.

Prices

New strings, fitted: $15

A full set-up: $40

Other repairs: bring the guitar in and we will give you a price.

Opening hours

Tuesday to Saturday, 10:00 to 18:00.

The rest happens on GitHub's website. Sign in first.

Step 1: Make the repository

  1. In the upper-right corner of any GitHub page, click the plus sign (Create something new), then New repository.
  2. Leave Owner as your own account. In Repository name, type havana-guitars. A name may use letters, digits, hyphens, full stops and underscores, with no spaces.
  3. Choose Public. A free account can publish Pages only from a public repository.
  4. Turn Add README to On.
  5. Click Create repository.

GitHub opens the repository's page. Creating the README was its first commit.

Step 2: Upload the page

  1. Above the list of files, click Add file, then Upload files.
  2. Drag index.html from your folder onto the page, or click choose your files and select it. Upload the file itself, not the havana folder.
  3. In the Commit message field, type Add the first version of the page.
  4. Below the message, keep the choice that commits directly to the main branch. A branch is a separate line of work, which teams use and you do not need yet.
  5. Click Commit changes. Some of GitHub's help pages call this button Propose changes.

The list of files now shows index.html and README.md.

Step 3: Turn on GitHub Pages

  1. Under the repository's name, click Settings. If you cannot see it, open the ... menu and click Settings there.
  2. In the sidebar, in the section "Code, planning, and automation", click Pages.
  3. Under "Build and deployment", under "Source", select Deploy from a branch.
  4. In the branch menu, select main. Leave the folder menu at /(root). Click Save.

Step 4: Find the live address

It can take up to 10 minutes for the site to be published. Wait a minute or two, then reload the Pages settings. When the site is ready, the page shows its address and a Visit site button. Click it. Your page opens at an address like this:

https://your-username.github.io/havana-guitars/

Open the same address on your phone. Anyone with the link can now see the page.

Step 5: Change the page

Ernesto raises the price of new strings to $18. On your computer, change $15 to $18 in index.html, save, and check it in your browser. Then upload it again, as in step 2, with the message Raise the price of new strings to $18. The new file replaces the old one.

Wait a minute and reload the live page. It shows $18. The repository now has three commits: the README, the first page and the new price. To see them, click the clock icon and the word commits above the list of files, on the main page of the repository. Each line is one commit, with its message, its author and when it was made.

Last, edit the README on GitHub with the pencil icon, as in orientation, so that it says what the repository is and gives the live address. That is your fourth commit:

README.md
# Havana Guitar Repair

The web page of Havana Guitar Repair, a guitar workshop in Havana, Cuba.

Live page: https://your-username.github.io/havana-guitars/

## Files

- `index.html` is the page: prices and opening hours.

This is a practice page, made while learning HTML.

Common mistakes

A capital letter in the file name

Your first try was saved as Index.html. On your computer, it opens and looks right:

Output
Havana Guitar Repair

Online, the address shows GitHub's own "404" page. The server looks for index.html, and on GitHub's servers Index.html is a different name. Rename the file on your computer and upload it. Then open Index.html on GitHub, click the ... menu at the top right, and click Delete file, with a message such as Remove the file with the wrong name. Windows and macOS usually treat the two names as the same, which is why the mistake hides until the page is online.

The page is inside a folder

If you uploaded the havana folder, the repository holds havana/index.html, and the address of the site gives a 404. Pages looks for index.html at the top level. Upload the file itself.

The address of the file on GitHub, which starts with https://github.com/, shows the HTML as code. That address is for you. The address that starts with https://your-username.github.io/ shows the page. That one is for customers.

Checking too soon

A new upload can take up to 10 minutes to appear on the live page. If you see the old version, wait, then reload, before you change anything else.

Think it through

Hana, a learner, published a page yesterday. Today the owner asks her to add the words "Closed on public holidays" under the opening hours. She wants the change online, with a history that explains it.

Understand. One new paragraph, on the live page, recorded as one commit with a clear message.

Break down. Change the file. Check it on her computer. Upload it. Check the live page.

Plan. Add one p element below the hours in index.html, save, and reload in the browser. Upload with the message "Add a note that we close on public holidays". Then wait and reload the live address.

Build. She adds the line, saves and checks it in her browser. It looks right. She uploads the file with her message.

Test. The list of files shows her message beside index.html. Two minutes later, the live page shows the new line. As an odd case, she opens the live address on her phone, where the browser may still show the old copy. After a reload, it shows the new line too.

Reflect. Checking on her own computer first meant the live page was right the first time. A clear message means that in a year, she can see when and why the line appeared.

At work

A link alone is not a question. Asking a good question about your work means sending the link and saying what you want the reader to look at. A busy client who receives a bare link glances at it on a phone, says "looks fine", and misses the price that is wrong.

Here is what Ernesto's developer could send:

The page is online: https://your-username.github.io/havana-guitars/

Please open it on your phone and check two things. Are the prices under "Prices" right? Are the opening hours right? If anything is wrong, tell me which line, and I will change it today.

The reader knows where to look, what to check and how to reply. The answer comes back as "the set-up is $45 now", which is something you can act on.

Your tasks

Task 1: Publish Ernesto's page

Follow steps 1 to 4 with your own copy of the page.

You are done when the live address opens the page in your browser and on your phone.

Task 2: Change it

Change one price on your computer, check it, and upload it again with a message that says what changed.

You are done when the live page shows the new price, and the repository has at least three commits, each with a message that starts with a verb.

Task 3: Your own page, online

Publish the page about your own stall from lesson 3 in a new public repository, with a README that says what it is and gives the live address.

You are done when the live page opens, and the README shows the live address.

Write the message you would send to the owner of your business from Task 3, to ask them to check the page.

You are done when your message has the live link, names at least two things to check, and says how to tell you about a mistake.

Recap

  • A repository is a project's folder on GitHub. A commit is one saved change, with a message that says what changed.
  • On GitHub's website, each upload or edit is one commit.
  • GitHub Pages serves index.html, in lower case, from the top of the repository at https://your-username.github.io/your-repository/.
  • A change can take up to 10 minutes to appear. Check on your computer first, then online.
  • Pages is for practice and projects, not for running a business.

Go deeper