How to Publish a Free Static Website With GitHub Pages
Build a simple HTML and CSS portfolio on GitHub Pages for free, enable HTTPS and understand static-hosting limits.
Before you begin
A small portfolio, project documentation site or personal résumé usually does not need a full application server. GitHub Pages hosts static website files from a GitHub repository and provides an address under github.io. GitHub's official documentation confirms Pages can be used from public repositories on GitHub Free. There are important limits: Pages is not a general-purpose backend, public repositories expose their source files and custom domains may require buying or managing a separate domain name.
1Choose the right type of GitHub Pages site
GitHub distinguishes user or organization sites from project sites. For a personal main site, the official quickstart uses a repository named username.github.io, replacing username with the GitHub username. Project documentation may instead live under a repository-specific path. Begin with the official GitHub Pages quickstart and check the repository visibility supported by your GitHub plan. On GitHub Free, Pages is available in public repositories; do not assume a private repo can be used without eligibility.
2Create a tiny website locally
Make an index.html file with a clear page title, heading, short introduction and contact link. Add a styles.css file for typography, colors and responsive spacing, and link it from the HTML head. Use semantic heading elements and descriptive links. Test both files in a desktop or mobile browser before uploading them. Avoid starting with a downloaded template whose license you have not read, and keep large video files off a simple static page unless you understand bandwidth and performance considerations.
3Create the repository and upload files
Sign in at github.com, create the correctly named repository and add the website files to its main branch. You can use the website's file upload interface or ordinary Git commands, depending on your comfort level. Ensure that index.html is at the location expected by the chosen publishing source. Review the repository's contents before making it public, especially .env files, exported databases, configuration files or screenshots of private information. Deleting a secret later may not remove it from repository history.
4Enable GitHub Pages through repository settings
Open the repository, choose Settings, Pages, and configure the publishing source as documented in GitHub's current quickstart. For a branch-based site, select the expected branch and directory, then save. Pages deployment and DNS changes may take time to become visible. Return to the Pages settings for the published URL and visit it in a private browser window. If you receive a 404 response, confirm the repository name, index.html location and publishing branch before changing multiple settings.
5Check links, mobile layout and HTTPS
Open the published github.io URL on a phone and computer. Verify that navigation works, images load and the page remains readable on a narrow screen. Relative links are often safer for project sites because the published path may contain the repository name. GitHub Pages offers HTTPS for supported hosting configurations; verify the secure connection and follow official instructions for custom domains if needed. A custom domain is optional and its registration normally has a separate price.
6Understand what Pages cannot safely do
GitHub Pages serves static assets and can support static-site generators, but does not provide your own traditional server-side PHP, Python or persistent SQL backend. A public web form needs a suitable external form handler or application service, with its own privacy and cost considerations. Do not use a public repo to hide API credentials in JavaScript: visitors can inspect them. For more complex applications or commercial transactions, use a properly secured application platform.
Frequently asked questions
Can I publish a website with GitHub Pages without buying hosting?
Yes. The documented public-repository workflow is available on GitHub Free, subject to service limits and acceptable-use rules.
Can my HTML site secretly store a paid API key in browser JavaScript?
No. Static client-side scripts and bundled files are visible to visitors and are not safe places for private keys.
Official sources and further reading
Interface labels, availability and policies may change. Confirm current details with the relevant service before taking action.