GitHub Pages for Beginners: Publish One Page
GitHub Pages lets you publish a web page for free from a GitHub repository, and you can do the whole process in your browser without using the command line. You create an account, create a repository, upload an index.html file, switch on Pages in the settings, and wait a minute or two for the site to appear at an address you can share.
Menus and wording on the site change from time to time, so if a label differs from what is written here, look for the closest match.
What you need
You need an index.html file that you have already tested on your own computer, an email address for the account, and a few minutes. You do not need to install anything. If you built the page with an AI assistant, make sure it is a single self-contained file, or that any images and scripts are in the same folder.
Create an account and a repository
Go to the GitHub website and create a free account. Choose a username with care, since it becomes part of your default address. A short, plain username is easier to share.
Next, create a repository, which is a project folder stored on GitHub:
- Click the button to create a new repository.
- Give it a name, such as
tip-calculator. Use lowercase letters and hyphens. - Set it to Public. Free Pages normally requires a public repository, though the details depend on your plan.
- Tick the option to add a README file, which makes setup simpler.
- Create the repository.
The repository name becomes part of your page’s address, so choose something you are happy to see in a link.
Upload your file
Inside the new repository, find the option to add a file and choose upload. Drag your index.html into the window, along with any image or script files your page needs. Keep the same folder structure you used on your computer.
Scroll down and write a short note, called a commit message, such as “Add first version.” Then confirm the upload. The file now appears in the list. Check that the name is exactly index.html, in lowercase.
Turn on Pages
Open the repository’s Settings, and look for Pages in the sidebar. Under the section that asks where to deploy from, choose to deploy from a branch, select the main branch, and choose the root folder. Save.
After a short wait, a message should appear at the top of the Pages section with your site’s address. It usually looks like https://yourname.github.io/tip-calculator/. The first publish may take a couple of minutes, so refresh the settings page if nothing appears right away.
Check the live page
Open the address on your computer and on your phone. Test every feature as you did locally. Common problems include:
- A 404 page. Wait a few minutes, confirm the file is named
index.htmland sits in the root of the repository, and check that Pages is pointing at the right branch. - Missing images or styles. Links may be wrong. Use relative paths such as
style.css, not/style.css, because your site lives in a subfolder of the address. - Old content. Browsers cache pages. Refresh with a hard reload, or open the page in a private window.
If you cannot find the cause, copy the address and the error you see into your AI assistant and ask for help, along with a description of your folder structure.
Update the page later
To change the page, open the file in the repository, click the pencil icon to edit it, paste in the new content, and commit the change. You can also upload a new file with the same name to replace the old one. The site updates in a minute or two.
Each change is recorded in the repository history, which means you can see earlier versions and restore one if a mistake slips in. This history is one of the reasons people use GitHub Pages instead of simple uploads.
Be careful what you publish
A public repository is visible to everyone, including the history of every file. Never upload passwords, API keys or private data, even briefly, because removing them later does not erase them from the history. If you accidentally upload a secret, treat it as exposed, and replace it with a new one from the service that issued it.
Also remember that Pages serves only static files. It cannot run code on a server or hold a private database.
Using a custom domain later
If you want your own address later, Pages supports custom domains. You add the domain in the Pages settings, then create the DNS records your registrar needs, following GitHub’s current instructions. A file may be added to your repository to record the domain. Once DNS has spread, you can enable the HTTPS option in the settings.
You do not have to do this now. Many small tools live happily at the default address for a long time. Keep the repository name short and clear, since renaming it later changes the default address and breaks links you have already shared. If you are unsure, pick a name you would be glad to see in a link a year from now.
If the page does not update after you commit a change, check the Actions or deployment status in the repository, which usually shows whether the publishing step is still running or has failed. A failure message there is the same kind of text you would paste to an assistant, so copy it exactly and ask for an explanation. Most first-time problems are small, such as a wrong branch name or a file placed in a subfolder, and they are quick to correct once you can see the message.
Next steps
Create the repository, upload one tested page, and turn on Pages. Open the address on your phone, then make a small edit, such as changing the heading, and confirm it appears online after a short wait. Write the address and the date in your notes file. If you later want your own domain name, see our guide on connecting a custom domain.