How to Set Up GitHub Pages for Your Portfolio in 5 Minutes

GitHub Pages is one of the most accessible and powerful tools available for hosting a professional portfolio website at absolutely no cost. With GitHub Pages, you can deploy a static website directly from your GitHub repository, with built-in support for custom domains, SSL certificates, and continuous deployment. Setting up a portfolio site takes only a few minutes, and once configured, every push to your repository automatically updates your live site. This guide walks you through the entire process from start to finish.

What You Need Before Starting

To set up GitHub Pages, you need a GitHub account and a repository where your portfolio files will live. If you do not already have a GitHub account, creating one is free and takes less than a minute. You also need some HTML files for your portfolio. You can write these yourself, use a static site generator like Jekyll or Hugo, or start with a pre-built template. The beauty of GitHub Pages is that it works with plain HTML, CSS, and JavaScript, so no complex frameworks or build tools are required.

Your portfolio should include at minimum an index.html file that serves as the landing page for your site. Additional pages can include about, projects, resume, and contact sections. You can organize these as separate HTML files or use a single-page application pattern depending on your preference. For a portfolio that looks professional and represents your skills well, invest time in clean design, responsive layout, and fast loading performance before deploying.

While not strictly required, a custom domain makes your portfolio look more professional. Custom domains can be purchased from domain registrars like Namecheap, Google Domains, or Cloudflare for around ten to fifteen dollars per year. GitHub Pages supports custom domains with automatic HTTPS certificate provisioning through Let's Encrypt, so you get professional-grade security at no additional cost. Even without a custom domain, your site will be available at username.github.io, which is perfectly acceptable for many purposes.

Understanding the basics of Git version control is helpful but not essential for the initial setup. You can upload your files directly through the GitHub web interface if you prefer. However, using Git to manage your portfolio files gives you version history, the ability to work from multiple computers, and the foundation for more advanced workflows in the future. The commitment to version control also signals professionalism to employers who review your portfolio repository.

Step 1: Create Your Repository

Log into your GitHub account and click the plus icon in the top right corner, then select New repository. For a personal portfolio site at the username.github.io address, name your repository exactly username.github.io, replacing username with your actual GitHub username. This special naming convention tells GitHub that this repository should be served as a GitHub Pages site at the root domain. If you name it anything else, your site will be served from a subdirectory instead.

You can choose to initialize the repository with a README file, which provides a place to document your portfolio project. Whether you add a .gitignore file depends on the technologies you are using. For a simple HTML portfolio, you likely do not need one. Choose a license for your repository if you want others to be able to use your portfolio code as a reference or template. The MIT license is a common choice for portfolio repositories.

Once the repository is created, you have several options for adding your files. You can clone the repository to your local machine using Git, add your files, commit them, and push back to GitHub. Alternatively, you can use the Add file button in the GitHub web interface to upload files directly. For a simple portfolio with just a few files, the web interface works perfectly fine. For more complex sites with many files, using Git locally is more efficient.

After creating the repository, immediately go to the repository settings to verify that GitHub Pages is configured correctly. Scroll down to the Pages section in the settings sidebar. You should see that your site has been published and is available at a URL. The default settings usually work correctly for the username.github.io naming convention, but it is good practice to verify and understand the configuration options available.

Step 2: Add Your Portfolio Files

Create your index.html file first, as this is the default page that visitors see when they access your portfolio URL. Your index.html should be a complete HTML document with proper structure including doctype declaration, head section with meta tags for SEO, and a body that contains your portfolio content. Include your name, a brief professional summary, links to your key projects, and contact information. Make sure the HTML validates correctly to avoid display issues across different browsers.

Organize your portfolio files logically within the repository. Place your main HTML files at the root level for easy access. Create an assets directory to hold CSS files, JavaScript files, images, and other static resources. Use a css subdirectory for stylesheets, a js subdirectory for scripts, and an images subdirectory for photos and screenshots. This organization keeps your repository clean and makes it easy to maintain as your portfolio grows.

Add the projects and work examples that you want to showcase in your portfolio. Each project should have a dedicated section or page that includes a description, technologies used, key challenges you solved, and links to the live demo and source code. Include screenshots or GIFs that show your projects in action. These visual elements make your portfolio more engaging and help visitors understand the quality and scope of your work quickly.

Ensure all file names are lowercase and use hyphens instead of spaces, as this convention avoids issues with case-sensitive operating systems and improves URL readability. Name your files descriptively so that both humans and search engines understand what each page contains. For example, use about.html, projects.html, and contact.html rather than page1.html or random-name.html.

Step 3: Configure GitHub Pages Settings

Navigate to your repository settings and locate the Pages section. Here you can configure how your site is built and deployed. For a simple HTML portfolio, select Deploy from a branch as the source and choose the main branch with the root folder. This configuration tells GitHub to serve the files directly from the root of your repository. If you use a static site generator that builds to a specific folder, you would select that folder instead.

If you have a custom domain, enter it in the Custom domain field in the Pages settings. GitHub will verify your domain ownership by prompting you to add a DNS record. Once verified, GitHub automatically provisions an SSL certificate through Let's Encrypt and enables HTTPS for your domain. This process typically takes a few minutes but can take up to an hour for DNS changes to propagate fully. You can enforce HTTPS-only access with a single checkbox in the settings.

Consider enabling GitHub Pages to build from a specific branch if you want to keep your source files separate from the published files. This pattern is useful when using static site generators. You would keep your source files on one branch and the built output on a gh-pages branch. GitHub Actions can automate the build process so that every push to the source branch triggers a build and deployment to the publishing branch.

Review the settings for your site's visibility. If your repository is public, your GitHub Pages site will be publicly accessible. If your repository is private, GitHub Pages sites require a paid GitHub plan. For portfolio purposes, a public repository is typically preferred since you want potential employers to be able to view your work without authentication restrictions.

Step 4: Add a Custom Domain (Optional but Recommended)

A custom domain transforms your portfolio from a hobby project into a professional presence. Purchase a domain that includes your name or a variation of it, such as yourname.com or yournamedev.com. Many developers use firstname-lastname.com or firstinitiallastname.dev. The dev TLD is particularly popular among developers and signals your profession clearly. Prices range from ten to fifty dollars per year depending on the TLD and registrar.

Once you have purchased your domain, configure its DNS settings to point to GitHub Pages. The recommended approach is to use an apex domain with a CNAME record pointing to your GitHub Pages URL. Alternatively, you can use a subdomain like www.yourname.com. GitHub provides detailed documentation on the specific DNS records required. Your domain registrar's DNS management interface is where you add these records. Propagation can take anywhere from a few minutes to 48 hours.

After configuring DNS, add your custom domain in the GitHub Pages settings as described in the previous step. GitHub will automatically create a commit adding a CNAME file to your repository, which ensures your custom domain persists even if you reset settings. The automatic SSL certificate provisioning through Let's Encrypt typically completes within minutes of domain verification, giving you secure HTTPS access to your portfolio.

Consider the user experience of your domain choice. Short, memorable domains are easier to share in conversation and on printed materials like business cards. Avoid domains that are difficult to spell or that could be confused with other names. Test your domain thoroughly after setup to ensure all pages, links, and resources load correctly through the custom domain.

Step 5: Test and Optimize Your Portfolio

After deployment, thoroughly test your portfolio across different devices, browsers, and screen sizes. Your site should look professional and function correctly on desktop computers, tablets, and smartphones. Pay particular attention to navigation, link functionality, and image display. Use browser developer tools to simulate different devices and identify any layout issues that need correction. A responsive portfolio creates a better impression on the diverse devices that recruiters and hiring managers use.

Test your site's loading speed using tools like Google PageSpeed Insights or Lighthouse. A fast-loading portfolio improves user experience and search engine ranking. Optimize images by compressing them and using appropriate formats like WebP for photographs and PNG for graphics. Minimize CSS and JavaScript files, leverage browser caching, and consider using a content delivery network for global audiences.

Verify that all links on your site work correctly, including external links to your GitHub repositories, LinkedIn profile, and project demos. Broken links create a poor impression and can prevent recruiters from accessing your work. Use a link checker tool or manually click through every link on your site. Pay special attention to links that open in new tabs and ensure they have proper security attributes configured.

Check your site's SEO fundamentals by reviewing your meta tags, heading structure, and content organization. Ensure each page has a unique title tag and meta description that accurately describes its content. Use descriptive heading tags in hierarchical order. Add alt text to all images for accessibility and SEO. Consider adding structured data markup to help search engines understand your portfolio content better.

Maintaining Your GitHub Pages Portfolio

Your portfolio is a living document that should evolve with your career. Plan to review and update it at least quarterly. Add new projects as you complete them, update your skills section as you learn new technologies, and refresh your professional summary to reflect your current career direction. Outdated portfolios can create a negative impression if they show technologies you no longer work with or projects that no longer represent your best work.

Monitor your site's performance and availability using free monitoring services like UptimeRobot or Pingdom. While GitHub Pages has excellent uptime, occasional issues can occur. Monitoring ensures you are aware of problems quickly and can address them before they impact potential employers trying to view your work. Set up notifications for downtime so you can respond promptly.

Consider adding a blog section to your portfolio over time. Writing about technical topics demonstrates expertise, improves your SEO, and gives visitors reasons to return to your site. GitHub Pages works well with static site generators that support blogging functionality. Even occasional posts about projects you have built or technologies you have learned add depth to your portfolio and showcase your communication skills.

Frequently Asked Questions

Is GitHub Pages really free?

Yes, GitHub Pages is completely free for public repositories. You get free hosting, automatic SSL certificates, and support for custom domains at no cost. The only expenses are your domain name registration if you choose to use a custom domain, which typically costs around ten to fifteen dollars per year.

Can I use a custom domain with GitHub Pages?

Yes, GitHub Pages fully supports custom domains with automatic HTTPS certificate provisioning through Let's Encrypt. You can use both apex domains and subdomains. DNS configuration is handled through your domain registrar's settings.

Does GitHub Pages support static site generators like Jekyll or Hugo?

Yes, GitHub Pages has built-in support for Jekyll and can be configured to work with any static site generator. You can either use the automatic build process for Jekyll or use GitHub Actions to build your site with any generator before deploying the output to GitHub Pages.

How often can I update my GitHub Pages site?

There is no limit on how often you can update your site. Every push to your configured branch triggers a new deployment. Updates typically go live within a few minutes of pushing changes to your repository.

Can I use GitHub Pages for a commercial website?

GitHub Pages is intended for personal and project websites, not commercial enterprises. However, using it for a portfolio that showcases your professional work and potentially leads to employment is completely within acceptable use. Review GitHub's Terms of Service for specific restrictions.

What happens if my GitHub account reaches its storage limit?

GitHub Pages repositories have a recommended size limit of 1 GB. If you exceed this limit, GitHub may contact you to reduce the repository size. For most portfolios, this limit is more than sufficient. If needed, you can host large files externally and link to them from your portfolio.

Can I use a framework like React or Vue with GitHub Pages?

Yes, you can deploy applications built with JavaScript frameworks to GitHub Pages. Build your application locally and commit the built output to your repository, or use GitHub Actions to automate the build process. The deployed site will function as a static site regardless of the framework used to build it.