Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsAdd one image file for each project, then reference it from that project’s card on your directory page. The important GitHub Pages detail is the image URL: a project site is served below its repository name, so an asset path that works at your computer’s root may fail after publishing. Keep the images in the configured publishing source, use paths that account for the site’s base path, and check the live page.
1. Choose and add a thumbnail for each project
Pick a representative image that helps visitors recognize or understand the project. A screenshot of the project is one option; you can also use another image you have the right to publish. The image itself is not required to be captured in any particular way.
Put the files in the directory GitHub Pages publishes. For example:
project-directory/
index.html
assets/
thumbnails/
project-one.jpg
project-two.png
css/
style.cssThis is an example organization, not a required GitHub Pages layout. GitHub Pages can publish static files from a repository, and the published directory structure is preserved. The exact publishing source depends on how the repository is configured; check GitHub’s documentation on what GitHub Pages is and creating a GitHub Pages site.
#1 Best Overall
2. Add the image to each project card
In a plain HTML directory, put an <img> inside the link for the project. This example assumes the page and assets directory are at the same published level:
<a class="project-card" href="projects/project-one/">
<img src="assets/thumbnails/project-one.jpg"
alt="Screenshot of Project One's dashboard">
<h2>Project One</h2>
</a>Change the image path, destination link, alt text, and project title for each card. Write alt text that briefly describes what the image conveys. If the image communicates no information beyond the adjacent project name, use an empty alt value (alt="") so assistive technology can skip a redundant description. GitHub’s Markdown guidance also explains alt text and image paths in rendered Markdown: GitHub Docs.
3. Make asset paths work on a project site
A GitHub Pages project site is hosted below a repository path, commonly /. If the repository is portfolio, for example, the site may be served below /portfolio. A root-relative image URL such as /assets/thumbnails/project-one.jpg points to the host’s root, not necessarily to /portfolio/assets/thumbnails/project-one.jpg.
Plain HTML
For a simple site where the listing page and assets share a directory level, a relative URL such as assets/thumbnails/project-one.jpg is often the simplest choice. If your page is nested, adjust the relative path to the asset’s actual location. Verify the resolved URL on the published project-site address rather than assuming a path that works locally will work at the host root.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
Jekyll
If the site uses Jekyll, set baseurl to the repository subpath when the site is hosted in a subdirectory, then generate asset URLs with the relative_url filter where the build environment supports it:
<img src="{{ '/assets/thumbnails/project-one.jpg' | relative_url }}"
alt="Screenshot of Project One's dashboard">For a repository site, the configured base URL should account for the repository path. Confirm the filter is available in your Jekyll setup and inspect the generated HTML to ensure the resulting image URL includes the correct path. GitHub’s Jekyll setup guidance covers setting up a GitHub Pages site with Jekyll and configuring baseurl for a subdirectory.
4. If the directory uses Jekyll, keep content and layout separate
Jekyll pages can use front matter and layouts, so you can keep project data separate from the markup that renders the cards. The specific data-file arrangement depends on your existing site and theme; the key is that each project entry provides an image path, descriptive alt text, title, and destination, and the template emits a URL that includes the site base path. GitHub documents Jekyll pages, front matter, layouts, and local preview in its guide to adding content to a GitHub Pages site using Jekyll.
5. Preview, publish, and troubleshoot
- Check the publishing source. Ensure the HTML, generated site files, and thumbnail images are included in the configured publishing source.
- Build or preview the site. If using Jekyll, preview locally using your normal Jekyll workflow and inspect the rendered page. GitHub’s documentation describes local preview; GitHub currently recommends GitHub Actions for deployment.
- Inspect the generated image URL. Open the live project site, inspect the image element, and confirm the final URL includes any repository base path. You can also open the image URL directly.
- Check the browser’s network result. If the image is missing, look for a failed request and compare its URL with the file’s path and capitalization in the repository.
- Image works locally but not on the published project site: the URL may omit the repository base path. Use a suitable relative path or Jekyll’s base-aware URL generation, then check the final URL on the live site.
- Image returns a not-found response: check that it is in the published source, the filename and extension match exactly, and the path is relative to the page or generated with the right base URL.
- Jekyll displays template syntax as text or produces a broken URL: make sure the markup is processed as a Jekyll template and that the site’s configuration and filter support are appropriate.
- Changes do not appear after publishing: confirm the deployment completed and that the changed image and page are part of the configured publishing source.
6. Keep site thumbnails separate from the repository social preview
An in-page thumbnail is an image referenced by your website’s markup and displayed in its project directory. A repository social preview is a separate image setting used when the repository link is shared on social platforms; changing it does not add thumbnails to your website. GitHub’s documentation on customizing a repository social media preview recommends PNG, JPG, or GIF files under 1 MB, at least 640 × 320 pixels, with 1280 × 640 pixels giving the best display. Those are recommendations for the social preview, not mandatory dimensions for in-page thumbnails.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Or skip the browser setup
If you want to create a project screenshot without setting up a browser capture workflow, ScreenshotNeo can return a screenshot through one GET request. Its cleanup options accept cookie and consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses include page-verdict and billing headers. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients.
Example cURL request (replace the URL with the project you want to capture):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request details. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Does GitHub Pages require a particular folder name for thumbnails?
No. The example uses assets/thumbnails/, but you can choose another location as long as the files are included in the configured publishing source and your page references the correct paths.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Are the recommended social-preview dimensions required for project-card images?
No. GitHub’s listed dimensions apply to the repository social preview, not to thumbnails embedded in the site.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
