Publishing on GitHub Pages

The site works on your computer, and nobody else can see it. Publishing means putting its files on a server that is always on and reachable from anywhere, at an address you can send to people. For a site made of plain HTML, CSS and JavaScript, that can cost nothing. GitHub Pages is a free hosting service from GitHub, a website where people store and share code, and it serves exactly this kind of site. You can publish without learning any new tool: everything happens in the browser.

Think of moving a play from the rehearsal room to a theatre. The show is the same: the same actors, the same lines. What changes is that the doors are open and the address is on the posters. Some things that never mattered in rehearsal suddenly do, such as whether the scenery fits through the theatre's doors. The rest of this page is about both halves: opening the doors, and the few things that do not fit.

What Is Static Hosting?

A static host is a server that sends your files exactly as they are. When a browser asks for projects.html, the server finds that file and sends it back, unchanged. It runs none of your code; all of your JavaScript still runs in the visitor's browser, as it did on your computer.

That is all this site needs. It is also why the contact form in Chapter 10 ended the way it did: a static host has no program of yours waiting to receive the form's data, so the form could only be honest about it. The day a site needs to store data or send email, it needs a backend, which is the subject of the Backend Deep Dive course.

How Do You Publish the Site?

There are four steps, and each happens on GitHub's website. GitHub changes its screens from time to time, so if a button has moved, look for the same words nearby.

First, create a GitHub account at github.com. This is something you do yourself, with your own email address and password; the free account is enough. Choose the username with care, because it becomes part of your site's address.

Second, create a repository, GitHub's name for a project folder stored on its servers, as Chapter 11 said. Use the plus button at the top right of any GitHub page and choose New repository. Name it my-site, set it to Public, and create it. A free account can publish only public repositories, which costs you nothing here: every file of a website is readable by its visitors anyway, as Chapter 1 said.

Third, upload the files. In the new repository, choose Add file, then Upload files, or follow the link to upload an existing file if the repository is empty. Open your my-site folder on your computer and drag its contents onto the page: the three HTML files and the css, js, data and images folders. Drag what is inside the folder, not the folder itself, or everything will end up one level too deep. Then press the green button at the bottom of the page to save the upload; if the page offers a choice of branch, keep the one that saves straight to main.

Fourth, turn on Pages. Open the repository's Settings tab and choose Pages in the list on the left. Under Build and deployment, set the source to Deploy from a branch, choose the branch called main and the folder marked with a single slash, which means the top of the repository, and press Save. GitHub builds the site in the background; it can take a few minutes. When it is ready, the same Pages screen shows the address and a Visit site button.

Your my-site folderon your computer

→

Upload to a repositorythrough the web page

→

Turn on Pagesone setting

→

Live on the webat a github.io address

What Is the Address, and Why HTTPS?

The site's address is your username, then .github.io, then the repository's name: for a user called username, https://username.github.io/my-site/. An address that ends at a folder is answered with that folder's index.html, so this opens the Home page, and the other pages follow as projects.html and contact.html after the last slash. If you name a repository exactly username.github.io, with your own username, its site is served at the shorter address with nothing after the domain.

GitHub serves every site on a github.io address over HTTPS automatically. HTTPS encrypts the page on its way to the visitor, so nobody on the same café network or anywhere along the route can read it or quietly change it. Browsers also mark plain HTTP pages as not secure, and some features refuse to work without HTTPS at all.

Open the address on your phone. It is the first time the site has run on a device that is not your computer, which makes it the real test of Chapter 5's responsive work.

What Breaks Only After Publishing?

A site that worked perfectly on your computer can arrive with a missing stylesheet or a broken link. Almost always the cause is one of three kinds of path, and the Network panel finds each one: open it on the published site, reload, and look for rows in red with the status 404, meaning not found.

The first is capital letters. The file systems that Windows and macOS use by default treat Projects.html and projects.html as the same file, so a link with the wrong capital works at home. GitHub's servers treat them as two different names, and the link breaks. This is why Chapter 1 asked for lowercase file names from the start.

The second is a path that points at your own computer, such as one beginning with file: or with a drive letter. It worked because the file was there; no visitor has your hard drive.

The third is subtler. A path that begins with a slash means "start from the very top of the website". On your computer, Live Preview served my-site at the top, so that worked. On GitHub Pages, the top is username.github.io, and your site lives one folder down, inside my-site.

<!-- Broken once published: looks for username.github.io/css/style.css -->
<link rel="stylesheet" href="/css/style.css">

<!-- Works everywhere: relative to the page, as Chapter 2 taught -->
<link rel="stylesheet" href="css/style.css">

With the leading slash, the published page asks for a stylesheet at the top of the whole github.io address, finds nothing there, and appears in the browser's plain default style: black text on white, no layout. The Network panel shows style.css in red with a 404. Without the slash, the path starts from the page's own folder, and the styles return. The relative paths from Chapter 2 are the reason the whole folder can move to a server unchanged.

What Comes Next?

To change the site, edit the files on your computer, then upload the changed ones again the same way; uploading a file with the same name replaces the old one. It works, and it gets tedious. The professional way to update a repository is Git, a tool that records every version of your files and sends only the changes. The Git for Beginners course teaches it from zero, then shows how to connect a folder on your computer to a repository on GitHub like this one.

You can also give the site your own address, such as yourname.com, by buying a domain name from a registrar, pointing it at GitHub in the registrar's settings, and entering it in the same Pages settings. And GitHub Pages is only one static host among several. The others work the same way: you give them the folder, and they give you an address.