How to Create Website Thumbnails for a Portfolio Hosted on GitHub Pages in India

To create website thumbnails for a portfolio hosted on GitHub Pages, capture each project page in a browser, crop the screenshot to the part that identifies the project, save it as an image in your portfolio repository, and reference it from the project card. Commit and push the files, then check the published portfolio at desktop and mobile sizes.

This workflow is the same in India as elsewhere: the research found no India-specific GitHub Pages thumbnail requirement. GitHub Pages serves static site files from a repository, so a thumbnail can be stored alongside your HTML, CSS, and JavaScript assets. See GitHub’s Pages overview.

1. Capture a useful project preview

Open the project page in a browser at the viewport size that best represents the design. Use your browser or operating system’s screenshot feature. A full-page screenshot can show a long layout, while a viewport capture usually makes a more recognizable portfolio card. Choose by checking legibility, recognition at small size, file weight, and consistency with the other cards.

1. Open the live project page, or its local development URL if it is not deployed yet.
2. Set a consistent browser viewport for the projects you are capturing.
3. Capture the page. Prefer a representative section with the project’s main visual identity and content.
4. Crop away browser chrome and irrelevant whitespace. Keep the key interface recognizable at the thumbnail’s actual display size.
5. Repeat with the same capture approach for each project so the grid feels consistent.

GitHub’s contributor screenshot guide recommends PNG, static images rather than GIFs, 144 dpi, 750–1000 pixels wide for full-column images, and a file size of 250 KB or less. Those recommendations are for GitHub documentation screenshots; they are not mandatory dimensions for portfolio cards. Export and crop for your own card layout, then inspect the result in the browser.

2. Add the images to your repository

Use a predictable asset directory and descriptive filenames tied to the project. For example:

portfolio/
├── index.html
└── assets/
    ├── images/
    │   ├── weather-dashboard.webp
    │   └── shop-redesign.webp

PNG is a straightforward choice for screenshots. WebP can be useful when you want smaller image files and your target browsers support it. Keep the source or a higher-quality export if you expect to revise the crop later.

3. Reference thumbnails in your portfolio HTML

For a user or organization site at username.github.io, a root-relative path such as /assets/images/weather-dashboard.webp can work when the asset is at the site root. For a project site served under a repository path, a root-relative path points to the account host root, not necessarily the project. A relative path is often safer for a page and its assets deployed together.

<article class="project-card">
  <a href="https://example.com/weather-dashboard">
    <img
      src="assets/images/weather-dashboard.webp"
      alt="Weather dashboard showing a weekly forecast and temperature chart"
      width="960"
      height="600"
      loading="lazy"
    >
    <h2>Weather dashboard</h2>
  </a>
  <p>A responsive forecast interface with a weekly view.</p>
</article>

Replace the example destination and description with the real project. The alt text should describe useful image content, not repeat a filename. Keep the project title and link as meaningful text so the project remains understandable if the image does not load. GitHub’s screenshot guidance likewise asks for alt text that describes the image content and any highlighting; procedural information should not depend on an image alone.

For a Jekyll site, a base URL setting may affect paths on project sites. Review the generated page’s image URL in the browser’s developer tools, and use the correct project path or the generator’s base-URL-aware URL helper where available.

4. Publish and verify on GitHub Pages

1. Commit the HTML and image files to the branch and directory configured for Pages.
2. Push the commit to GitHub.
3. Wait for the Pages build and deployment to finish. GitHub’s quickstart says a push may take up to 10 minutes to publish.
4. Open the live portfolio and inspect each thumbnail at the card’s actual size.
5. Check a narrow viewport, confirm that images load, and verify the link destination and alt text.

User and organization sites use a host such as username.github.io; project sites include the repository path in the default URL. That difference is a common source of broken asset paths. See GitHub’s Pages quickstart and its documentation about Pages publishing. Pages hosts static files; branch publishing uses Jekyll by default, while custom build processes can use GitHub Actions. Server-side PHP, Ruby, or Python is not supported by Pages, but a static image asset needs no server-side processing.

5. Make thumbnails readable and lightweight

• Crop for recognition: show the part of the project visitors need to identify it; a full-page capture may become too small to read in a card.
• Keep a consistent grid: use a consistent aspect ratio and similar visual framing where the designs allow it.
• Size to the layout: avoid serving an unnecessarily huge image to a small card. Use the real card dimensions to choose an export size.
• Preserve useful detail: check text and controls at the rendered card size, especially on a phone.
• Use meaningful alternatives: write concise alt text for informative previews. If an image is purely decorative and the adjacent text already conveys everything, use an empty alt attribute.
• Do not rely on the thumbnail alone: provide project names and descriptions in HTML as well.

There is no universal card dimension established by the cited guidance. Pick dimensions based on your own layout and verify the rendered result rather than treating documentation screenshot sizes as a portfolio standard.

6. Troubleshoot common problems

Symptom	Likely cause	Fix
Image works locally but is broken on the live site	The path assumes the site root, but the project site is under a repository path; or filename capitalization differs.	Inspect the deployed image URL and use a path that includes the project base path or a relative/base-aware URL. Match filename case exactly.
Image returns 404 after a push	The file was not committed to the published branch or directory, the path is misspelled, or deployment has not completed.	Check the repository and Pages publishing source, verify spelling and capitalization, then wait for deployment. GitHub says publishing may take up to 10 minutes.
Thumbnail looks blurry	The source capture is too small for the rendered card or was enlarged during export.	Capture at a larger viewport or use a higher-resolution source, then export to the card’s intended size without enlarging a small crop.
Text is unreadable in the card	The crop includes too much of the page or the card is too small to preserve fine detail.	Crop to the defining area, choose a representative viewport capture, or make the card larger. The preview is a summary, not a replacement for the linked project.
Cards have inconsistent heights or crops	Images use different aspect ratios or the layout does not constrain image presentation.	Choose a consistent export ratio and set a consistent display aspect ratio in CSS; check that the crop remains informative.
Pages build fails after adding images	The asset was added in a way that conflicts with the configured generator or publishing directory.	Review the Pages build log and confirm the image is in the published output/source directory. For custom builds, ensure the workflow copies static assets.

7. Capture thumbnails with ScreenshotNeo

If you have many project pages or want repeatable captures, ScreenshotNeo can return a screenshot from one GET request. Its API supports PNG, JPEG, or WebP output and options such as viewport dimensions, full-page capture, device presets, and retina scale. See the ScreenshotNeo API documentation for parameters and usage.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com/project \
  -o project-thumbnail.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com/project"},
    timeout=90,
)
r.raise_for_status()
open("project-thumbnail.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com/project'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('project-thumbnail.webp', res);

In Node.js environments without Bun.write, use the runtime’s file-writing API to save the response bytes. Keep the API key on a trusted machine or server; do not expose it in public portfolio HTML or client-side JavaScript. For a public static GitHub Pages site, generate the image before deployment and commit the resulting image file.

Or skip the browser setup

ScreenshotNeo captures the project URL in one API call. Cookie banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000 shots.

Sign up for 1,000 free screenshots a month, with no card.

8. Performance, reliability, and cost

For a small portfolio, local static image files are simple to publish and do not require a screenshot service at page-view time. Optimize the exported file and use lazy loading for cards below the fold. For many projects or repeated updates, automated capture can save manual browser work, but generate assets as part of a trusted workflow and publish the finished files with the site. GitHub Pages is static hosting, so a live page cannot run a private API key to capture images on demand.

When using a screenshot API, page rendering time, network requests, and large full-page captures affect how long a capture takes and the resulting file size. Use a stable target URL and appropriate wait behavior, and review the returned image before publishing. ScreenshotNeo states that only clean shots are billed; bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with response headers identifying the page verdict and billing status. Plans listed by ScreenshotNeo are Free: 1,000 shots/month; Starter: $5 for 3,000; Growth: $15 for 15,000; Pro: $39 for 60,000; Scale: $99 for 250,000; Business: $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan. Check the product site for current details before choosing a plan.

Frequently asked questions

Do I need a special screenshot tool in India?

No India-specific tool or GitHub Pages requirement was found for this workflow. A browser capture and static image file are sufficient.

Should each card use a full-page screenshot?

Only if the complete page remains recognizable at the card size. A focused viewport crop often makes a clearer preview; inspect both options in your actual layout.

Can I generate thumbnails in PHP or Python on GitHub Pages?

Pages does not run server-side PHP, Ruby, or Python. You can generate images locally or in a build workflow, then publish the resulting static assets.

What dimensions should I use?

There is no universal portfolio-card size in the cited sources. Choose an aspect ratio and pixel size that fit your design, then check sharpness and readability at the rendered size.